Document spans emitted by instrumentations

[jaydeluca]

Context

As part of #13468 we want to document the spans emitted by each instrumentation. We should be able to differentiate spans emitted by default vs when various configuration options are enabled.

This work was enabled by #14065

Requirements

Each module's gradle file will need to be modified to include a system property feature flag configured for when the tests run. Along with the collectMetadata flag, you will need to also add collectSpans set to true:

tasks {
  test {
    systemProperty("collectMetadata", collectMetadata)
    systemProperty("collectSpans", true)
  }
}

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)
    systemProperty("collectSpans", true)
  }

  val testStableSemconv by registering(Test::class) {
    jvmArgs("-Dotel.semconv-stability.opt-in=database")

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

  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

TODO: add a tracking mechanism / list of modules