Opentelemetry-specification: Where to put instrumentation-specific semantic conventions.

[anuraaga]

I think it's common for there to be a set of semantic conventions for specific instrumentation. These are often for frameworks with a cross-language scope, or client libraries for a service that exist in many languages. Information that are useful in observability that are always present in these situations make sense to have consistent in spans across languages.

We have an example already in our spec of instrumentation-specific conventions for gRPC.

https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/semantic_conventions/rpc.md#grpc

I am working on semantic conventions for the AWS SDK client libraries

https://github.com/anuraaga/aws-opentelemetry-java-instrumentation/blob/master/docs/aws-sdk-semantic-conventions.md

These are conventions that AWS has collected through working with customers and are a set of data that we find helps with observability. Of course, we're happy to increase this list even more :) But the main idea is we think it is a good idea to have these conventions implemented in all instrumentations of the AWS SDK, regardless of language and want to make sure there is a reference point for instrumentation writers.

In Java instrumentation, we already have some attributes that are useful to users that are not documented anywhere, but should presumably be in the spec and filled by all languages instrumenting the same system (or not filled anywhere).

https://github.com/open-telemetry/opentelemetry-java-instrumentation/issues/602

For example, Kafka tombstone, elasticsearch actions.

Is it appropriate to have an instrumentations subfolder in semantic_conventions to put these sort of conventions in? We can start by extracting out grpc.md since it's already in this spec.

[Oberon00]

We have an example already in our spec of instrumentation-specific conventions for gRPC.

That's not instrumentation specific. All gRPC instrumentations will follow this convention. In a sense, you could argue that it is on the same level as HTTP, as both are semantic conventions for client/server of a certain protocol. In practice however, there is probably only one gRPC implementation per language while there are many for HTTP.

[anuraaga]

In a strict sense, yes, but all of our languages currently publish instrumentation models such as opentelemetry-instrumentation-grpc, I expect similar for RSocket, and these seem different than concepts like SOAP, REST which are frameworkless protocols. Indeed, perhaps a folder called protocols for these instead of putting them in instrumentations could make sense, but I don't know if it's really easier to understand for the instrumentation writers. But the meat of this discussion should be independent of whether we want to call gRPC a protocol of instrumentation, there are popular "systems" that can benefit from having conventions defined in a cross-language way.

[Oberon00]

I think we should just allow all of these to be in the spec. Or if we find there are too many, maybe we could have a spec-contrib repository with quicker approval/merge process for less important semantic conventions.

[arminru]

I think we should just allow all of these to be in the spec. Or if we find there are too many, maybe we could have a spec-contrib repository with quicker approval/merge process for less important semantic conventions.

👍
This would certainly help in terms of discoverability and allow instrumentations for the same framework/system/protocol/... to be aligned across langugages.

[iNikem]

@Oberon00 what about attributes for e.g. Elasticsearch or Solr? Something very specific to some particular technology. Should we just propose/create semantic convention for such quite narrow area and submit to the spec repo as broader HTTP convention?