Clarify which API classes must be available to users

[Azquelt]

Description

The spec is not explicit about which classes and packages should be available to applications.

The closest I can find is this:

This document and implementations MUST comply with the following OpenTelemetry 1.13 specifications:

• OpenTelemetry Overview
• Tracing API
• Baggage API
• Context API
• Resource SDK

The spec has several examples of using API classes, and the TCK also assumes that the autoconfigure SPI is available as the InMemorySpanExporterProvider implements one of its interfaces.

The spec should be more explicit about which API classes are required and we should have TCK tests to assert that they are available.

[Emily-Jiang]

This involves spec clarification and TCK verification (load the classes and/or use the classes).

[Azquelt]

We noted in the meeting that the list should also include the parts of the autoconfigure SPI which are relevant to tracing since elsewhere the spec says we support autoconfigure and the TCK already depends on using the SPI to add a custom exporter.

[Emily-Jiang]

In the next call, we will work out the list of API classes to be exposed under this spec.

[Azquelt]

Here are the API packages I think are required.

Tracing API

• io.opentelemetry.api
• io.opentelemetry.api.trace
• io.opentelemetry.api.common

Note: io.opentelemetry.api does depend on io.opentelemetry.api.metrics and io.opentelemetry.api.logs, though we only support the parts of it that relate to tracing.

Baggage API

• io.opentelemetry.api.baggage
• io.opentelemetry.api.baggage.propagation

Context API

• io.opentelemetry.context
• io.opentelemetry.context.propagation

Resource SDK

• io.opentelemetry.sdk.resources

Autoconfigure SPI

This is the programmatic interface that allows users to register extensions when using the SDK Autoconfigure Extension (which we use for configuration). The spec currently isn't clear about whether or not support for the SPI is required, but the TCK currently requires it to register a SpanExporter.

• io.opentelemetry.sdk.autoconfigure.spi
• io.opentelemetry.sdk.autoconfigure.spi.traces
• these then depend on the following packages
  • io.opentelemetry.sdk.trace
  • io.opentelemetry.sdk.trace.data
  • io.opentelemetry.sdk.trace.export
  • io.opentelemetry.sdk.trace.samplers
  • io.opentelemetry.sdk.common

WithSpan annotation

I see this now also contains an AddingSpanAttributes annotation (added in 1.26.0) which sets attributes on the current span without creating a new one. We should decide whether to support that.

• io.opentelemetry.instrumentation.annotations

Semantic Conventions

We say that the implementation needs to follow semantic conventions. It makes sense to also expose the semantic convention APIs to the user. The TCK currently requires that these APIs are available, though we could change the TCK to package the classes in the test application.

Note that these packages are not stable.

• io.opentelemetry.semconv.trace.attributes
• io.opentelemetry.semconv.resource.attributes

[Emily-Jiang]

@Azquelt since we are not sure which spec version we should link to, it might be problematic to link to the spec with a particular release version. We can discuss how best to provide the info on the call.

[Azquelt]

All of the links that I've provided above link to opentelemetry-java javadoc (or opentelemetry-java-instrumentation for the annotations), not to the opentelemetry spec.

I assume we're going to specify either a minimum version of opentelemetry-java, or a version of opentelemetry-java which implementations must be compatible with, in which case we can link to that version.

[brunobat]

I wonder if we could divide the tests and, therefore, the required packages in 2 types:

• end users.
• integrators.
  ... And we should doublecheck with the OTel community if our approach is safe enough.

[Azquelt]

Firstly,

The spec only needs to say what services the implementer has to provide to the end user. If the end user can't use it, then it doesn't need to go in the spec at all. The implementer is always free to do whatever they like and use whatever they like.

However, the TCK mostly tests compliance with the spec by building and deploying applications (as a user would) and checking that they function correctly. When we're testing like this, the TCK must not use anything that the spec doesn't require is available to users.

At the moment, the TCK uses ConfigurableSpanExporterProvider and for those tests to be valid, the spec needs to say that users can also provide their own span exporter within the application as the TCK does.

The alternative would be for the TCK to have an extension mechanism which each implementer must implement to allow an additional span exporter to be registered. The CDI TCK does something similar, requiring each vendor to implement the porting package interfaces to allow the TCK to inspect CDI internals.

Secondly,

The only place I see OTel give guidance on the API vs the SDK is for library developers: https://opentelemetry.io/docs/concepts/instrumentation/libraries/#opentelemetry-api

(Edit, it's also in the overview: https://opentelemetry.io/docs/specs/otel/overview/#api )

Developers who are instrumenting libraries should only use the OTel API and not touch the SDK. In contrast, application developers can use the SDK to configure OTel to their liking at application start.

In the MicroProfile case, I don't think the implementer entirely takes the place of the application developer. While the implementer does take responsibility for configuring OTel via MP Config, the application developer might still want to configure OTel in ways that aren't possible with only config properties (e.g. adding a custom exporter or propagator). If we want to allow them to do this, then we need to allow access to io.opentelemetry.sdk.autoconfigure.spi.traces and its dependencies.