Metadata

Every data point stored in OpenTSDB has at least three UIDs associated with it. There will always be a and one or more tag pairs consisting of a tagk or tag name, and a tagv or tag value. When a new name for one of these UIDs comes into the system, a Unique ID is assigned so that there is always a UID name and numeric identifier pair.

Each UID may also have a metadata entry recorded in the tsdb-uid table. Data available for each UID includes immutable fields such as the uid, type, name and created timestamp that reflects the time when the UID was first assigned. Additionally some fields may be edited such as the description, notes, displayName and a set of key/value pairs to record extra information. For details on the fields, see the /api/uid/uidmeta endpoint.

Whenever a new UIDMeta object is created or modified, it will be pushed to the Search plugin if a plugin has been configured and loaded. For information about UID values, see .

Each timeseries in OpenTSDB is uniquely identified by the combination of its metric UID and tag name/value UIDs, creating a TSUID as per UIDs and TSUIDs. When a new timeseries is received, a TSMeta object can be recorded in the tsdb-uid table in a row identified by the TSUID. The meta object includes some immutable fields such as the tsuid, metric, tags, lastReceived and created timestamp that reflects the time when the TSMeta was first received. Additionally some fields can be edited such as a description, notes and others. See for details.

If you want to use metadata in your OpenTSDB setup, you must explicitly enable real-time metadata tracking and/or use the CLI tools. There are multiple options for meta data generation due to impacts on performance, so before you enable any of these settings, please test the impact on your TSDs before enabling the settings in production.

Two are available, starting with the least impact to the most.

Warning

Watch your JVM heap usage when enabling any of the real-time meta data settings. Also watch the storage servers as write traffic may effectively double or treble.

For situations where a TSD crashes before metadata can be written to storage or if you do not enable real-time tracking, you can periodically use the uid CLI tool and the metasync sub command to generate missing UIDMeta and TSMeta objects. See uid for information.

Every annotation is associated with a start timestamp. This determines where the note is stored in the backend and may be the start of an event with a beginning and end, or just used to record a note at a specific point in time. Optionally an end timestamp can be set if the note represents a time span, such as an issue that was resolved some time after the start.

Additionally, an annotation is defined by a TSUID. If the TSUID field is set to a valid TSUID, the annotation will be stored, and associated, along with the data points for the timeseries defined by the ID. This means that when creating a query for data points, any annotations stored within the requested timespan will be retrieved and optionally returned to the user. These annotations are considered “local”.

If the TSUID is empty, the annotation is considered a “global” notation, something associated with all timeseries in the system. When querying, the user can specify that global annotations be fetched for the timespan of the query. These notes will then be returned along with “local” annotations.

Annotations should have a very brief description, limited to 25 characters or so since the note may appear on a graph. If the requested timespan has many annotations, the graph can become clogged with notes. User interfaces can then let the user select an annotation to retrieve greater detail. This detail may include lengthy “notes” and/or a custom map of key/value pairs.

Users can add, edit and delete annotations via the Http API at ../api_http/annotation.

An example GnuPlot graph with annotation markers appears below. Notice how only the description field appears in a box with a blue line recording the . Only the start_time appears on the graph.