Add 'how to define spans' meta-guidance #3240

lmolkova · 2026-01-03T02:35:37Z

docs/how-to-write-conventions/README.md

kamphaus · 2026-01-05T16:20:57Z

docs/how-to-write-conventions/README.md

+Define spans when:
+
+- The corresponding operation is important for observability.
+- The operation has duration.
+- A new trace context should be created.


Should all or any of these conditions be fulfilled? Are any points optional?

Maybe consider similar phrasing to the Defining attributes conditions.

Suggested change

Define spans when:

- The corresponding operation is important for observability.

- The operation has duration.

- A new trace context should be created.

Define spans when all of the following apply:

- The corresponding operation is important for observability.

- The operation has duration.

- A new trace context should be created.

lmolkova · 2026-01-05T17:41:58Z

docs/how-to-write-conventions/README.md

+Don't try to capture all available properties as span attributes. Telemetry is
+lossy, and it's important to assess the value-to-cost ratio of each referenced attribute.
+
+Capture the details of that specific operation. Parent operations or sub-operations
+will have their own spans.
+
+For example, when recording a call to upload a file to an object store,
+include the endpoint, collection, and object identifier. Don't include details of
+the underlying HTTP/gRPC requests unless there is a strong reason to.


move this to attributes section

lmolkova · 2026-01-05T17:42:21Z

docs/how-to-write-conventions/README.md

+  messaging queue, GenAI model, object store collection), input parameters, and
+  result properties that should be recorded on the span.
+
+- When referencing attributes, refine its properties:


Suggested change

- When referencing attributes, refine its properties:

- When referencing an attribute, refine its properties:

trask · 2026-01-05T21:14:31Z

docs/how-to-write-conventions/README.md

+
+- The corresponding operation is important for observability.
+- The operation has duration.
+- A new trace context should be created.


maybe add a link for trace context? maybe call it span context(?)

trask · 2026-01-05T21:17:50Z

docs/how-to-write-conventions/README.md

+- The operation has duration.
+- A new trace context should be created.
+
+Don't define spans for point-in-time telemetry that does not need new context - use events instead.


I think the parts about not needing a new context is going to be confusing for most readers

wdyt of leaving that out of the main section and have an "exception" section below for messaging?

trask · 2026-01-05T21:20:28Z

docs/how-to-write-conventions/README.md

+Don't try to capture all available properties as span attributes. Telemetry is
+lossy, and it's important to assess the value-to-cost ratio of each referenced attribute.


I didn't follow the tie in to being lossy

trask · 2026-01-05T21:21:56Z

docs/how-to-write-conventions/README.md

+> the duration of the same operation type. For example, the `http.client.request.duration`
+> metric is recorded alongside the corresponding HTTP client span.
+
+A span definition includes the following sections:


I didn't follow this line, is it a heading for the sections below?

trask · 2026-01-05T21:23:55Z

docs/how-to-write-conventions/README.md

+- When the span starts and ends.
+- If this span represents a client call, specify whether it captures the logical call
+  (as observed by the API caller) or the physical call (per-try/per-attempt).
+- Define a span per different operation type.


I'm not sure what this is saying, maybe a short example could help?

trask · 2026-01-05T21:30:07Z

docs/how-to-write-conventions/README.md

+
+Certain conditions can't be clearly classified as errors or not-errors (cancellations,
+HTTP 404 and many others). Avoid using strict requirements - allow instrumentations
+to leverage context they might have to provide accurate status.


Suggested change

to leverage context they might have to provide accurate status.

to leverage context they might have to provide a more accurate status.

trask · 2026-01-05T21:34:54Z

docs/how-to-write-conventions/README.md

+All span definitions MUST include a specific span kind. Don't mix definitions of
+different span kinds.


Don't mix definitions of different span kinds.

maybe this could be clearer, something like a span type(?) should only have one span kind?

trask · 2026-01-05T21:40:57Z

docs/how-to-write-conventions/README.md

+
+- When referencing attributes, refine its properties:
+  - Specify if an attribute is relevant for head-sampling. Such attributes should be
+    provided at start time and would be passed to the sampler. Usually, these are


Suggested change

provided at start time and would be passed to the sampler. Usually, these are

provided at start time so that they will be passed to the sampler. Usually, these are

trask · 2026-01-05T21:45:51Z

docs/how-to-write-conventions/README.md

+- Include some form of operation name that allows identifying different operations
+  of the same type.


"identifying different operations of the same type" seems vague

Maybe "important / useful categories of operations"?

Or could be even more specific and reframe it around {action} {target}?

kamphaus · 2026-01-05T21:56:38Z

docs/how-to-write-conventions/README.md

+
+- Static text should not be included, but can be used as a fallback.
+
+  E.g., we use `GET /{controller}/{action}` instead of `HTTP GET /{controller}/{action}`.


I assume the {action} here was meant to represent a URL path variable and not the action from the span name pattern.

Add how to define spans guidance

db6aafe

lmolkova requested review from a team as code owners January 3, 2026 02:35

github-project-automation bot added this to Semantic Conventions Triage Jan 3, 2026

github-project-automation bot moved this to Untriaged in Semantic Conventions Triage Jan 3, 2026

lmolkova commented Jan 3, 2026

View reviewed changes

docs/how-to-write-conventions/README.md Outdated Show resolved Hide resolved

Apply suggestion from @lmolkova

0b17b67

kamphaus reviewed Jan 5, 2026

View reviewed changes

lmolkova commented Jan 5, 2026

View reviewed changes

trask reviewed Jan 5, 2026

View reviewed changes

kamphaus reviewed Jan 5, 2026

View reviewed changes

	- When referencing attributes, refine its properties:
	- When referencing an attribute, refine its properties:

		Don't try to capture all available properties as span attributes. Telemetry is
		lossy, and it's important to assess the value-to-cost ratio of each referenced attribute.

	to leverage context they might have to provide accurate status.
	to leverage context they might have to provide a more accurate status.

		All span definitions MUST include a specific span kind. Don't mix definitions of
		different span kinds.

	provided at start time and would be passed to the sampler. Usually, these are
	provided at start time so that they will be passed to the sampler. Usually, these are

		- Include some form of operation name that allows identifying different operations
		of the same type.


		- Static text should not be included, but can be used as a fallback.

		E.g., we use `GET /{controller}/{action}` instead of `HTTP GET /{controller}/{action}`.

Add 'how to define spans' meta-guidance #3240

Are you sure you want to change the base?

Add 'how to define spans' meta-guidance #3240

Uh oh!

Conversation

lmolkova commented Jan 3, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants