Skip to content

Populate Metadata for each instrumentation #14096

New issue
New issue
Open
Open
Populate Metadata for each instrumentation#14096
Assignees
jaydeluca
Labels
contribution welcomeRequest makes sense, maintainers probably won't have time, contribution would be welcomeenhancementNew feature or request
@jaydeluca

Description

@jaydeluca
jaydeluca
opened on Jun 21, 2025

Requirements

For each instrumentation module, enable telemetry collection (where applicable), and audit/populate the metadata.yaml file with all relevant details. See documenting instrumentation for additional information on the schema and descriptions.

Telemetry collection

Each module's gradle file will need to be modified to include a system property feature flag configured for when the tests run.

tasks.test {
  systemProperty("collectMetadata", findProperty("collectMetadata")?.toString() ?: "false")
}

Sometimes instrumentation will behave differently based on configuration options, and we can
differentiate between these configurations by using the metadataConfig system property. When the
telemetry is written to a file, the value of this property will be included, or it will default to
a default attribution.

For example, to collect and write metadata for the otel.semconv-stability.opt-in=database option
set for an instrumentation:

val collectMetadata = findProperty("collectMetadata")?.toString() ?: "false"

tasks {
  test {
    usesService(gradle.sharedServices.registrations["testcontainersBuildService"].service)
    systemProperty("collectMetadata", collectMetadata)
  }

  val testStableSemconv by registering(Test::class) {
    testClassesDirs = sourceSets.test.get().output.classesDirs
    classpath = sourceSets.test.get().runtimeClasspath
    jvmArgs("-Dotel.semconv-stability.opt-in=database")

    systemProperty("metadataConfig", "otel.semconv-stability.opt-in=database")
    systemProperty("collectMetadata", collectMetadata)
  }

  check {
    dependsOn(testStableSemconv)
  }
}

After the configuration option is set, the gradle tasks should be added to the collect.sh script. If you configured multiple test suites, be sure to add both the standard test task and the others, for example:

readonly INSTRUMENTATIONS=(
   ....
  "clickhouse-client-0.5:javaagent:test"
  "clickhouse-client-0.5:javaagent:testStableSemconv"
   ....

You can generate the span telemetry data by running:

./instrumentation-docs/collect.sh

And then we can update the resulting instrumentation-list.yaml by running:

./gradlew :instrumentation-docs:runAnalysis

Tip: When adding net-new modules, if you have already run the collect script for all the existing modules, comment those ones out in the collect.sh script so you can just run it for each new one to speed up your workflow.

Progress

Metadata

Metadata

Assignees

Labels

contribution welcomeRequest makes sense, maintainers probably won't have time, contribution would be welcomeenhancementNew feature or request

Type

No type

Projects

Java Instrumentation Metadata Phase 2

Status

In Progress
Ecosystem Explorer

Status

In Progress

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions