Skip to content

Commit 926a8d9

Browse files
Update span events/attributes guidance based on missed feedback (#4190)
Co-authored-by: opentelemetrybot <[email protected]>
1 parent 2904ea5 commit 926a8d9

File tree

1 file changed

+12
-15
lines changed

1 file changed

+12
-15
lines changed

content/en/docs/concepts/signals/traces.md

+12-15
Original file line numberDiff line numberDiff line change
@@ -238,11 +238,9 @@ For example, if a span tracks an operation that adds an item to a user's
238238
shopping cart in an eCommerce system, you can capture the user's ID, the ID of
239239
the item to add to the cart, and the cart ID.
240240

241-
Attributes can be added to spans during span creation or after creation. If you
242-
can add an attribute during span creation, it's preferable to do that compared
243-
to after span creation. That's because it allows those attributes to be used in
244-
SDK sampling. However, if you only have a value to add after the span has been
245-
created, you can just add it to the span when it's available.
241+
You can add attributes to spans during or after span creation. Prefer adding
242+
attributes at span creation to make the attributes available to SDK sampling. If
243+
you have to add a value after span creation, update the span with the value.
246244

247245
Attributes have the following rules that each language SDK implements:
248246

@@ -273,19 +271,18 @@ and an end.
273271
A Span Event is best used to track the second scenario because it represents a
274272
meaningful, singular point in time.
275273

276-
#### When to use Span Events or Span Attributes
274+
#### When to use span events versus span attributes
277275

278-
Span Events contain attributes as well, so you may wonder, when is it
279-
appropriate to use a Span Event or create a new Attribute on the current span?
276+
Since span events also contain attributes, the question of when to use events
277+
instead of attributes might not always have an obvious answer. To inform your
278+
decision, consider whether a specific timestamp is meaningful.
280279

281-
It all comes down to if a specific timestamp is meaningful.
280+
For example, when you're tracking an operation with a span and the operation
281+
completes, you might want to add data from the operation to your telemetry.
282282

283-
For example, if you are tracking an operation with a span and the operation
284-
completes, you may wish to add data from the operation to your telemetry. If the
285-
timestamp in which the operation completes is important to know, then a Span
286-
Event is an appropriate way to model things with telemetry. However, if the
287-
timestamp is not meaningful, then it's better to attach the data as a Span
288-
Attribute instead.
283+
- If the timestamp in which the operation completes is meaningful or relevant,
284+
attach the data to a span event.
285+
- If the timestamp isn't meaningful, attach the data as span attributes.
289286

290287
### Span Links
291288

0 commit comments

Comments
 (0)