Skip to content

Declarative configuration documentation #15728

@jaydeluca

Description

@jaydeluca

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

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

Status

No status

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions