Skip to main content
Version: v5.3

Telemetry readings

Telemetry readings​

A reading is a time-stamped measurement, such as a flow rate at a point in time, recorded against a telemetry individual. A telemetry individual is an individual of a class that descends from the base Telemetry class and is mapped to a NamedTelemetryCollection. For more information, see Collection mapping.

Readings aren't stored on the individual. The Item Service keeps them in the time series of the class's telemetry collection. Each reading names its telemetry individual in _tsMetadata._telItemId.

The readings calls suit simulators, corrections, and agents that send readings a few at a time. For high-volume telemetry, use the Item Service ingestion routes instead. Imports don't load readings.

Readings always use the live version of the ontology.

Telemetry individuals​

Every individual in a telemetry collection needs a _sourceId, which identifies the source of its readings, such as a device. When you create or update a telemetry individual, the service uses the first of the following that has a value:

  1. The _sourceId you send.
  2. The _sourceId already stored on the individual.
  3. On an import, the individual's external key, built from the class's _externalKeyFields, for example _sourceKey=p-1.

If none has a value, the call returns 400. For more information on external keys, see External keys.

Writing readings​

A reading has a time, _ts, in ISO 8601 format, and the measured values as other fields. Every reading also needs a _tsMetadata._sourceId.

You can write readings in two ways:

  • To one individual. The service takes the individual from the path. To set the same source on every reading, send the sourceId query parameter. For more information, see Add readings to an individual.
  • To several individuals of a class. Each reading names its own _tsMetadata._telItemId and _tsMetadata._sourceId. For more information, see Add readings to several individuals.

A request holds up to 2000 readings. By default, a failure partway through a write can leave some readings stored. To store the batch whole or not at all, set transactional=true.

A successful write returns 204, but that doesn't confirm that every reading was stored. The Item Service drops readings whose _telItemId isn't an individual in the collection. If no reading matches, the call returns 400. To be sure, read the readings back.

Reading readings​

You can read the readings of one individual, or of every individual of a class. Both reads return a page of readings, newest first by default. To limit the time range, send from (inclusive) and to (exclusive). For more information, see Get the readings of an individual and Get the readings of a class.

If several classes share a telemetry collection, a class read returns only that class's readings. In that case, a class with more than 1000 individuals returns 409. Read each individual instead, or give the class a collection of its own.

Time series settings​

A telemetry collection that the service creates at promotion uses the Item Service default time series settings: minute granularity and no expiry. You can change these settings later in the Item Service, but you can't make the granularity finer. If you sample more often than once a minute, create the telemetry collection in the Item Service yourself with seconds granularity, and bind the class to it by ID. For more information on telemetry collections, see NamedTelemetryCollection.

Permissions​

Writing readings needs INDIVIDUALS_CREATE on the class. Reading them needs INDIVIDUALS_READ. For more information, see Permissions.