Proposal: Dictionary of common Attribute/Label definitions

[justinfoote]

Hey all,
In a recent PR regarding metric semantic conventions, we repeatedly diverted the conversation to these topics:

• There's a lot of duplication between the labels in the HTTP metric semantic convention and the attributes in the HTTP tracing semantic convention.
• If we remove that duplication and reference the tracing convention from the metrics convention, it implies some connection between the underlying span and metric data structures.
• Labels and attributes have different restrictions on value types. Does it even make sense to use the same key for a metric label and a span attribute if their value is different (for example, http.response_code of "200" on a label or 200 on an attribute).

I propose that we solve this issue by creating a single data dictionary that can be referenced from all semantic conventions. This will clarify what each attribute name signifies, so we don't have to redefine the same names in multiple places.

We use a system like this at New Relic. We've even made this data dictionary publicly-available and searchable. Check it out here: https://docs.newrelic.com/attribute-dictionary?attribute_name=traceId

In this example, because the definition of traceId exists in a single place, when it is included in a spec for Spans, Transactions, and Logs, each spec does not need to include a full definition of the attribute.

At the moment, OpenTelemetry has defined traceId in at least two places:

• Logs:

Field: TraceId

Type: byte sequence.

Description: Request trace id as defined in W3C Trace Context. Can be set for logs that are part of request processing and have an assigned trace id. This field is optional.

• SpanContext:

TraceId is the identifier for a trace. It is worldwide unique with practically sufficient probability by being made as 16 randomly generated bytes. TraceId is used to group all spans for a specific trace together across all processes.

I propose something like this, in a big table of all attributes:

Name	Description	Serialization	Example
traceId	The identifier for a trace. It is worldwide unique with practically sufficient probability by being made as 16 randomly generated bytes. TraceId is used to group all spans for a specific trace together across all processes, and to correlate other data points to those spans.	Byte Sequence	8ac95d01265752b841aa418a0ed4cb48

In addition, I think such a document could include details about how to convert each value to a String to be used as a label (or in other places where a value must be coerced to a String):

Name	Description	Serialization	Example	String Representation
traceId	The identifier for a trace. It is worldwide unique with practically sufficient probability by being made as 16 randomly generated bytes. TraceId is used to group all spans for a specific trace together across all processes, and to correlate other data points to those spans.	Byte Sequence	8ac95d01265752b841aa418a0ed4cb48
http.status_code	HTTP response status code.	Integer	200	"200"

[austinlparker]

We believe this has already been accomplished by the semantic conventions SIG. If you believe this determination to be in error, please comment and we will re-open.