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.

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 span events vs. attributes guidance #4185

Merged
merged 3 commits into from
Mar 21, 2024
Merged
Changes from all commits
Commits
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
20 changes: 20 additions & 0 deletions content/en/docs/concepts/signals/traces.md
Original file line number Diff line number Diff line change
Expand Up @@ -238,6 +238,12 @@ For example, if a span tracks an operation that adds an item to a user's
shopping cart in an eCommerce system, you can capture the user's ID, the ID of
the item to add to the cart, and the cart ID.

Attributes can be added to spans during span creation or after creation. If you
can add an attribute during span creation, it's preferable to do that compared
to after span creation. That's because it allows those attributes to be used in
SDK sampling. However, if you only have a value to add after the span has been
created, you can just add it to the span when it's available.

Attributes have the following rules that each language SDK implements:

- Keys must be non-null string values
Expand Down Expand Up @@ -267,6 +273,20 @@ and an end.
A Span Event is best used to track the second scenario because it represents a
meaningful, singular point in time.

#### When to use Span Events or Span Attributes

Span Events contain attributes as well, so you may wonder, when is it
appropriate to use a Span Event or create a new Attribute on the current span?

It all comes down to if a specific timestamp is meaningful.

For example, if you are tracking an operation with a span and the operation
completes, you may wish to add data from the operation to your telemetry. If the
timestamp in which the operation completes is important to know, then a Span
Event is an appropriate way to model things with telemetry. However, if the
timestamp is not meaningful, then it's better to attach the data as a Span
Attribute instead.

### Span Links

Links exist so that you can associate one span with one or more spans, implying
Expand Down
Loading