From b9ff9b5ffe04174e7c6c31744db58e665c0d5b48 Mon Sep 17 00:00:00 2001 From: Daniel Griesser Date: Tue, 22 Sep 2020 15:39:29 +0200 Subject: [PATCH 1/3] feat: Add from/to traceparent --- src/docs/sdk/unified-api/tracing.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/docs/sdk/unified-api/tracing.mdx b/src/docs/sdk/unified-api/tracing.mdx index b3059333b0..a654ad6e81 100644 --- a/src/docs/sdk/unified-api/tracing.mdx +++ b/src/docs/sdk/unified-api/tracing.mdx @@ -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 - `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 From 92310eb311cbec13aed804f38b64caf0e5d38639 Mon Sep 17 00:00:00 2001 From: Daniel Griesser Date: Wed, 23 Sep 2020 12:43:40 +0200 Subject: [PATCH 2/3] feat: Add sentry-trace header docs --- src/docs/sdk/unified-api/tracing.mdx | 31 ++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/src/docs/sdk/unified-api/tracing.mdx b/src/docs/sdk/unified-api/tracing.mdx index a654ad6e81..6bcf40592c 100644 --- a/src/docs/sdk/unified-api/tracing.mdx +++ b/src/docs/sdk/unified-api/tracing.mdx @@ -88,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 *not* 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 From 5627eda98e14741a46f52530ba0e57080ce2ef8a Mon Sep 17 00:00:00 2001 From: Daniel Griesser Date: Wed, 23 Sep 2020 14:17:39 +0200 Subject: [PATCH 3/3] Update src/docs/sdk/unified-api/tracing.mdx Co-authored-by: Rodolfo Carvalho --- src/docs/sdk/unified-api/tracing.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docs/sdk/unified-api/tracing.mdx b/src/docs/sdk/unified-api/tracing.mdx index 6bcf40592c..d510b574ce 100644 --- a/src/docs/sdk/unified-api/tracing.mdx +++ b/src/docs/sdk/unified-api/tracing.mdx @@ -113,7 +113,7 @@ The sampling section is optional. The format is not `flags` to simplify processi ``` 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 *not* sample that trace in order to have tracing data available for the reported crash. +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`