open-telemetry / open-telemetry/opentelemetry-java-instrumentation
Declarative configuration documentation
@jaydeluca is already working on this.
Since Dec 24, 2025.
- Dominant language
- Java
- Stars
- 2.6k
- Forks
- 1.2k
- Avg merge
- 2d 18h
- Merged PRs (30d)
- 228
Description
As part of the metadata system, we currently document system properties. We need to now implement a similar system for the new declarative configuration options.
Work to be done:
- Come up with a new format for displaying this information within the context of the metadata
- Identify if there is a way to automate the identification of these new configuration options
- Go through and update all instrumentations to document the associated configs
For example, the R2DBC library has:
configurations:
- name: otel.instrumentation.r2dbc.statement-sanitizer.enabled
description: >
Enables statement sanitization for database queries. Takes precedence over
otel.instrumentation.common.db-statement-sanitizer.enabled.
type: boolean
default: true
- name: otel.instrumentation.common.db-statement-sanitizer.enabled
description: Enables statement sanitization for database queries.
type: boolean
default: true
- name: otel.instrumentation.r2dbc.experimental.sqlcommenter.enabled
description: >
Enables augmenting queries with a comment containing the tracing information. See
[sqlcommenter](https://google.github.io/sqlcommenter/) for more info. WARNING: augmenting
queries with tracing context will make query texts unique, which may have adverse impact on
database performance.
type: boolean
default: false
- name: otel.instrumentation.common.peer-service-mapping
description: Used to specify a mapping from host names or IP addresses to peer services.
type: map
default: ""
Which could have an output like:
r2dbc:
statement_sanitizer:
enabled: false
sqlcommenter/development:
enabled: false
but unclear how we could document the description and type in this format.
Alternatively we could document them similar to how they are now, and collapsing the names:
declarative_configurations:
- name: r2dbc.statement_sanitizer.enabled
description: >
Enables statement sanitization for database queries.
type: boolean
default: true
- name: r2dbc.experimental.sqlcommenter/development.enabled
description: >
Enables augmenting queries with a comment containing the tracing information. See
[sqlcommenter](https://google.github.io/sqlcommenter/) for more info. WARNING: augmenting
queries with tracing context will make query texts unique, which may have adverse impact on
database performance.
type: boolean
default: false
While this isn't great in the sense of being able to copy/paste it into a config, we could use it to generate a different format that is more copy/paste friendly
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.