Refactor description of span kind #4088

pyohannes · 2024-06-27T12:34:36Z

Changes

This PR provides some re-wording for the SpanKind section of the tracing API specification.

The current wording has caused some confusion, in particular related to consumer and producer spans. Some readers have assumed that a consumer span needs to be a child of the producer span it relates to, however, this is not the case. In particular the wording "logical remote child or parent" has been confusing.

The PR adds clarifications around span links as valid way to correlate spans, as well it avoids the misleading wording of logical child or parents.

This PR just adds clarifications, it doesn't involve any functional changes.

Related issues Clarify semantic of SpanKind regarding parent/child relationships #3172
~~Related OTEP(s) #~~
~~Links to the prototypes (when adding or changing features)~~
CHANGELOG.md file updated for non-trivial changes
~~spec-compliance-matrix.md updated if necessary~~

lmolkova

It seems we don't have clear boundaries between span kinds and rely on the context to explain what they should be (which is confusing to me).

I wonder if we can simplify this section to state that

operations that are requested externally are SERVER/CONSUMER
operations that are requesting work somewhere else are CLIENT/PRODUCER
for everything else we don't know and suggest defining it on case-by-cases basis in the semconv
(non-normative) it's common to describe logical operations as client spans

lmolkova · 2024-06-27T19:08:23Z

specification/trace/api.md

@@ -749,36 +749,36 @@ 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
+`SpanKind` describes the relationship between Spans that are correlated via


nitpicking.

maybe

Suggested change

`SpanKind` describes the relationship between Spans that are correlated via

`SpanKind` clarifies the relationship between Spans that are correlated via

it does not really describe the relationship

lmolkova · 2024-06-27T19:18:05Z

specification/trace/api.md

+The first property described by `SpanKind` reflects whether, from the point of
+view of the library that is being instrumented, a Span sends a message or


more nitpicking:

Suggested change

The first property described by `SpanKind` reflects whether, from the point of

view of the library that is being instrumented, a Span sends a message or

The first property described by `SpanKind` reflects whether, from the instrumentation point of

view, a Span sends a message or

(it's not necessarily a library, it could be FaaS or another piece of infra)

lmolkova · 2024-06-27T19:18:51Z

specification/trace/api.md

-the functionality are built and instrumented. These scenarios, when they occur,
+The first property described by `SpanKind` reflects whether, from the point of
+view of the library that is being instrumented, a Span sends a message or
+request (CLIENT and PRODUCER spans), or whether a Span receives or handles


more nit:
Span sends/span receives -> span describes an operations that (?)

lmolkova · 2024-06-27T19:19:27Z

specification/trace/api.md

+request (CLIENT and PRODUCER spans), or whether a Span receives or handles
+a message or request (SERVER and CONSUMER spans).  Spans with a remote
+parent or remote incoming link are interesting because they are sources of
+external load.  Spans with a remote child remote ougoing links are interesting


Suggested change

external load. Spans with a remote child remote ougoing links are interesting

external load. Spans with a remote child or remote ougoing links are interesting

Suggested change

external load. Spans with a remote child remote ougoing links are interesting

external load. Spans with a remote child or remote outgoing links are interesting

lmolkova · 2024-06-27T19:20:54Z

specification/trace/api.md

+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


I know it was here before, but it does not look right:

Suggested change

guideline, instrumentation should create a new Span prior to extracting and

guideline, instrumentation should create a new Span prior to injecting and

lmolkova · 2024-06-27T19:43:08Z

specification/trace/api.md

  individual messages requires a new `PRODUCER` span per message to
  be created.
-* `CONSUMER` Indicates that the span describes a child of an
+* `CONSUMER` Indicates that the span describes the receiving or handling of an
  asynchronous `PRODUCER` request.
 * `INTERNAL` Default value. Indicates that the span represents an


I think the table ("To summarize the interpretation of these kinds:") is not up to date and should be updated as well:

client is not necessarily remote outgoing, but also logical as note on line 778 indicates (or there are no means to propagate context)

lmolkova · 2024-06-27T19:45:51Z

specification/trace/api.md

+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


since we clarified that DB, messaging, GenAI and potentially other conventions generate client spans which are logical operations that may or may not have transport-level spans and it's actually a common scenario to have nested client spans, could we rephrase it? E.g.

Suggested change

Note: there are complex scenarios where a CLIENT span may have a child that is

Note: CLIENT span may have a child that is

lmolkova · 2024-06-27T19:53:47Z

specification/trace/api.md

+request (CLIENT and PRODUCER spans), or whether a Span receives or handles
+a message or request (SERVER and CONSUMER spans).  Spans with a remote
+parent or remote incoming link are interesting because they are sources of
+external load.  Spans with a remote child remote ougoing links are interesting


I feel using context propagation to express span kinds is not helpful:

initiating a connection can be captured as a CLIENT span, but there are no means to pass the context around.

same with DNS, TLS, streaming calls, which are leaf spans

I wonder if we could rephrase it like

Suggested change

external load. Spans with a remote child remote ougoing links are interesting

external load. It'd useful to distinguish CLIENT spans as such that describe logical or physical calls to external systems or components.

lmolkova · 2024-06-27T19:58:06Z

specification/trace/api.md

+The first property described by `SpanKind` reflects whether, from the point of
+view of the library that is being instrumented, a Span sends a message or
+request (CLIENT and PRODUCER spans), or whether a Span receives or handles
+a message or request (SERVER and CONSUMER spans).  Spans with a remote


Similar to a client concern, context is not really helping to clarify server/consumer kind:

if upstream is not instrumented or my protocol does not support propagation, I have no remote context

if I'm not using upstream context (on a public boundary), it does not mean I should create INTERNAL spans
...

Could we describe SERVER/CONSUMER spans as those that process external load?

github-actions · 2024-07-05T03:17:13Z

This PR was marked stale due to lack of activity. It will be closed in 7 days.

github-actions · 2024-07-16T03:17:52Z

This PR was marked stale due to lack of activity. It will be closed in 7 days.

github-actions · 2024-07-23T03:20:07Z

Closed as inactive. Feel free to reopen if this PR is still being worked on.

Fixes #3172 (Built on top of #4088) ## Changes - Explains kinds without assuming presence of parent/children - Adds links as another correlation mechanism - Normalizes nested client spans even further - database, messaging, RPC, and LLM semantic conventions require CLIENT kind for logical client operation. - Does not touch INTERNAL kind yet - #4179 * [x] Related issues #3172, open-telemetry/semantic-conventions#674, open-telemetry/oteps#172, open-telemetry/semantic-conventions#1315 * ~~[ ] Related [OTEP(s)](https://github.com/open-telemetry/oteps) #~~ * ~~[ ] Links to the prototypes (when adding or changing features)~~ * [x] [`CHANGELOG.md`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/CHANGELOG.md) file updated for non-trivial changes * ~~[ ] [`spec-compliance-matrix.md`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix.md) updated if necessary~~ --------- Co-authored-by: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> Co-authored-by: Yuri Shkuro <yurishkuro@users.noreply.github.com> Co-authored-by: Trask Stalnaker <trask.stalnaker@gmail.com>

Fixes open-telemetry#3172 (Built on top of open-telemetry#4088) ## Changes - Explains kinds without assuming presence of parent/children - Adds links as another correlation mechanism - Normalizes nested client spans even further - database, messaging, RPC, and LLM semantic conventions require CLIENT kind for logical client operation. - Does not touch INTERNAL kind yet - open-telemetry#4179 * [x] Related issues open-telemetry#3172, open-telemetry/semantic-conventions#674, open-telemetry/oteps#172, open-telemetry/semantic-conventions#1315 * ~~[ ] Related [OTEP(s)](https://github.com/open-telemetry/oteps) #~~ * ~~[ ] Links to the prototypes (when adding or changing features)~~ * [x] [`CHANGELOG.md`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/CHANGELOG.md) file updated for non-trivial changes * ~~[ ] [`spec-compliance-matrix.md`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix.md) updated if necessary~~ --------- Co-authored-by: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> Co-authored-by: Yuri Shkuro <yurishkuro@users.noreply.github.com> Co-authored-by: Trask Stalnaker <trask.stalnaker@gmail.com>

pyohannes added 2 commits June 27, 2024 14:26

Refactor description span relationships

27eab20

Fix formatting

e34aadb

lmolkova reviewed Jun 27, 2024

View reviewed changes

github-actions bot added the Stale label Jul 5, 2024

carlosalberto removed the Stale label Jul 8, 2024

lmolkova mentioned this pull request Jul 8, 2024

Activities for Http Connections, Dns, Sockets and SslStream dotnet/runtime#103922

Merged

pyohannes mentioned this pull request Jul 15, 2024

Give exhaustive specification of span kinds for messaging spans open-telemetry/semantic-conventions#1171

Merged

3 tasks

github-actions bot added the Stale label Jul 16, 2024

github-actions bot closed this Jul 23, 2024

lmolkova mentioned this pull request Aug 6, 2024

Refactor description of span kind #4178

Merged

2 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Refactor description of span kind #4088

Refactor description of span kind #4088

pyohannes commented Jun 27, 2024

lmolkova left a comment

lmolkova Jun 27, 2024

lmolkova Jun 27, 2024

lmolkova Jun 27, 2024

lmolkova Jun 27, 2024

kenfinnigan Jun 27, 2024

lmolkova Jun 27, 2024

lmolkova Jun 27, 2024 •

edited

Loading

lmolkova Jun 27, 2024 •

edited

Loading

lmolkova Jun 27, 2024 •

edited

Loading

lmolkova Jun 27, 2024 •

edited

Loading

github-actions bot commented Jul 5, 2024

github-actions bot commented Jul 16, 2024

github-actions bot commented Jul 23, 2024

	`SpanKind` describes the relationship between Spans that are correlated via
	`SpanKind` clarifies the relationship between Spans that are correlated via

		The first property described by `SpanKind` reflects whether, from the point of
		view of the library that is being instrumented, a Span sends a message or

	external load. Spans with a remote child remote ougoing links are interesting
	external load. Spans with a remote child or remote ougoing links are interesting

	guideline, instrumentation should create a new Span prior to extracting and
	guideline, instrumentation should create a new Span prior to injecting and

	Note: there are complex scenarios where a CLIENT span may have a child that is
	Note: CLIENT span may have a child that is

	external load. Spans with a remote child remote ougoing links are interesting
	external load. It'd useful to distinguish CLIENT spans as such that describe logical or physical calls to external systems or components.

Refactor description of span kind #4088

Refactor description of span kind #4088

Conversation

pyohannes commented Jun 27, 2024

Changes

lmolkova left a comment

Choose a reason for hiding this comment

lmolkova Jun 27, 2024

Choose a reason for hiding this comment

lmolkova Jun 27, 2024

Choose a reason for hiding this comment

lmolkova Jun 27, 2024

Choose a reason for hiding this comment

lmolkova Jun 27, 2024

Choose a reason for hiding this comment

kenfinnigan Jun 27, 2024

Choose a reason for hiding this comment

lmolkova Jun 27, 2024

Choose a reason for hiding this comment

lmolkova Jun 27, 2024 • edited Loading

Choose a reason for hiding this comment

lmolkova Jun 27, 2024 • edited Loading

Choose a reason for hiding this comment

lmolkova Jun 27, 2024 • edited Loading

Choose a reason for hiding this comment

lmolkova Jun 27, 2024 • edited Loading

Choose a reason for hiding this comment

github-actions bot commented Jul 5, 2024

github-actions bot commented Jul 16, 2024

github-actions bot commented Jul 23, 2024

lmolkova Jun 27, 2024 •

edited

Loading

lmolkova Jun 27, 2024 •

edited

Loading

lmolkova Jun 27, 2024 •

edited

Loading

lmolkova Jun 27, 2024 •

edited

Loading