open-telemetry / open-telemetry/opentelemetry-java-instrumentation

Declarative configuration documentation

Open
#15,728 1 comment 0 reactions 1 assignee View on GitHub

@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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.