open-telemetryotel

Do the OpenTelemetry spec/docs recommend/require OTLP consumer behavior for attribute names that are not defined in the semantic conventions?


Here, I'm particularly interested in attributes related to OpenTelemetry metrics:

For example, if I coin a resource attribute name that is not defined in the OTel semantic conventions, and specify that name in the resource_metrics.resource.attributes.key of an ExportMetricsServiceRequest message, then what should a consumer of that message (telemetry backend) do with that resource attribute: discard it, or ingest it?

I'm deliberately phrasing this question in terms of the OTel spec/docs.

I'm deliberately not naming any specific OTLP consumers (telemetry backends).

I've seen that some telemetry backends discard unrecognized* resource attributes, but accept (ingest) any metric data point attributes.

* Here, by "unrecognized", I mean: resource attribute names that are not defined in the OTel semantic conventions, as implemented by the telemetry backend.

Other telemetry backends ingest whatever resource attributes you send them, regardless of name.

In all cases I've seen so far (admittedly, not that many), telemetry backends ingest whatever metric data point attributes you send them.

Do the OTel spec/docs say what backends should do with resource attributes (or metric data point attributes) with names that are not defined in the semantic conventions?

I've read (and re-read!) most of the OTel docs, including, for example:

Semantic Conventions defines the set of fields in the OTLP data model:

  • Resource
    • attribute keys. ...
  • Metrics
    • The attribute keys on any *DataPoint

but I'm none the wiser regarding this question.

One reason I'm asking this question is the time gaps between:

  1. An OTLP exporter being able to send new attributes. (Attributes that are not yet defined in the OTel semantic conventions.)
  2. New attributes being accepted into the OTel semantic conventions. (For instance, as the deliverable of an OTel Special Interest Group (SIG).)
  3. Existing OTLP consumers (telemetry backends) supporting the new attributes in the updated semantic conventions. (That is, to the extent that each OTLP consumer "cares" about OTel semantic conventions when ingesting data via OTLP into "their" data model, which is potentially proprietary, and not necessarily completely aligned with OTel.)

Existing consumer recommendations in the OTel docs/spec

Another reason I'm asking this question is because I've seen existing statements in the OTel docs/spec such as (quoted here with my additional highlighting):

OpenTelemetry Protocol data model: Consumer recommendations

Consumers MAY reject OpenTelemetry Metrics data containing semantic errors

and

ExponentialHistogram: Consumer Recommendations

Consumers SHOULD reject...

and

Semantic Conventions Stability

...

The values of attributes ... Consumers should expect unknown values.

so I wondered if I was missing a statement such as "Consumers SHOULD accept resource attribute names that are not defined in the semantic conventions".


Solution

  • OpenTelemetry as a project and framework stay away from defining what the destinations of telemetry data do with it. That's 100% intentional and not something that will likely change.

    In my experience, backends aren't dropping attributes not in the semantic conventions. What they are doing is not ingesting attributes (especially resource) that aren't ones they recognised from their agents and ingest paths that pre-date otel.

    The semantic conventions seek to provide context and standardisation of known or widely used names. This allows backends to reason about the data better. The semantic conventions will always be a baseline, and won't be a substitute for providing your own context to telemetry.

    There is guidance to not use the prefixes that are already defined (like k8s. and service.) however this is about future compatibility since the semantic conventions will potentially expand into those.

    As a general rule (not written down) you should put anything that is company specific under a prefix that matches your company somehow. Like using mycomp.tenant.group where mycomp is some abbreviation that makes sense within your company context.

    I've written a lot of best practices docs around naming for Otel specifically, I won't link them here as they're on my company blog, but Google me and you'll find them.