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

Merged
merged 3 commits into from
Mar 21, 2024
Merged

Clarify span events vs. attributes guidance #4185

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
72817db
Clarify span events vs. attributes guidance
cartermp Mar 20, 2024
ba1b2ee
Merge branch 'main' into cartermp-patch-2
cartermp Mar 21, 2024
0bc60a5
Results from /fix:format
opentelemetrybot Mar 21, 2024
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
19 changes: 19 additions & 0 deletions content/en/docs/concepts/signals/traces.md
View file
Open in desktop
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.
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
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.
You can add attributes to spans during or after span creation. Always add
attributes at span creation to make the attributes available to SDK sampling.
If you have to add a value after span creation, update the span with the value.


Attributes have the following rules that each language SDK implements:

- Keys must be non-null string values
Expand Down Expand Up @@ -267,6 +273,19 @@ 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.
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
#### 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.
#### When to use span events versus span attributes
Since span events also contain attributes, the question of when to use events
instead of attributes might not always have an obvious answer. To inform your
decision, consider whether a specific timestamp is meaningful.
For example, when you're tracking an operation with a span and the operation
completes, you might want to add data from the operation to your telemetry.
- If the timestamp in which the operation completes is meaningful or relevant,
attach the data to a span event.
- If the timestamp isn't meaningful, attach the data as a span attribute.


### Span Links

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