search

open-telemetry / opentelemetry-js-contrib

OpenTelemetry instrumentation for JavaScript modules
https://opentelemetry.io
Apache License 2.0
711 stars 529 forks source link

Should we document non-spec attribute names in READMEs? #2170

Open JamieDanielson opened 7 months ago

JamieDanielson commented 7 months ago

I wonder if it can be helpful to also enumerate the other, non-spec-compliant attributes that are emitted by this instrumentation, as a reference for users and for them to know what to expect when using this instrumentation.

There seems to be 2 custom attributes at the moment:

export enum AttributeNames {
  CONNECT_TYPE = 'connect.type',
  CONNECT_NAME = 'connect.name',
}

Do you think eventually we will need to either remove them or add them to the specs? Or eventually, each instrumentation is allowed to record extra attributes for which we also need some sort of documentation and stability guarantee?

_Originally posted by @blumamir in https://github.com/open-telemetry/opentelemetry-js-contrib/pull/2154#discussion_r1582544261_

joaopgrassi commented 7 months ago

We didn't have time to discuss it this week, but it's at the top of the agenda for next week (May 6th). I will keep you updated.

JamieDanielson commented 7 months ago

This was discussed in today's Semantic Conventions WG meeting. There is some general guidance about stable instrumentation NOT providing telemetry at all outside of semantic conventions. This would mean that we should open PRs to add these specific attributes to semantic conventions for frameworks, along with any other attributes not currently defined in semantic conventions, and have that codified before declaring instrumentations stable (instrumentations are not yet stable).

This is sort of a "newer" problem as we are growing as a project and trying to ensure relative stability of attributes, so there is actually not a ton of precedence in documenting and guaranteeing attributes specific to a framework that doesn't exist in other languages or frameworks. There is also discussion about what attributes should potentially be opt-in vs enabled by default. There will be an issue opened in semantic conventions repo to document the current approaches and try to provide workarounds where deemed appropriate.