add known methods for declarative configuration

[zeitlinger]

Relates open-telemetry/opentelemetry-java#7468

[zeitlinger]

@jack-berg I didn't see any mention of other declarative configuration properties in this repo. Should they be added?

[jack-berg]

@jack-berg I didn't see any mention of other declarative configuration properties in this repo. Should they be added?

This is an unsolved problem. For now, I did a one time analysis of the semantic conventions repo and modeled of the concepts that are supposed to be configurable as properties in the declarative configuration schema: https://github.com/open-telemetry/opentelemetry-configuration/blob/main/schema/instrumentation.json#L50-L128

@lmolkova has previously expressed the idea that the semantic-conventions repo itself could somehow directly model the configuration schema. Then, opentelemetry-configuration could take a dependency on semantic-conventions and translate / merge the configuration schema into its JSON schema.

I like this idea but for now its just an idea.

[zeitlinger]

that the semantic-conventions repo itself could somehow directly model the configuration schema. Then, opentelemetry-configuration could take a dependency on semantic-conventions and translate / merge the configuration schema into its JSON schema.

I also like that.
I'm wondering if we should continue with the current approach until we've figured it out - to not create a split setup.

[lmolkova]

related: #1450

How I see it:

• when opt-in metric/attribute is defined, there should be a way to express which config option it's controlled with. this option should be the same across instrumentations
• it should be possible to enable/disable a tracer/meter/logger (or even span/metric/event) based on a stable language-agnostic property that goes over the wire - semconv and config should work together
• stability opt-in env var should be a config option
• ...

I don't believe anyone is working on it, but I would be exited to see any detailed suggestions/proposals in this space.

[lmolkova]

@jack-berg what are your thoughts on semconv eventually owning the instrumentation config schema - it'd be difficult to write and implement conventions otherwise having config defined separately.

Our long-term vision is that codegen will get smarter and would generate whole spans/events/etc according to configuration, so we'd need to define/refer to config properties formally here in semconv and would interact with config API to retrieve values.

[jack-berg]

@jack-berg what are your thoughts on semconv eventually owning the instrumentation config schema - it'd be difficult to write and implement conventions otherwise having config defined separately.

I'm supportive. We can find a way to make opentelemetry-configuration depend on semantic-conventions and transform / merge the schema.

[zeitlinger]

I propose we make this transformation separate from adding the property now - to avoid delaying the feature.

I've created open-telemetry/opentelemetry-configuration#244

[lmolkova]

Thanks! I left some comments. A few additional thoughts:

• this is a first precedent documenting declarative config in semantic conventions, which I support
• we need to find way to record config options formally in YAML schema at least in some cases, but it's not trivial and we need to collect more precedents to start formalizing it. I don't want to block this PR on that. But we should leave some TODOs around options being introduced and link #1450 as tracking issue
• I'd like to hear what other @open-telemetry/specs-semconv-maintainers think. @zeitlinger could you please bring this topic up on the next semconv call? Thanks!

[lmolkova]

do we know which component would be responsible to use this configuration? This requirement should be actionable for this component. E.g. specialized span or log processor would match network.protocol.address to peer and populate peer.service on all spans based on the service.

In the current form, this requirement is only actionable for declarative config schema.

[zeitlinger]

1. yes, it should only apply to declarative config, because this is a use case that is too complicated for env vars
2. the responsible component is typically a shared library in the instrumentation part
3. specialized log processor: that does not work because you typically don't have access to the URL for HTTP server duration

[lmolkova]

please add Development status for this note

[zeitlinger]

the whole attribute has Development stability

[lmolkova]

is this format defined in the declarative config? I'd use exact attribute names instead.

Suggested change

	- peer: 1.2.3.4
	service: FooService
	- peer: 2.3.4.5
	service: BarService
	- network.peer.address: 1.2.3.4
	peer.service: FooService
	- network.peer.address: 2.3.4.5
	peer.service: BarService

but also, it could be much more generic and allow to do things like "if attribute A matches value B, then set attribute C with value D"

[zeitlinger]

just added the following description:

      - `peer` is host, and optionally the and path of the remote service that is used to identify the service 
         instance, e.g., `example.com:443`, `1.2.3.4:8080`, `example.com`, `example.com:443/fooService`.
      - `service` is the name of the remote service, e.g., `AuthService` that will be translated to the
        `peer.service` attribute.

1. network.peer.address would be wrong, because it can contain the port and path as well
2. declarative config uses _ style
3. it could be much more generic

• this has to be implemented in every SDK, so we try to limit such complex features
• otel collector has an attributes processor where you can already do this if needed

4. peer_service would still be an option

[lmolkova]

why would it be an instrumentation responsibility at all BTW? There are a lot of HTTP / RPC/ etc instrumentations producing spans that may benefit from peer.service.

This enrichment can be done in the single processor (collector or per-language) and dozens of instrumentations would never bother.

[zeitlinger]

the SDK does not have access to the URL - see above

[zeitlinger]

@trask @lmolkova please check again 😄