Skip to content

Commit

Permalink
Add standard warnings for components (open-telemetry#5558)
Browse files Browse the repository at this point in the history
* Add standard warnings

* Updated to include timeseries
  • Loading branch information
TylerHelmuth authored Jun 27, 2022
1 parent bd7e054 commit 259f711
Showing 1 changed file with 16 additions and 0 deletions.
16 changes: 16 additions & 0 deletions docs/standard-warnings.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# Standard Warnings
Some components have scenarios that could cause issues. Some components require the collector be interacted with in a specific way in order to ensure the component works as intended. This document describes common warnings that may affect a component in the collector.

Visit a component's README to see if it is affected by any of these standard warnings.

## Unsound Transformations
Incorrect usage of the component may lead to telemetry data that is unsound i.e. not spec-compliant/meaningless. This would most likely be caused by converting metric data types or creating new metrics from existing metrics.

## Statefulness
The component keeps state related to telemetry data and therefore needs all data from a producer to be sent to the same Collector instance to ensure a correct behavior. Examples of scenarios that require state would be computing/exporting delta metrics, tail-based sampling and grouping telemetry.

## Identity Conflict
The component may change the [identity of a metric](https://github.com/open-telemetry/opentelemetry-specification/blob/main//specification/metrics/data-model.md#opentelemetry-protocol-data-model-producer-recommendations) or the [identity of a timeseries](https://github.com/open-telemetry/opentelemetry-specification/blob/main//specification/metrics/data-model.md#timeseries-model). This could be done by modifying the metric/timeseries's name, attributes, or instrumentation scope. Modifying a metric/timeseries's identity could result in a metric/timeseries identity conflict, which caused by two metrics/timeseries sharing the same name, attributes, and instrumentation scope.

## Orphaned Telemetry
The component modifies the incoming telemetry in such a way that a span becomes orphaned, that is, it contains a `trace_id` or `parent_span_id` that does not exist. This may occur because the component can modify `span_id`, `trace_id`, or `parent_span_id` or because the component can delete telemetry.

0 comments on commit 259f711

Please sign in to comment.