Standardize telemetry samples to go with instrumentation entries in the OTel registry

[punya]

As an end-user looking for instrumentation for my chosen language/library/tool, I want to quickly see a sample of the telemetry I'll get by adopting an OTel instrumentation library, so that I can evaluate whether it'll serve my obervability needs.

Today, to evaluate an instrumentation library I find in the registry, I need to

1. follow the steps to add it to my application
2. possibly set up: the OTel SDK, an exporter, a collector, and an observability backend
3. exercise my application in a way that generates telemetry
4. find the telemetry in my backend (without knowing exactly what to look for)

It would be great if the registry also provided a standard location and format for telemetry samples. Concretely,

1. We'd add a samples field to the YAML files backing the registry.
2. We'd index the content of the samples and link to them from the search result snippet.

Using https://github.com/open-telemetry/opentelemetry.io/blob/main/data/registry/instrumentation-go-grpc.yml as an example, this might look like

title: gRPC instrumentation
registryType: instrumentation
isThirdParty: false
language: go
tags:
  - go
  - instrumentation
  - grpc
repo: https://github.com/open-telemetry/opentelemetry-go-contrib/tree/main/instrumentation/google.golang.org/grpc
license: Apache 2.0
description: Go contrib plugin for Google's grpc package.
authors: OpenTelemetry Authors
otVersion: latest

samples:

- name: Trace attributes sample
  libraryVersion: 3.4.5
  scopeLabels:
  - key: key-name
    value: actual-value
    semconv: url of relevant semconv, if any
  spanLabels:
  - key: key-name
    value: actual-value
    semconv: url of relevant semconv, if any

- name: Metric attributes sample
  libraryVersion: 3.4.5
  scopeLabels:
  - key: key-name
    value: actual-value
    semconv: url of relevant semconv, if any

[punya]

I'm happy to work on this or coordinate with others - I created the issue to get feedback on the idea.

[svrnm]

While I see and understand the value of such samples, my main concern is the maintainability of the same: there are a few hundred instrumentation libraries across all languages, steadily growing, so keeping them up-to-date beyond a name, description & link requires some regular maintanance. Is this something you are willing to take on?

[punya]

I can't personally maintain the full set of samples. My hope was that:

• including the version number of the instrumentation library would give users an indication of how much the most recent version might have diverged from it
• the value of such samples would give instrumentation library maintainers an incentive to update samples

Do you have any suggestions for reducing scope so that these samples become easier to maintain?

[svrnm]

I don't really see a way how to make this easy. We discussed making the registry better in different ways over the last few months and the scale of things is just a big blocker. Ideally people would have an appetite to keep their entries up-to-date themselves like they do it with other registries (npmjs, etc.), but as long as this is not the case, we need people do the heavy lifting

[svrnm]

Closing this issue in favor of open-telemetry/community#2246, which may cover this as well