Refactor description of span kind

CHANGELOG.md

@@ -13,6 +13,9 @@ release.
 
 - Minor clarification on BatchExportingProcessor behavior.
   ([#4164](https://github.com/open-telemetry/opentelemetry-specification/pull/4164))
+- 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
 

specification/trace/api.md

@@ -749,68 +749,68 @@ This functionality MUST be fully implemented in the API, and SHOULD NOT be overr
 
 ## SpanKind
 
-`SpanKind` describes the relationship between the Span, its parents,
-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 "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.
-
-The second property described by `SpanKind` reflects whether a child
-Span represents a synchronous call.  When a child span is synchronous,
-the parent is expected to wait for it to 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.
+`SpanKind` clarifies the relationship between Spans that are correlated via
+parent/child relationships or span links. `SpanKind` describes two independent
+properties that benefit tracing systems during analysis:
+
+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 directly as the parent of another
-remote span.  As a simple guideline, instrumentation should create a
-new Span prior to extracting and serializing the SpanContext for a
-remote call.
+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.
+
+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.
+
+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.
 
-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.
+Such scenarios, when they occur, should be detailed in the semantic conventions
+appropriate to the relevant technologies.
 
-These are the possible SpanKinds:
+These are the possible `SpanKind`s:
 
 * `SERVER` Indicates that the span covers server-side handling of a
-  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 a child of an
-  asynchronous `PRODUCER` request.
+  synchronous RPC or other remote request.
+* `CLIENT` Indicates that the span describes a synchronous request to
+  a remote service.
+  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.
+* `CONSUMER` Indicates that the span describes the receiving or handling of an
+  asynchronous request.
 * `INTERNAL` Default value. Indicates that the span represents an
   internal operation within an application, as opposed to an
   operations with remote parents or children.
 
 To summarize the interpretation of these kinds:
 
 | `SpanKind` | Synchronous | Asynchronous | Remote Incoming | Remote Outgoing |
-|---|---|---|---|---|
-| `CLIENT` | yes | | | yes |
-| `SERVER` | yes | | yes | |
-| `PRODUCER` | | yes | | maybe |
-| `CONSUMER` | | yes | maybe | |
-| `INTERNAL` | | | | |
+|------------|-------------|--------------|-----------------|-----------------|
+| `CLIENT`   |     yes     |              |                 |       yes       |
+| `SERVER`   |     yes     |              |       yes       |                 |
+| `PRODUCER` |             |     yes      |                 |       maybe     |
+| `CONSUMER` |             |     yes      |      maybe      |                 |
+| `INTERNAL` |             |              |                 |                 |
 
 ## Link