semconv: generate metrics specs

[iRevive]

This one is rather interesting. Since we depend on semantic conventions, we can generate all necessary instruments immediately.

The generated objects provide:

• Metric name
• Metric unit
• Metric description
• Metric attributes (including requirement level, stability, etc)
• A utility method to create an instrument

Use cases

Semantic testing

Libraries (e.g. http4s-otel4s, skunk) can use otel4s-semconv-metrics-experimental to test the implementation:

val requiredKeys = HttpMetrics.ClientActiveRequests.AttributeSpecs
  .specs
  .filter(_.requirement.level == Requirement.Level.Required)
  .map(_.key)

OpenTelemetrySdkTestkit.inMemory[IO]().use { testkit =>
  for {
    _ <- client.run(...) // generate metrics via fake requests
    metrics <- testkit.collectMetrics
  } yield {
    metrics.filter(_.name == ClientActiveRequests.Name).foreach { md =>
      assert(md.unit == ClientActiveRequests.Unit)
      assert(md.description == ClientActiveRequests.Description)
      md.data.points.toVector.foreach { point =>
        requiredKeys.foreach(key => assert(point.attributes.get(key).isDefined))
      }
    }
  }
}

Implement metrics

Libraries can use otel4s-semconv-metrics to implementation the metrics:

for {
  clientRequestDuration <- HttpMetrics.ClientRequestDuration.create[F](bucketBoundaries)
  ...
} yield new MetricsOps(clientRequestDuration)

The only problem is that only a few metrics are stable, so it's not very useful right now.

[NthPortal]

should AttributeSpec and friends be outside of the metrics directory? it seems like it might be useful to generate these for tracing as well

[NthPortal]

docs here wouldn't be amiss

[iRevive]

Done

[mzuehlke]

A question not directly related to this PR, but more how to deal with not stable semconv:

What is about the semconv-metrics-experimental artifact ?
Can e.g. http4s-otel4s use this for implementing the not yet stable metrics (which are valuable). should this be done in a 2nd module ? Or would it be better to implement them manually (like all metrics are done now), used these specs only for testing and require the user to enable them explicitly ?

[iRevive]

What is about the semconv-metrics-experimental artifact ?

Here is some context: https://opentelemetry.io/docs/specs/otel/versioning-and-stability/.

OpenTelemetry marks each semantic either as stable or experimental.

stable means the changes will evolve in backwards-compatible way.
experimental, on the other hand, may have breaking changes.

We try to follow the same approach, we define two artifacts:

1. otel4s-semconv-metrics - only metrics and associated attributes that are marked as stable will be generated there
2. otel4s-semconv-metrics-experimental - the experimental metrics and attributes

Can e.g. http4s-otel4s use this for implementing the not yet stable metrics (which are valuable).

I would say no. Since generated metrics are public and there can be breaking changes between releases, http4s-otel4s shouldn't depend on the experimental artifact if it wants to guarantee binary compatibility.

But to make life easier, I would do the following:

1. http4s-otel4s should use only the stable module otel4s-semconv-metrics
2. all experimental metrics can be implemented in http4s-otel4s repository manually - the same way we do this now
3. we can use http4s-semconv-metrics-experimental as a test dependency to ensure the current implementation matches the

Or would it be better to implement them manually (like all metrics are done now), used these specs only for testing and require the user to enable them explicitly ?

That's the most realistic scenario, I believe.

[iRevive]

should AttributeSpec and friends be outside of the metrics directory? it seems like it might be useful to generate these for tracing as well

That makes sense. Currently, AttributeSpec lives in the org.typelevel.otel4s.semconv package in the otel4s-semconv-metrics artifact.

Once we implement tracing generators, we can move them to some kind of a common package.

[mzuehlke]

That's the most realistic scenario, I believe.

Thats sound like a very sensible approach. Thanks!
I asked because I planed to work on an sttp integration.