feat(exporters): add user-agent enrichment #4560
Conversation
specification/protocol/exporter.md
Outdated
| @@ -208,6 +208,21 @@ OTel-OTLP-Exporter-Python/1.2.3 | |||
|
|
|||
| The format of the header SHOULD follow [RFC 7231][rfc-7231]. The conventions used for specifying the OpenTelemetry SDK language and version are available in the [Resource semantic conventions][resource-semconv]. | |||
|
|
|||
| Exporters MAY expose a configuration option to append a product identifier to the User-Agent | |||
| header as defined in [RFC 7231][rfc-7231]. Such option should not be available as | |||
There was a problem hiding this comment.
SHOULD NOT (even MUST NOT?)
There was a problem hiding this comment.
I agree with MUST NOT. Thanks @carlosalberto :)
commit d7d96d7
|
Maybe Collector folks should review this too @mx-psi ? |
|
My understanding is that Collector components are not, as a general rule, bound by the spec. I guess we can add this to our coding guidelines in the Collector as well if it gets approved here to make sure it is followed |
…telemetry-specification into enrich-user-agent-header
|
This PR was marked stale due to lack of activity. It will be closed in 7 days. |
|
not stale |
|
@open-telemetry/spec-sponsors sorry for the noise but I do not know exactly who to ping for this review |
|
This PR was marked stale due to lack of activity. It will be closed in 7 days. |
|
Link checking is failing in a file unrelated to this PR https://github.com/open-telemetry/opentelemetry-specification/actions/runs/16450064559/job/46492635216?pr=4560 |
|
Now failing for a different URL in a different file https://github.com/open-telemetry/opentelemetry-specification/actions/runs/16503550939/job/46668267584?pr=4560 :( |
| Exporters MAY expose a configuration option to append a product identifier to the User-Agent | ||
| header as defined in [RFC 7231][rfc-7231]. Such option MUST NOT be available as | ||
| an environment variable since is meant to be used by [distributions][opentelemetry-distribution] | ||
| to append their product identifier along with the exporter's one. |
There was a problem hiding this comment.
Seems odd to me to explicitly call out no env vars but make this configurable in code. I assume the idea behind disallowing env support is to prevent users from setting this or overriding the distro, but if it's a config they can do that anyway. Should this be hidden entirely from users by e.g. making it a protected class property that a distro would override in a subclass?
There was a problem hiding this comment.
even if Env variable exists, it cannot override the code based setting, as code wins over env variable in almost all OTel implementations.
There was a problem hiding this comment.
This decision comes from the discussion in #4230
At the time of creating the issue in opentelemetry-js it was possible to override the user agent header and we concluded it was not a good idea let the user control completely it's value via en vars.
There was a problem hiding this comment.
Maybe instead of being precise about how people can interact with that (e.g. references to environment variables) we can just say that users (distro developers / end users) MAY change the user agent but the updated one MUST SHOULD be a superset of the OTel one?
| above example would report the following: | ||
|
|
||
| ``` | ||
| OTel-OTLP-Exporter-Python/1.2.3 MyDistribution/x.y.z |
There was a problem hiding this comment.
Should this be MyDistribution/x.y.z OTel-OTLP-Exporter-Python/1.2.3 instead? The distribution (user's application) is typically more significant for identification than the underlying exporter library.
Also suggested here - https://www.rfc-editor.org/rfc/rfc9110#name-user-agents
User-Agent: CERN-LineMode/2.15 libwww/2.17b3
the first one is the application (browser), and second one is the library used by it.
There was a problem hiding this comment.
I agree. I'll change it when I get back from vacation.
| an environment variable since is meant to be used by [distributions][opentelemetry-distribution] | ||
| to append their product identifier along with the exporter's one. | ||
|
|
||
| SDKs MAY expose a similar configuration option if exporters have it. This configuration |
There was a problem hiding this comment.
Not sure of the reasoning behind this being an SDK feature... this looks quite specific to the OTLP Exporter...Could you clarify why SDK is mentioned here?
There was a problem hiding this comment.
Is not mandatory but quite convenient to not to have to provide the default processors and exporters just to append a value in the headers. It's just for making the setup shorter. I'm totally fine removing that part
| to append their product identifier along with the exporter's one. | ||
|
|
||
| SDKs MAY expose a similar configuration option if exporters have it. This configuration | ||
| MUST be overridable by a signal specific option. |
There was a problem hiding this comment.
signal specific option - need some clarity on this is referring to..
There was a problem hiding this comment.
I can add an example if we finally decide to have the option for sdks.
|
Ping @david-luna |
|
@carlosalberto sorry for the delay but I'm on vacation with limited connection. I did answer the comments the best I could from my phone and will resume work when back on the 18th |
Fixes #4479
Changes
Document that exporters may allow a
user-agentoption to append a product identifier to the exporter User Agent header. such option is only available via local var (not environment)For non-trivial changes, follow the change proposal process.
CHANGELOG.mdfile updated for non-trivial changesspec-compliance-matrix.mdupdated if necessary