Skip to content
This repository was archived by the owner on Aug 14, 2024. It is now read-only.
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
33 changes: 33 additions & 0 deletions src/docs/sdk/unified-api/tracing.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,8 @@ tree as well as the unit of reporting to Sentry.
- When a `Span` is created, set the `startTimestamp` to the current time
- `SpanContext` is the attribute collection for a `Span` (Can be an implementation detail)
- The relation between parent - child is captured in the property `parentSpanId`
- `Span` should have a method called `toTraceparent` which returns a string `sentry-trace` that could be sent as a header
- Similar `SpanContext` should have a static method called `fromTraceparent` which prefills a `SpanContext` with data received from a `sentry-trace` string
Copy link
Contributor

Choose a reason for hiding this comment

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

  • SpanContext is an implementation detail, as indicated above, so I'd not define required methods on it. from/toTraceparent should be in Span and Transaction. JS defines both methods on Span and they are inherited by Transaction.
  • We need to document the format of the string used for the sentry-trace header.

Copy link
Member Author

Choose a reason for hiding this comment

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

I would say SpanContext while implementation detail we can come with an opinion to have this there.

- `Transaction` Interface
- A `Transaction` internally holds a flat list of child Spans (not a tree structure)
- `Transaction` has additionally a `setName` method the set the name of the transaction
Expand All @@ -86,6 +88,37 @@ tree as well as the unit of reporting to Sentry.
- The `Transport` should implement category-based rate limiting →
- The `Transport` should deal with wrapping a `Transaction` in an `Envelope` internally

## Header `sentry-trace`

`sentry-trace = traceid-spanid-sampling`

With sampling being optional. So at a minimum, it's expected:

`sentry-trace = traceid-spanid`

To offer a minimal compatibility with W3C `traceparent` (without the version prefix) and `b3` (which considers valid both 64 and 128 bits for `traceId`) headers the propagation header should have a `traceId` of 128 bits encoded in 32 hex chars and a `spanId` of 64 bits encoded in 16 hex chars.
To avoid confusion with W3C `traceparent` due to being similar but not the exactly an implementation of it, we call it simply `sentry-trace`.
No version is being defined in the header.

### Sampling

The sampling section is optional. The format is not `flags` to simplify processing it. It's a single char. The possible values are:

```
- No value means defer

0 - Don't sample

1 - Sampled
```

Differently than `b3` a simple sampling decision as a value to `sentry-trace` should not be implemented. [There are reasons to always include](https://github.com/apache/incubator-zipkin-b3-propagation/blob/bc937b6854ea30e46b3e85fbf147d8f4de685dd5/README.md#why-send-trace-ids-with-a-reject-sampling-decision) the `trace-id` and `span-id` regardless of sampling having been decided by the caller. And also this will simplify the implementation.
Besides the [usual reasons to use *defer](https://github.com/apache/incubator-zipkin-b3-propagation/blob/bc937b6854ea30e46b3e85fbf147d8f4de685dd5/README.md#why-defer-a-sampling-decision),* in the case of Sentry, a reason would be if a downstream system captures an error event with Sentry. The decision could be done at that point to sample that trace in order to have tracing data available for the reported crash.

`sentry-trace = sampled`

Which in reality is useful for proxies to set it to `0` and opt out of tracing.

## Static API Changes

The `Sentry.startTransaction` function should take the same arguments as the
Expand Down