Document metrics emitted by instrumentations

[jaydeluca]

Context

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

This work was enabled by #13891 and #14018

Requirements

Each module's gradle file will need to be modified to include a system property feature flag configured for when the tests run. By enabling the following flag you will enable metric collection for the default case:

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 {
  val testStableSemconv by registering(Test::class) {
    jvmArgs("-Dotel.semconv-stability.opt-in=database")

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

  test {
    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 metrics 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

• Collect metrics from more http and database clients #14038

These are at least some of the modules that generate metrics that will need to be enabled/verified:

• apache-httpclient-5.2
• armeria-1.3
• async-http-client-1.9
• async-http-client-2.0
• avaje-jex-3.0
• finagle-http-23.11
• finatra-2.9
• grails-3.0
• grizzly-2.3
• grpc-1.6
• http-url-connection
• javalin-5.0
• jaxrs-2.0-cxf-3.2
• jaxrs-2.0-jersey-2.0
• jaxrs-2.0-resteasy-3.0
• jaxrs-2.0-resteasy-3.1
• jaxrs-3.0-jersey-3.0
• jaxrs-3.0-resteasy-6.0
• jetty-11.0
• jetty-12.0
• jetty-8.0
• ktor-1.0
• ktor-2.0
• ktor-3.0
• play-mvc-2.4
• play-mvc-2.6
• ratpack-1.4
• ratpack-1.7
• restlet-1.1
• restlet-2.0
• restlet-2.0
• servlet-2.2
• servlet-3.0

Notes

In order to collect the emitted metrics, there must be a waitAndAssertMetrics within the test suite. Tests may need to be updated in order to ensure we intercept the metrics.