Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify some details about span kind and the meanings of the values. #1738

Merged
merged 3 commits into from
Jun 8, 2021
Merged

Clarify some details about span kind and the meanings of the values. #1738

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4070ac6
Clarify some details about span kind.
Jun 1, 2021
8896f65
Merge branch 'main' into clarify_span_kind
carlosalberto Jun 5, 2021
6dc1a2c
Merge branch 'main' into clarify_span_kind
carlosalberto Jun 8, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 19 additions & 10 deletions specification/trace/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In this section you say both "remote child" and "span with a remote parent". I am afraid "remote child" will be somewhat confusing term. Or at least we have to explicitly define what is "remote child".

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.
Expand All @@ -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
Expand All @@ -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 |
Expand Down