diff --git a/CHANGELOG.md b/CHANGELOG.md index b0e7987087d..332c328a629 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,10 @@ release. ### Traces +- Clarify `SpanKind` description, extend it to cover links, add examples of + nested client spans. + ([#4178](https://github.com/open-telemetry/opentelemetry-specification/pull/4178)) + ### Metrics ### Logs diff --git a/specification/trace/api.md b/specification/trace/api.md index 53edc07dfd9..eb318f77745 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -753,26 +753,36 @@ This functionality MUST be fully implemented in the API, and SHOULD NOT be overr parent/child relationships or span links. `SpanKind` describes two independent properties that benefit tracing systems during analysis: -1. Whether span represents an outgoing request to a remote service (CLIENT and PRODUCER spans) - or a processing of request initiated externally (SERVER and CONSUMER spans). -2. Whether a Span represents a synchronous call. Spans that describe synchronous operations - (SERVER and CLIENT) end after all its children complete under ordinary circumstances. - It can be useful for tracing systems to know this property, since synchronous Spans may - contribute to the overall trace latency. Asynchronous scenarios can be remote or local. +1. Whether span represents an outgoing call a remote service (`CLIENT` and + `PRODUCER` spans) or a processing of request initiated externally (`SERVER` + and `CONSUMER` spans). +2. Whether a Span represents a synchronous call. Spans that describe synchronous + operations (`SERVER` and `CLIENT`) end after all its children complete under + ordinary circumstances. It can be useful for tracing systems to know this + property, since synchronous Spans may contribute to the overall trace + latency. Asynchronous scenarios can be remote or local. In order for `SpanKind` to be meaningful, callers SHOULD arrange that a single Span does not serve more than one purpose. For example, a server-side span SHOULD NOT be used to describe outgoing remote procedure call. As a simple guideline, instrumentation should create a -new Span prior to injecting the SpanContext for a remote outgoing call. +new Span prior to injecting the `SpanContext` for a remote outgoing call. -Note: A CLIENT span may have a child that is also 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. +Note: A `CLIENT` span may have a child that is also a `CLIENT` span, or a +`PRODUCER` span might have a local child that is a `CLIENT` span, +depending on how the various components that are providing the functionality +are built and instrumented. -These are the possible SpanKinds: +For instance, a database client instrumentations create `CLIENT` span that +describes database calls. If the database client communicate to the server over +HTTP, the HTTP instrumentation (when enabled) creates nested `CLIENT` spans to +track individual HTTP calls performed in the scope of logical database `CLIENT` +operation. + +Such scenarios, when they occur, should be detailed in the semantic conventions +appropriate to the relevant technologies. + +These are the possible `SpanKind`s: * `SERVER` Indicates that the span covers server-side handling of a synchronous RPC or other remote request. @@ -781,10 +791,11 @@ These are the possible SpanKinds: When the context of a `CLIENT` span is propagated, `CLIENT` span usually becomes a parent of a remote `SERVER` span and ends after the `SERVER` span completes. -* `PRODUCER` span describes the initiation of an asynchronous request. This initiating - span will often end before the correlated `CONSUMER` span, possibly even before the - `CONSUMER` span starts. In messaging scenarios with batching, tracing - individual messages requires a new `PRODUCER` span per message to be created. +* `PRODUCER` span describes the initiation of an asynchronous request. This + initiating span will often end before the correlated `CONSUMER` span, + possibly even before the `CONSUMER` span starts. In messaging scenarios with + batching, tracing individual messages requires a new `PRODUCER` span per + message to be created. * `CONSUMER` Indicates that the span describes the receiving or handling of an asynchronous request. * `INTERNAL` Default value. Indicates that the span represents an