Exemplars are example data points for aggregated data. In particular, for distribution-type metrics, exemplars are points associated with each bucket in the distribution giving an example of what was aggregated into the bucket.
Exemplars consist of a value that was recorded, an exact timestamp of when that value was recorded, and a set of attachments.
Exemplars my have zero or more attachments. Attachments are key-value pairs that describe the context in which the exemplar was recored.
Implementations should provide an extensible mechanism to extract custom attachments from the context.
We define the following types of attachments:
trace_id: lower-case base16 encoded trace IDspan_id: lower-case base16 encoded span IDtag:KEY: tags that were active at the time of recording, regardless of whether they were ultimately added to views or not.KEYis the tag key, the value of the attachment is the tag value in effect.
If trace_id and span_id are provided, the associated trace should be sampled.
Libraries should attempt to retain and export at least once exemplar per bucket per reporting period for distribution-type views. Libraries should not retain an unbounded number of exemplars.
Libraries should prefer retaining exemplars with sampled traces associated with them. After considering associated trace, libraries should prefer exemplars with more attachments over exemplars with fewer or no attachments.
The interpretation of attachments is up to the exporter. Currently, only Stackdriver is known to support exemplars.