diff --git a/specification/trace/api.md b/specification/trace/api.md index f46ff135504..ee44740154e 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -697,7 +697,9 @@ and its children in a Trace. `SpanKind` describes two independent properties that benefit tracing systems during analysis. The first property described by `SpanKind` reflects whether the Span -is a remote child or parent. Spans with a remote parent are +is a "logical" remote child or parent. By "logical", we mean that +the span is logically a remote child or parent, from the point of view +of the library that is being instrumented. Spans with a remote parent are interesting because they are sources of external load. Spans with a remote child are interesting because they reflect a non-local system dependency. @@ -716,21 +718,28 @@ remote span. As a simple guideline, instrumentation should create a new Span prior to extracting and serializing the SpanContext for a remote call. +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. + These are the possible SpanKinds: * `SERVER` Indicates that the span covers server-side handling of a - synchronous RPC or other remote request. This span is the child of - a remote `CLIENT` span that was expected to wait for a response. -* `CLIENT` Indicates that the span describes a synchronous request to - some remote service. This span is the parent of a remote `SERVER` - span and waits for its response. -* `PRODUCER` Indicates that the span describes the parent of an - asynchronous request. This parent span is expected to end before + synchronous RPC or other remote request. This span is often the child + of a remote `CLIENT` span that was expected to wait for a response. +* `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. +* `PRODUCER` Indicates that the span describes the initiators of an + asynchronous request. This parent span will often end before the corresponding child `CONSUMER` span, possibly even before the child 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 child of an +* `CONSUMER` Indicates that the span describes a child of an asynchronous `PRODUCER` request. * `INTERNAL` Default value. Indicates that the span represents an internal operation within an application, as opposed to an @@ -739,7 +748,7 @@ These are the possible SpanKinds: To summarize the interpretation of these kinds: | `SpanKind` | Synchronous | Asynchronous | Remote Incoming | Remote Outgoing | -|--|--|--|--|--| +|---|---|---|---|---| | `CLIENT` | yes | | | yes | | `SERVER` | yes | | yes | | | `PRODUCER` | | yes | | maybe |