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:
Docs / Specs / OTel / Common concepts: Exempt Entities
Docs / Specs / OTel / Versioning and stability for OpenTelemetry clients: Semantic Conventions Stability e.g.
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:
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".
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.