Area(s)

area:gen-ai

Is your change request related to a problem? Please describe.

The current conventions for GenAI spans require the span kind to be CLIENT for GenAI applications interacting with model providers.

Interactions with model providers rely on HTTP APIs, for which Semantic Conventions exist already. Production applications typically have already an established HTTP infrastructure in their architecture, which often include also instrumentation and observability already. Client libraries to interact with GenAI model providers can build on top of the existing HTTP infrastructure. For example, an OpenAI Client library would delegate to an existing (and already used in production) HTTP library to perform the actual HTTP calls. When that happens, the HTTP calls are already instrumented and observed.

When instrumenting such a GenAI Client, the result would be a span for the GenAI client and a nested/child span for the HTTP interaction (GenAI => HTTP). The GenAI part is a wrapper around HTTP, and it's probably worth maintaining that distinction instead of mixing up the two different concerns. However, in that case, the child span (HTTP) would be of kind CLIENT. And in order to follow the Semantic Conventions, the parent span (GenAI) would also have to be of kind CLIENT, but that's confusing and possibly not one of the "complex scenarios" mentioned in the OpenTelemetry Traces Spec:

Note: there are complex scenarios where a CLIENT span may have a child that is also logically a CLIENT span, or a PRODUCER span might have a local child that is a CLIENT span, depending on how the various libraries that are providing the functionality are built and instrumented. These scenarios, when they occur, should be detailed in the semantic conventions appropriate to the relevant libraries.

Even just looking at the definition for the kind CLIENT, it seems wrong having the GenAI span as CLIENT, even though it's the child HTTP span that ultimately describes "a request to some remote service".

CLIENT Indicates that the span describes a request to some remote service. This span is usually the parent of a remote SERVER span and does not end until the response is received.

Describe the solution you'd like

If I understood correctly and it would not be correct to have two nested spans (GenAI => HTTP) both with kind CLIENT, then my suggestion would be to change the requirement for GenAI spans to allow both INTERNAL and CLIENT kinds, letting the implementers decide on which one to use based on the library they are instrumenting.

If the library doesn't use an already-instrumented HTTP library, then the kind would be CLIENT. Example: OpenAI Python library.

If the library relies on an already-instrumented HTTP library, then the kind would be INTERNAL. Example: OpenAI Java library in Spring Boot and Quarkus.

Once we acknowledge the common scenario with two nested spans in production applications (GenAI => HTTP), it's also worth pointing out that some of the span attributes and metric attributes included in the Semantic Conventions for GenAI would not be used when the GenAI span is of kind INTERNAL (e.g. server.port, server.address, error.type), because they would belong to the child HTTP span.

Describe alternatives you've considered

No response

Additional context

I mainly work with Java. The two main Java frameworks (Spring Boot and Quarkus) both come with existing instrumentation and observability for the HTTP infrastructure, which is the foundation on top of which libraries like Spring AI and Quarkus LangChain4j are built.

I'm working on instrumenting Spring AI based on the Semantic Conventions for GenAI. Currently, the GenAI spans are of kind INTERNAL and the HTTP spans are of kind CLIENT. Example of trace for a GenAI library that uses an already instrumented (and used in production) HTTP library: