From faa85a832eca3f3d417816b5d52d527403aeb8cb Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Tue, 13 Sep 2022 13:43:02 +0200 Subject: [PATCH 01/13] feat: OpenTelemetry Spec --- src/components/sidebar.tsx | 1 + src/docs/sdk/performance/opentelemetry.mdx | 46 ++++++++++++++++++++++ 2 files changed, 47 insertions(+) create mode 100644 src/docs/sdk/performance/opentelemetry.mdx diff --git a/src/components/sidebar.tsx b/src/components/sidebar.tsx index fc253334ae..6a54ce8854 100644 --- a/src/components/sidebar.tsx +++ b/src/components/sidebar.tsx @@ -226,6 +226,7 @@ export default () => { Span Operations Dynamic Sampling Context + OpenTelemetry Support diff --git a/src/docs/sdk/performance/opentelemetry.mdx b/src/docs/sdk/performance/opentelemetry.mdx new file mode 100644 index 0000000000..63d6f964f8 --- /dev/null +++ b/src/docs/sdk/performance/opentelemetry.mdx @@ -0,0 +1,46 @@ +--- +title: "OpenTelemetry Support" +--- + + + +This page is under active development. Specifications are not final and subject to change. + +"Proof is in the progress" - Drake + + + +This document details Sentry's work in integrating and supporting [OpenTelemetry](https://opentelemetry.io/), the open standard for metrics, traces and logs. In particular, it focuses on the integration between [Sentry's performance monitoring product](https://docs.sentry.io/product/performance/) and [OpenTelemetry's tracing spec](https://opentelemetry.io/docs/concepts/signals/traces/). + +## Background + +When Sentry performance monitoring was initially introduced, OpenTelemetry was in early stages. This lead to us adopt a slightly different model from OpenTelemetry, notably we have this concept of transactions that OpenTelemetry does not have. We've described this, and some more historical background, in our [performance monitoring research document](../research/performance/index.mdx). + +TODO: Add history about OpenTelemetry Sentry Exporter: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/sentryexporter + +## Approach + +TODO: Talk about the approach we are using, based on Matt's hackweek project - https://github.com/getsentry/sentry-ruby/pull/1876 + +## Protocol + +Below describe the transformations between an OpenTelemetry span and a Sentry Span. Related: [the interface for a Sentry Span](https://develop.sentry.dev/sdk/event-payloads/span/), [the Relay spec for a Sentry Span](https://github.com/getsentry/relay/blob/master/relay-general/src/protocol/span.rs) and the spec for an [OpenTelemetry span](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L80-L256). + +This is based on a mapping done as part of work on the [OpenTelemetry Sentry Exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/exporter/sentryexporter/docs/transformation.md). + +| OpenTelemetry Span | SentrySpan | Note | +| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Span.TraceID](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L81-L89) | [Span.trace_id](https://github.com/getsentry/relay/blob/7fb4ef6546cbe27c2b6e101dc46fd36cbe273d57/relay-general/src/protocol/span.rs#L37) | | +| [Span.SpanID](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L91-L99) | [Span.span_id](https://github.com/getsentry/relay/blob/7fb4ef6546cbe27c2b6e101dc46fd36cbe273d57/relay-general/src/protocol/span.rs#L30) | | +| [Span.ParentSpanID](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L106-L108) | [Span.parent_span_id](https://github.com/getsentry/relay/blob/7fb4ef6546cbe27c2b6e101dc46fd36cbe273d57/relay-general/src/protocol/span.rs#L33) | | +| [Span.ParentSpanID](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L106-L108) | [Span.parent_span_id](https://github.com/getsentry/relay/blob/7fb4ef6546cbe27c2b6e101dc46fd36cbe273d57/relay-general/src/protocol/span.rs#L33) | If a span does not have a parent span ID, it is a root span. For a root span:
  • If there is an active Sentry transaction, add it to the transaction
  • If there is no active Sentry transaction, construct a new transaction from that span
    • | +| [Span.Name](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L110-L121), [Span.Attributes](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L174-L186), [Span.Kind](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L153-L156) | [Span.description](https://github.com/getsentry/relay/blob/7fb4ef6546cbe27c2b6e101dc46fd36cbe273d57/relay-general/src/protocol/span.rs#L22) | The span description is decided using OpenTelemetry Semantic Conventions. Generally, the OpenTelemetry [Span.Name](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L110-L121) maps to a Sentry [Span.description](https://github.com/getsentry/relay/blob/7fb4ef6546cbe27c2b6e101dc46fd36cbe273d57/relay-general/src/protocol/span.rs#L22). | + +### Semantic Conventions + +Using the [Span.Name](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L110-L121), [Span.Attributes](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L174-L186), and [Span.Kind](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L153-L156) of OpenTelemetry Spans, we can generate ops, descriptions, and tags. This exact mapping is described below. + +## SDK Spec + +- SpanProcessor: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#span-processor +- Propogator: https://opentelemetry.io/docs/reference/specification/context/api-propagators/ From 4465be8e45a36967543fd5810f1cd0ff5f560dbc Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Thu, 15 Sep 2022 15:51:06 +0200 Subject: [PATCH 02/13] remove broken links --- src/docs/sdk/performance/opentelemetry.mdx | 42 +++++++++++++++++----- 1 file changed, 34 insertions(+), 8 deletions(-) diff --git a/src/docs/sdk/performance/opentelemetry.mdx b/src/docs/sdk/performance/opentelemetry.mdx index 63d6f964f8..76f8abd505 100644 --- a/src/docs/sdk/performance/opentelemetry.mdx +++ b/src/docs/sdk/performance/opentelemetry.mdx @@ -14,7 +14,7 @@ This document details Sentry's work in integrating and supporting [OpenTelemetry ## Background -When Sentry performance monitoring was initially introduced, OpenTelemetry was in early stages. This lead to us adopt a slightly different model from OpenTelemetry, notably we have this concept of transactions that OpenTelemetry does not have. We've described this, and some more historical background, in our [performance monitoring research document](../research/performance/index.mdx). +When Sentry performance monitoring was initially introduced, OpenTelemetry was in early stages. This lead to us adopt a slightly different model from OpenTelemetry, notably we have this concept of transactions that OpenTelemetry does not have. We've described this, and some more historical background, in our performance monitoring research document. TODO: Add history about OpenTelemetry Sentry Exporter: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/sentryexporter @@ -24,22 +24,48 @@ TODO: Talk about the approach we are using, based on Matt's hackweek project - h ## Protocol +### Transaction Protocol + +TODO: Talk about generating transactions + +### Span Protocol + Below describe the transformations between an OpenTelemetry span and a Sentry Span. Related: [the interface for a Sentry Span](https://develop.sentry.dev/sdk/event-payloads/span/), [the Relay spec for a Sentry Span](https://github.com/getsentry/relay/blob/master/relay-general/src/protocol/span.rs) and the spec for an [OpenTelemetry span](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L80-L256). This is based on a mapping done as part of work on the [OpenTelemetry Sentry Exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/exporter/sentryexporter/docs/transformation.md). -| OpenTelemetry Span | SentrySpan | Note | -| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Span.TraceID](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L81-L89) | [Span.trace_id](https://github.com/getsentry/relay/blob/7fb4ef6546cbe27c2b6e101dc46fd36cbe273d57/relay-general/src/protocol/span.rs#L37) | | -| [Span.SpanID](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L91-L99) | [Span.span_id](https://github.com/getsentry/relay/blob/7fb4ef6546cbe27c2b6e101dc46fd36cbe273d57/relay-general/src/protocol/span.rs#L30) | | -| [Span.ParentSpanID](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L106-L108) | [Span.parent_span_id](https://github.com/getsentry/relay/blob/7fb4ef6546cbe27c2b6e101dc46fd36cbe273d57/relay-general/src/protocol/span.rs#L33) | | -| [Span.ParentSpanID](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L106-L108) | [Span.parent_span_id](https://github.com/getsentry/relay/blob/7fb4ef6546cbe27c2b6e101dc46fd36cbe273d57/relay-general/src/protocol/span.rs#L33) | If a span does not have a parent span ID, it is a root span. For a root span:
  • If there is an active Sentry transaction, add it to the transaction
  • If there is no active Sentry transaction, construct a new transaction from that span
    • | -| [Span.Name](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L110-L121), [Span.Attributes](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L174-L186), [Span.Kind](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L153-L156) | [Span.description](https://github.com/getsentry/relay/blob/7fb4ef6546cbe27c2b6e101dc46fd36cbe273d57/relay-general/src/protocol/span.rs#L22) | The span description is decided using OpenTelemetry Semantic Conventions. Generally, the OpenTelemetry [Span.Name](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L110-L121) maps to a Sentry [Span.description](https://github.com/getsentry/relay/blob/7fb4ef6546cbe27c2b6e101dc46fd36cbe273d57/relay-general/src/protocol/span.rs#L22). | + + +| OpenTelemetry Span | Sentry Span | Note | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Span.TraceID](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L81-L89) | [Span.trace_id](https://github.com/getsentry/relay/blob/7fb4ef6546cbe27c2b6e101dc46fd36cbe273d57/relay-general/src/protocol/span.rs#L37) | | +| [Span.SpanID](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L91-L99) | [Span.span_id](https://github.com/getsentry/relay/blob/7fb4ef6546cbe27c2b6e101dc46fd36cbe273d57/relay-general/src/protocol/span.rs#L30) | | +| [Span.ParentSpanID](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L106-L108) | [Span.parent_span_id](https://github.com/getsentry/relay/blob/7fb4ef6546cbe27c2b6e101dc46fd36cbe273d57/relay-general/src/protocol/span.rs#L33) | | +| [Span.ParentSpanID](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L106-L108) | [Span.parent_span_id](https://github.com/getsentry/relay/blob/7fb4ef6546cbe27c2b6e101dc46fd36cbe273d57/relay-general/src/protocol/span.rs#L33) | If a span does not have a parent span ID, it is a root span. For a root span:
  • If there is an active Sentry transaction, add it to the transaction
  • If there is no active Sentry transaction, construct a new transaction from that span
    • | +| [Span.Name](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L110-L121), [Span.Attributes](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L174-L186), [Span.Kind](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L153-L156) | [Span.description](https://github.com/getsentry/relay/blob/7fb4ef6546cbe27c2b6e101dc46fd36cbe273d57/relay-general/src/protocol/span.rs#L22) | The span description is decided using OpenTelemetry Semantic Conventions. Generally, the OpenTelemetry [Span.Name](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L110-L121) maps to a Sentry [Span.description](https://github.com/getsentry/relay/blob/7fb4ef6546cbe27c2b6e101dc46fd36cbe273d57/relay-general/src/protocol/span.rs#L22). | +| [Span.Name](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L110-L121), [Span.Attributes](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L174-L186), [Span.Kind](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L153-L156) | [Span.op](https://github.com/getsentry/relay/blob/d7c5698888a2148799697d5427b37bfbe3b895bc/relay-general/src/protocol/span.rs#L26) | + +- TODO: Talk about generating stuff (breadcrumbs/error events) from Span Events: https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/48ee3288c030ed32374125190a8abf7ced1a4238/exporter/sentryexporter/sentry_exporter.go#L167-L202 ### Semantic Conventions Using the [Span.Name](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L110-L121), [Span.Attributes](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L174-L186), and [Span.Kind](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L153-L156) of OpenTelemetry Spans, we can generate ops, descriptions, and tags. This exact mapping is described below. +TODO: Talk about what we do here: https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/48ee3288c030ed32374125190a8abf7ced1a4238/exporter/sentryexporter/sentry_exporter.go#L226-L267 + ## SDK Spec - SpanProcessor: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#span-processor From b14691817b776cea34b5e204ec5fbeea52df26fc Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Thu, 15 Sep 2022 15:54:47 +0200 Subject: [PATCH 03/13] remove table comment that borks the mdx transpiler :thinking: --- src/docs/sdk/performance/opentelemetry.mdx | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/src/docs/sdk/performance/opentelemetry.mdx b/src/docs/sdk/performance/opentelemetry.mdx index 76f8abd505..31ec2b8167 100644 --- a/src/docs/sdk/performance/opentelemetry.mdx +++ b/src/docs/sdk/performance/opentelemetry.mdx @@ -34,21 +34,6 @@ Below describe the transformations between an OpenTelemetry span and a Sentry Sp This is based on a mapping done as part of work on the [OpenTelemetry Sentry Exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/exporter/sentryexporter/docs/transformation.md). - - | OpenTelemetry Span | Sentry Span | Note | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Span.TraceID](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L81-L89) | [Span.trace_id](https://github.com/getsentry/relay/blob/7fb4ef6546cbe27c2b6e101dc46fd36cbe273d57/relay-general/src/protocol/span.rs#L37) | | From 6d374fc226103a5e6a0b5e0110efca9fd643240a Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Mon, 19 Sep 2022 10:59:00 +0200 Subject: [PATCH 04/13] get span protocol down --- src/docs/sdk/performance/opentelemetry.mdx | 57 --- .../sdk/performance/opentelemetry/index.mdx | 44 +++ .../opentelemetry/span-protocol.mdx | 337 ++++++++++++++++++ 3 files changed, 381 insertions(+), 57 deletions(-) delete mode 100644 src/docs/sdk/performance/opentelemetry.mdx create mode 100644 src/docs/sdk/performance/opentelemetry/index.mdx create mode 100644 src/docs/sdk/performance/opentelemetry/span-protocol.mdx diff --git a/src/docs/sdk/performance/opentelemetry.mdx b/src/docs/sdk/performance/opentelemetry.mdx deleted file mode 100644 index 31ec2b8167..0000000000 --- a/src/docs/sdk/performance/opentelemetry.mdx +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: "OpenTelemetry Support" ---- - - - -This page is under active development. Specifications are not final and subject to change. - -"Proof is in the progress" - Drake - - - -This document details Sentry's work in integrating and supporting [OpenTelemetry](https://opentelemetry.io/), the open standard for metrics, traces and logs. In particular, it focuses on the integration between [Sentry's performance monitoring product](https://docs.sentry.io/product/performance/) and [OpenTelemetry's tracing spec](https://opentelemetry.io/docs/concepts/signals/traces/). - -## Background - -When Sentry performance monitoring was initially introduced, OpenTelemetry was in early stages. This lead to us adopt a slightly different model from OpenTelemetry, notably we have this concept of transactions that OpenTelemetry does not have. We've described this, and some more historical background, in our performance monitoring research document. - -TODO: Add history about OpenTelemetry Sentry Exporter: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/sentryexporter - -## Approach - -TODO: Talk about the approach we are using, based on Matt's hackweek project - https://github.com/getsentry/sentry-ruby/pull/1876 - -## Protocol - -### Transaction Protocol - -TODO: Talk about generating transactions - -### Span Protocol - -Below describe the transformations between an OpenTelemetry span and a Sentry Span. Related: [the interface for a Sentry Span](https://develop.sentry.dev/sdk/event-payloads/span/), [the Relay spec for a Sentry Span](https://github.com/getsentry/relay/blob/master/relay-general/src/protocol/span.rs) and the spec for an [OpenTelemetry span](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L80-L256). - -This is based on a mapping done as part of work on the [OpenTelemetry Sentry Exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/exporter/sentryexporter/docs/transformation.md). - -| OpenTelemetry Span | Sentry Span | Note | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Span.TraceID](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L81-L89) | [Span.trace_id](https://github.com/getsentry/relay/blob/7fb4ef6546cbe27c2b6e101dc46fd36cbe273d57/relay-general/src/protocol/span.rs#L37) | | -| [Span.SpanID](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L91-L99) | [Span.span_id](https://github.com/getsentry/relay/blob/7fb4ef6546cbe27c2b6e101dc46fd36cbe273d57/relay-general/src/protocol/span.rs#L30) | | -| [Span.ParentSpanID](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L106-L108) | [Span.parent_span_id](https://github.com/getsentry/relay/blob/7fb4ef6546cbe27c2b6e101dc46fd36cbe273d57/relay-general/src/protocol/span.rs#L33) | | -| [Span.ParentSpanID](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L106-L108) | [Span.parent_span_id](https://github.com/getsentry/relay/blob/7fb4ef6546cbe27c2b6e101dc46fd36cbe273d57/relay-general/src/protocol/span.rs#L33) | If a span does not have a parent span ID, it is a root span. For a root span:
  • If there is an active Sentry transaction, add it to the transaction
  • If there is no active Sentry transaction, construct a new transaction from that span
    • | -| [Span.Name](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L110-L121), [Span.Attributes](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L174-L186), [Span.Kind](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L153-L156) | [Span.description](https://github.com/getsentry/relay/blob/7fb4ef6546cbe27c2b6e101dc46fd36cbe273d57/relay-general/src/protocol/span.rs#L22) | The span description is decided using OpenTelemetry Semantic Conventions. Generally, the OpenTelemetry [Span.Name](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L110-L121) maps to a Sentry [Span.description](https://github.com/getsentry/relay/blob/7fb4ef6546cbe27c2b6e101dc46fd36cbe273d57/relay-general/src/protocol/span.rs#L22). | -| [Span.Name](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L110-L121), [Span.Attributes](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L174-L186), [Span.Kind](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L153-L156) | [Span.op](https://github.com/getsentry/relay/blob/d7c5698888a2148799697d5427b37bfbe3b895bc/relay-general/src/protocol/span.rs#L26) | - -- TODO: Talk about generating stuff (breadcrumbs/error events) from Span Events: https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/48ee3288c030ed32374125190a8abf7ced1a4238/exporter/sentryexporter/sentry_exporter.go#L167-L202 - -### Semantic Conventions - -Using the [Span.Name](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L110-L121), [Span.Attributes](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L174-L186), and [Span.Kind](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L153-L156) of OpenTelemetry Spans, we can generate ops, descriptions, and tags. This exact mapping is described below. - -TODO: Talk about what we do here: https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/48ee3288c030ed32374125190a8abf7ced1a4238/exporter/sentryexporter/sentry_exporter.go#L226-L267 - -## SDK Spec - -- SpanProcessor: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#span-processor -- Propogator: https://opentelemetry.io/docs/reference/specification/context/api-propagators/ diff --git a/src/docs/sdk/performance/opentelemetry/index.mdx b/src/docs/sdk/performance/opentelemetry/index.mdx new file mode 100644 index 0000000000..1146cfc49d --- /dev/null +++ b/src/docs/sdk/performance/opentelemetry/index.mdx @@ -0,0 +1,44 @@ +--- +title: "OpenTelemetry Support" +--- + + + +This page is under active development. Specifications are not final and subject to change. + +"Proof is in the progress" - Drake + + + +This document details Sentry's work in integrating and supporting [OpenTelemetry](https://opentelemetry.io/), the open standard for metrics, traces and logs. In particular, it focuses on the integration between [Sentry's performance monitoring product](https://docs.sentry.io/product/performance/) and [OpenTelemetry's tracing spec](https://opentelemetry.io/docs/concepts/signals/traces/). + +## Background + +When Sentry performance monitoring was initially introduced, OpenTelemetry was in early stages. This lead to us adopt a slightly different model from OpenTelemetry, notably we have this concept of transactions that OpenTelemetry does not have. We've described this, and some more historical background, in our performance monitoring research document. + +TODO: Add history about OpenTelemetry Sentry Exporter: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/sentryexporter + +## Approach + +TODO: Talk about the approach we are using, based on Matt's hackweek project - https://github.com/getsentry/sentry-ruby/pull/1876 + +## Transaction Protocol + +TODO: Talk about generating transactions + +## Span Protocol + +import "./span-protocol.mdx" + +- TODO: Talk about generating stuff (breadcrumbs/error events) from Span Events: https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/48ee3288c030ed32374125190a8abf7ced1a4238/exporter/sentryexporter/sentry_exporter.go#L167-L202 + +### Semantic Conventions + +Using the [Span.Name](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L110-L121), [Span.Attributes](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L174-L186), and [Span.Kind](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L153-L156) of OpenTelemetry Spans, we can generate ops, descriptions, and tags. This exact mapping is described below. + +TODO: Talk about what we do here: https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/48ee3288c030ed32374125190a8abf7ced1a4238/exporter/sentryexporter/sentry_exporter.go#L226-L267 + +## SDK Spec + +- SpanProcessor: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#span-processor +- Propogator: https://opentelemetry.io/docs/reference/specification/context/api-propagators/ diff --git a/src/docs/sdk/performance/opentelemetry/span-protocol.mdx b/src/docs/sdk/performance/opentelemetry/span-protocol.mdx new file mode 100644 index 0000000000..4b089e6c4d --- /dev/null +++ b/src/docs/sdk/performance/opentelemetry/span-protocol.mdx @@ -0,0 +1,337 @@ +Below describe the transformations between an OpenTelemetry span and a Sentry Span. Related: [the interface for a Sentry Span](https://develop.sentry.dev/sdk/event-payloads/span/), [the Relay spec for a Sentry Span](https://github.com/getsentry/relay/blob/master/relay-general/src/protocol/span.rs) and the spec for an [OpenTelemetry span](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L80-L256). + +This is based on a mapping done as part of work on the [OpenTelemetry Sentry Exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/exporter/sentryexporter/docs/transformation.md). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    OpenTelemetry SpanSentry SpanNotes
    + + Span.trace_id + + + + Span.trace_id + +
    + + Span.span_id + + + + Span.span_id + +
    + + Span.parent_span_id + + + + Span.parent_span_id + + + If a span does not have a parent span ID, it is a root span. For + a root span: +
  • + If there is an active Sentry transaction, add it to the + transaction +
    • +
  • + If there is no active Sentry transaction, construct a new + transaction from that span +
    • +
    + + Span.name + + + Span.attributes + + + Span.kind + + + + Span.description + + + The span description is decided using OpenTelemetry Semantic + Conventions. Generally, the OpenTelemetry + + Span.name + + maps to a Sentry + + Span.description + +
    + + Span.name + + + Span.attributes + + + Span.kind + + + + Span.op + +
    + + Span.attributes + + + Span.kind + + + Span.Status + + + + Span.tags + + + The OpenTelemetry Span Status message and span kind are set as tags on the Sentry span. +
    + + Span.attributes + + + Span.Status + + + + Span.status + + + See Span Status for more details +
    + + Span.start_time_unix_nano + + + + Span.start_timestamp + +
    + + Span.end_time_unix_nano + + + + Span.timestamp + +
    + +### Span Status + +In OpenTelemetry, [Span Status is an enum of 3 values](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#set-status), while [Sentry's Span Status is an enum of 17 values](https://github.com/getsentry/relay/blob/ed3a521f773ecd4bf9a2aefd7af80080d56d0841/relay-common/src/constants.rs#L200-L286) that map to the [GRPC status codes](https://github.com/grpc/grpc/blob/master/doc/statuscodes.md). Each of the Sentry Span Status codes also map to HTTP codes. Sentry adopted it's Span Status spec from OpenTelemetry, [who used the GRPC status code spec](https://github.com/open-telemetry/opentelemetry-specification/blob/8fb6c14e4709e75a9aaa64b0dbbdf02a6067682a/specification/api-tracing.md#status), but later on changed to the current spec it uses today. + +To map from OpenTelemetry Span Status to, you need to rely on both OpenTelemetry [Span Status](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L253-L255) and [Span attributes](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L174-L186). This approach was adapted from a PR by GH user [@anguisa](https://github.com/anguisa) to the [OpenTelemetry Sentry Exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/pull/13407). + + +```go +// OpenTelemetry span status can be Unset, Ok, Error. HTTP and Grpc codes contained in tags can make it more detailed. + +// canonicalCodesHTTPMap maps some HTTP codes to Sentry's span statuses. See possible mapping in https://develop.sentry.dev/sdk/event-payloads/span/ +var canonicalCodesHTTPMap = map[string]sentry.SpanStatus{ + "400": sentry.SpanStatusFailedPrecondition, // SpanStatusInvalidArgument, SpanStatusOutOfRange + "401": sentry.SpanStatusUnauthenticated, + "403": sentry.SpanStatusPermissionDenied, + "404": sentry.SpanStatusNotFound, + "409": sentry.SpanStatusAborted, // SpanStatusAlreadyExists + "429": sentry.SpanStatusResourceExhausted, + "499": sentry.SpanStatusCanceled, + "500": sentry.SpanStatusInternalError, // SpanStatusDataLoss, SpanStatusUnknown + "501": sentry.SpanStatusUnimplemented, + "503": sentry.SpanStatusUnavailable, + "504": sentry.SpanStatusDeadlineExceeded, +} + +// canonicalCodesGrpcMap maps some GRPC codes to Sentry's span statuses. See description in grpc documentation. +var canonicalCodesGrpcMap = map[string]sentry.SpanStatus{ + "1": sentry.SpanStatusCanceled, + "2": sentry.SpanStatusUnknown, + "3": sentry.SpanStatusInvalidArgument, + "4": sentry.SpanStatusDeadlineExceeded, + "5": sentry.SpanStatusNotFound, + "6": sentry.SpanStatusAlreadyExists, + "7": sentry.SpanStatusPermissionDenied, + "8": sentry.SpanStatusResourceExhausted, + "9": sentry.SpanStatusFailedPrecondition, + "10": sentry.SpanStatusAborted, + "11": sentry.SpanStatusOutOfRange, + "12": sentry.SpanStatusUnimplemented, + "13": sentry.SpanStatusInternalError, + "14": sentry.SpanStatusUnavailable, + "15": sentry.SpanStatusDataLoss, + "16": sentry.SpanStatusUnauthenticated, +} + +code := spanStatus.Code() +if code < 0 || int(code) > 2 { + return sentry.SpanStatusUnknown, fmt.Sprintf("error code %d", code) +} +httpCode, foundHTTPCode := tags["http.status_code"] +grpcCode, foundGrpcCode := tags["rpc.grpc.status_code"] +var sentryStatus sentry.SpanStatus +switch { +case code == 1 || code == 0: + sentryStatus = sentry.SpanStatusOK +case foundHTTPCode: + httpStatus, foundHTTPStatus := canonicalCodesHTTPMap[httpCode] + switch { + case foundHTTPStatus: + sentryStatus = httpStatus + default: + sentryStatus = sentry.SpanStatusUnknown + } +case foundGrpcCode: + grpcStatus, foundGrpcStatus := canonicalCodesGrpcMap[grpcCode] + switch { + case foundGrpcStatus: + sentryStatus = grpcStatus + default: + sentryStatus = sentry.SpanStatusUnknown + } +default: + sentryStatus = sentry.SpanStatusUnknown +} +return sentryStatus +``` + From 85881b711486ecfe38c749d2e277b7e1c3834e7e Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Mon, 19 Sep 2022 11:44:10 +0200 Subject: [PATCH 05/13] clean up naming --- .../sdk/performance/opentelemetry/index.mdx | 2 - .../opentelemetry/span-protocol.mdx | 63 +++++++++++-------- 2 files changed, 36 insertions(+), 29 deletions(-) diff --git a/src/docs/sdk/performance/opentelemetry/index.mdx b/src/docs/sdk/performance/opentelemetry/index.mdx index 1146cfc49d..6dcd3036cb 100644 --- a/src/docs/sdk/performance/opentelemetry/index.mdx +++ b/src/docs/sdk/performance/opentelemetry/index.mdx @@ -26,8 +26,6 @@ TODO: Talk about the approach we are using, based on Matt's hackweek project - h TODO: Talk about generating transactions -## Span Protocol - import "./span-protocol.mdx" - TODO: Talk about generating stuff (breadcrumbs/error events) from Span Events: https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/48ee3288c030ed32374125190a8abf7ced1a4238/exporter/sentryexporter/sentry_exporter.go#L167-L202 diff --git a/src/docs/sdk/performance/opentelemetry/span-protocol.mdx b/src/docs/sdk/performance/opentelemetry/span-protocol.mdx index 4b089e6c4d..8c81f4f010 100644 --- a/src/docs/sdk/performance/opentelemetry/span-protocol.mdx +++ b/src/docs/sdk/performance/opentelemetry/span-protocol.mdx @@ -1,3 +1,5 @@ +## Span Protocol + Below describe the transformations between an OpenTelemetry span and a Sentry Span. Related: [the interface for a Sentry Span](https://develop.sentry.dev/sdk/event-payloads/span/), [the Relay spec for a Sentry Span](https://github.com/getsentry/relay/blob/master/relay-general/src/protocol/span.rs) and the spec for an [OpenTelemetry span](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L80-L256). This is based on a mapping done as part of work on the [OpenTelemetry Sentry Exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/exporter/sentryexporter/docs/transformation.md). @@ -17,7 +19,7 @@ This is based on a mapping done as part of work on the [OpenTelemetry Sentry Exp title="OpenTelemetry Span trace_id Protobuf definitions" href="https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L81-L89" > - Span.trace_id + trace_id @@ -25,7 +27,7 @@ This is based on a mapping done as part of work on the [OpenTelemetry Sentry Exp title="Sentry Span trace_id Relay definitions" href="https://github.com/getsentry/relay/blob/7fb4ef6546cbe27c2b6e101dc46fd36cbe273d57/relay-general/src/protocol/span.rs#L37" > - Span.trace_id + trace_id @@ -36,7 +38,7 @@ This is based on a mapping done as part of work on the [OpenTelemetry Sentry Exp title="OpenTelemetry Span span_id Protobuf definitions" href="https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L91-L99" > - Span.span_id + span_id @@ -44,7 +46,7 @@ This is based on a mapping done as part of work on the [OpenTelemetry Sentry Exp title="Sentry Span span_id Relay definitions" href="https://github.com/getsentry/relay/blob/7fb4ef6546cbe27c2b6e101dc46fd36cbe273d57/relay-general/src/protocol/span.rs#L30" > - Span.span_id + span_id @@ -55,7 +57,7 @@ This is based on a mapping done as part of work on the [OpenTelemetry Sentry Exp title="OpenTelemetry Span parent_span_id Protobuf definitions" href="https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L106-L108" > - Span.parent_span_id + parent_span_id @@ -63,7 +65,7 @@ This is based on a mapping done as part of work on the [OpenTelemetry Sentry Exp title="Sentry Span parent_span_id Relay definitions" href="https://github.com/getsentry/relay/blob/7fb4ef6546cbe27c2b6e101dc46fd36cbe273d57/relay-general/src/protocol/span.rs#L33" > - Span.parent_span_id + parent_span_id @@ -85,19 +87,21 @@ This is based on a mapping done as part of work on the [OpenTelemetry Sentry Exp title="OpenTelemetry Span name Protobuf definitions" href="https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L110-L121" > - Span.name + name + , - Span.attributes + attributes + , - Span.kind + kind @@ -105,7 +109,7 @@ This is based on a mapping done as part of work on the [OpenTelemetry Sentry Exp title="Sentry Span description Relay definitions" href="https://github.com/getsentry/relay/blob/7fb4ef6546cbe27c2b6e101dc46fd36cbe273d57/relay-general/src/protocol/span.rs#L22" > - Span.description + description @@ -115,14 +119,14 @@ This is based on a mapping done as part of work on the [OpenTelemetry Sentry Exp title="OpenTelemetry Span name Protobuf definitions" href="https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L110-L121" > - Span.name + name maps to a Sentry - Span.description + description @@ -132,19 +136,21 @@ This is based on a mapping done as part of work on the [OpenTelemetry Sentry Exp title="OpenTelemetry Span name Protobuf definitions" href="https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L110-L121" > - Span.name + name + , - Span.attributes + attributes + , - Span.kind + kind @@ -152,7 +158,7 @@ This is based on a mapping done as part of work on the [OpenTelemetry Sentry Exp title="Sentry Span op Relay definitions" href="https://github.com/getsentry/relay/blob/d7c5698888a2148799697d5427b37bfbe3b895bc/relay-general/src/protocol/span.rs#L26" > - Span.op + op @@ -163,19 +169,21 @@ This is based on a mapping done as part of work on the [OpenTelemetry Sentry Exp title="OpenTelemetry Span attributes Protobuf definitions" href="https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L174-L186" > - Span.attributes + attributes + , - Span.kind + kind + , - Span.Status + status @@ -183,7 +191,7 @@ This is based on a mapping done as part of work on the [OpenTelemetry Sentry Exp title="Sentry Span tags Relay definitions" href="https://github.com/getsentry/relay/blob/d7c5698888a2148799697d5427b37bfbe3b895bc/relay-general/src/protocol/span.rs#L44" > - Span.tags + tags @@ -196,13 +204,14 @@ This is based on a mapping done as part of work on the [OpenTelemetry Sentry Exp title="OpenTelemetry Span attributes Protobuf definitions" href="https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L174-L186" > - Span.attributes + attributes + , - Span.Status + status @@ -210,7 +219,7 @@ This is based on a mapping done as part of work on the [OpenTelemetry Sentry Exp title="Sentry Span status Relay definitions" href="https://github.com/getsentry/relay/blob/d7c5698888a2148799697d5427b37bfbe3b895bc/relay-general/src/protocol/span.rs#L40" > - Span.status + status @@ -223,7 +232,7 @@ This is based on a mapping done as part of work on the [OpenTelemetry Sentry Exp title="OpenTelemetry Span start_time_unix_nano Protobuf definitions" href="https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L158-L164" > - Span.start_time_unix_nano + start_time_unix_nano @@ -231,7 +240,7 @@ This is based on a mapping done as part of work on the [OpenTelemetry Sentry Exp title="Sentry Span start_timestamp Relay definitions" href="https://github.com/getsentry/relay/blob/d7c5698888a2148799697d5427b37bfbe3b895bc/relay-general/src/protocol/span.rs#L14" > - Span.start_timestamp + start_timestamp @@ -242,7 +251,7 @@ This is based on a mapping done as part of work on the [OpenTelemetry Sentry Exp title="OpenTelemetry Span end_time_unix_nano Protobuf definitions" href="https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L166-L172" > - Span.end_time_unix_nano + end_time_unix_nano @@ -250,7 +259,7 @@ This is based on a mapping done as part of work on the [OpenTelemetry Sentry Exp title="Sentry Span timestamp Relay definitions" href="https://github.com/getsentry/relay/blob/d7c5698888a2148799697d5427b37bfbe3b895bc/relay-general/src/protocol/span.rs#L10" > - Span.timestamp + timestamp From 0894725c49d6c7e3e78a1a7ce5aa28ce99bc7b7b Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Mon, 19 Sep 2022 12:06:01 +0200 Subject: [PATCH 06/13] add docs around span events --- .../sdk/performance/opentelemetry/index.mdx | 4 +++ .../opentelemetry/span-protocol.mdx | 26 +++++++++++++++++++ 2 files changed, 30 insertions(+) diff --git a/src/docs/sdk/performance/opentelemetry/index.mdx b/src/docs/sdk/performance/opentelemetry/index.mdx index 6dcd3036cb..575cf54b25 100644 --- a/src/docs/sdk/performance/opentelemetry/index.mdx +++ b/src/docs/sdk/performance/opentelemetry/index.mdx @@ -22,6 +22,10 @@ TODO: Add history about OpenTelemetry Sentry Exporter: https://github.com/open-t TODO: Talk about the approach we are using, based on Matt's hackweek project - https://github.com/getsentry/sentry-ruby/pull/1876 +## OpenTelemetry Context + +TODO: Do we add OpenTelemetry Event Context? + ## Transaction Protocol TODO: Talk about generating transactions diff --git a/src/docs/sdk/performance/opentelemetry/span-protocol.mdx b/src/docs/sdk/performance/opentelemetry/span-protocol.mdx index 8c81f4f010..5ca515402a 100644 --- a/src/docs/sdk/performance/opentelemetry/span-protocol.mdx +++ b/src/docs/sdk/performance/opentelemetry/span-protocol.mdx @@ -264,6 +264,21 @@ This is based on a mapping done as part of work on the [OpenTelemetry Sentry Exp + + + + event + + + + + + See Span Events for more details + + @@ -344,3 +359,14 @@ default: return sentryStatus ``` +### Span Events + +OpenTelemetry, has the concept of [Span Events](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L193-L214). As per the spec: + +> An event is a human-readable message on a span that represents “something happening” during it’s lifetime + +In Sentry, we have two options for how to treat span events. First, we can add them as breadcrumbs to the transaction the span belongs to. Second, we can create an artificial "point-in-time" span (a span with 0 duration), and add it to the span tree. TODO on what approach we take here. + +In the special case that the span event is an exception span, [where the `name` of the span event is `exception`](https://opentelemetry.io/docs/reference/specification/trace/semantic_conventions/exceptions/), we also have the possibility of generating a Sentry error from an exception. In this case, we can create this [exception based on the attributes of an event](https://opentelemetry.io/docs/reference/specification/trace/semantic_conventions/exceptions/#attributes), which include the error message and stacktrace. This exception can also inherit all other attributes of the span event + span as tags on the event. + +In the OpenTelemetry Sentry exporter, we've used this [strategy to generate Sentry errors](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/8eda2f80b6dbd5aea03ca699c3ad1454714156d0/exporter/sentryexporter/sentry_exporter.go#L169-L196). From 5343eed46039f6237a40ade8bf09b6ca45d9254b Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Mon, 19 Sep 2022 12:06:34 +0200 Subject: [PATCH 07/13] remove todos around span protocol --- src/docs/sdk/performance/opentelemetry/index.mdx | 8 -------- 1 file changed, 8 deletions(-) diff --git a/src/docs/sdk/performance/opentelemetry/index.mdx b/src/docs/sdk/performance/opentelemetry/index.mdx index 575cf54b25..181929344c 100644 --- a/src/docs/sdk/performance/opentelemetry/index.mdx +++ b/src/docs/sdk/performance/opentelemetry/index.mdx @@ -32,14 +32,6 @@ TODO: Talk about generating transactions import "./span-protocol.mdx" -- TODO: Talk about generating stuff (breadcrumbs/error events) from Span Events: https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/48ee3288c030ed32374125190a8abf7ced1a4238/exporter/sentryexporter/sentry_exporter.go#L167-L202 - -### Semantic Conventions - -Using the [Span.Name](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L110-L121), [Span.Attributes](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L174-L186), and [Span.Kind](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L153-L156) of OpenTelemetry Spans, we can generate ops, descriptions, and tags. This exact mapping is described below. - -TODO: Talk about what we do here: https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/48ee3288c030ed32374125190a8abf7ced1a4238/exporter/sentryexporter/sentry_exporter.go#L226-L267 - ## SDK Spec - SpanProcessor: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#span-processor From 67ee7cd41836de54fee8ec639f84b8ff18b66702 Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Mon, 19 Sep 2022 13:41:42 +0200 Subject: [PATCH 08/13] add otel context spec --- .../sdk/performance/opentelemetry/index.mdx | 48 +++++++++++++++++-- 1 file changed, 44 insertions(+), 4 deletions(-) diff --git a/src/docs/sdk/performance/opentelemetry/index.mdx b/src/docs/sdk/performance/opentelemetry/index.mdx index 181929344c..d393bedfbb 100644 --- a/src/docs/sdk/performance/opentelemetry/index.mdx +++ b/src/docs/sdk/performance/opentelemetry/index.mdx @@ -22,16 +22,56 @@ TODO: Add history about OpenTelemetry Sentry Exporter: https://github.com/open-t TODO: Talk about the approach we are using, based on Matt's hackweek project - https://github.com/getsentry/sentry-ruby/pull/1876 -## OpenTelemetry Context - -TODO: Do we add OpenTelemetry Event Context? - ## Transaction Protocol TODO: Talk about generating transactions import "./span-protocol.mdx" +## OpenTelemetry Context + +Aside from information from Spans and Transactions, OpenTelemetry has meta-level information about the SDK, resource, and service that generated spans. To track this information, we generate a new OpenTelemetry Event Context. + +The existence of this context on an event (transaction or error) is how the Sentry backend will know that the incoming event is an OpenTelemetry event. + +It uses the following schema: + +```ts +interface OpenTelemetryContext { + type?: "opentelemetry", + + // https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/semantic_conventions/README.md#service + service?: { + // from: service.name + name: string; + // from: service.namespace + namespace?: string; + // from: service.instance.id + instance_id?: string; + // from: service.version + version?: string; + }; + + // https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/semantic_conventions/README.md#telemetry-sdk + sdk?: { + // from: telemetry.sdk.name + name?: string; + // from: telemetry.sdk.language + language?: SDKLanguage; + // from: telemetry.sdk.version + version?: string; + // from: telemetry.auto.version + auto_version?: string; + }; + + // Rest of attribute keys excluding service and sdk keys + // https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/resource/v1/resource.proto#L32 + [key: string]?: string, +} +``` + +The reason sdk and service are split are so they can be indexed as top level fields in the future for easier usage within Sentry. + ## SDK Spec - SpanProcessor: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#span-processor From b44fa21ea085a8de2a0bdbbe4d8bfc54d71ff98f Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Mon, 19 Sep 2022 14:02:23 +0200 Subject: [PATCH 09/13] add transaction protocol notes --- src/docs/sdk/performance/opentelemetry/index.mdx | 8 +++++--- src/docs/sdk/performance/opentelemetry/span-protocol.mdx | 4 ++-- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/src/docs/sdk/performance/opentelemetry/index.mdx b/src/docs/sdk/performance/opentelemetry/index.mdx index d393bedfbb..b21bb390cf 100644 --- a/src/docs/sdk/performance/opentelemetry/index.mdx +++ b/src/docs/sdk/performance/opentelemetry/index.mdx @@ -22,12 +22,14 @@ TODO: Add history about OpenTelemetry Sentry Exporter: https://github.com/open-t TODO: Talk about the approach we are using, based on Matt's hackweek project - https://github.com/getsentry/sentry-ruby/pull/1876 -## Transaction Protocol - -TODO: Talk about generating transactions +## Span Protocol import "./span-protocol.mdx" +## Transaction Protocol + +There is no concept of a transaction within OpenTelemetry, so we rely on promoting spans to become transactions. The span `description` becomes the transaction `name`, and the span `op` becomes the transaction `op`. Therefore, OpenTelemetry spans must be mapped to Sentry spans before they can be promoted to become a transaction. + ## OpenTelemetry Context Aside from information from Spans and Transactions, OpenTelemetry has meta-level information about the SDK, resource, and service that generated spans. To track this information, we generate a new OpenTelemetry Event Context. diff --git a/src/docs/sdk/performance/opentelemetry/span-protocol.mdx b/src/docs/sdk/performance/opentelemetry/span-protocol.mdx index 5ca515402a..dd61fbcc87 100644 --- a/src/docs/sdk/performance/opentelemetry/span-protocol.mdx +++ b/src/docs/sdk/performance/opentelemetry/span-protocol.mdx @@ -1,5 +1,3 @@ -## Span Protocol - Below describe the transformations between an OpenTelemetry span and a Sentry Span. Related: [the interface for a Sentry Span](https://develop.sentry.dev/sdk/event-payloads/span/), [the Relay spec for a Sentry Span](https://github.com/getsentry/relay/blob/master/relay-general/src/protocol/span.rs) and the spec for an [OpenTelemetry span](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L80-L256). This is based on a mapping done as part of work on the [OpenTelemetry Sentry Exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/exporter/sentryexporter/docs/transformation.md). @@ -282,6 +280,8 @@ This is based on a mapping done as part of work on the [OpenTelemetry Sentry Exp +Currently there is no spec for how [Span.link in OpenTelemetry](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L220-L247) should appear in Sentry. + ### Span Status In OpenTelemetry, [Span Status is an enum of 3 values](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#set-status), while [Sentry's Span Status is an enum of 17 values](https://github.com/getsentry/relay/blob/ed3a521f773ecd4bf9a2aefd7af80080d56d0841/relay-common/src/constants.rs#L200-L286) that map to the [GRPC status codes](https://github.com/grpc/grpc/blob/master/doc/statuscodes.md). Each of the Sentry Span Status codes also map to HTTP codes. Sentry adopted it's Span Status spec from OpenTelemetry, [who used the GRPC status code spec](https://github.com/open-telemetry/opentelemetry-specification/blob/8fb6c14e4709e75a9aaa64b0dbbdf02a6067682a/specification/api-tracing.md#status), but later on changed to the current spec it uses today. From 6d75ff998ecf4f6e270fbf42d79981b4145791db Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Tue, 20 Sep 2022 10:59:15 +0200 Subject: [PATCH 10/13] simplify span descriptions --- .../opentelemetry/span-protocol.mdx | 32 +------------------ 1 file changed, 1 insertion(+), 31 deletions(-) diff --git a/src/docs/sdk/performance/opentelemetry/span-protocol.mdx b/src/docs/sdk/performance/opentelemetry/span-protocol.mdx index dd61fbcc87..91b01f5fc1 100644 --- a/src/docs/sdk/performance/opentelemetry/span-protocol.mdx +++ b/src/docs/sdk/performance/opentelemetry/span-protocol.mdx @@ -87,20 +87,6 @@ This is based on a mapping done as part of work on the [OpenTelemetry Sentry Exp > name - , - - attributes - - , - - kind - - - The span description is decided using OpenTelemetry Semantic - Conventions. Generally, the OpenTelemetry - - name - - maps to a Sentry - - description - - + From 69db3e0303746da6f3e446510522626283c29cf9 Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Mon, 17 Oct 2022 15:58:58 +0200 Subject: [PATCH 11/13] include info about attribtues, mention no tags in transactions --- .../sdk/performance/opentelemetry/index.mdx | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/src/docs/sdk/performance/opentelemetry/index.mdx b/src/docs/sdk/performance/opentelemetry/index.mdx index b21bb390cf..fb9ba2ff04 100644 --- a/src/docs/sdk/performance/opentelemetry/index.mdx +++ b/src/docs/sdk/performance/opentelemetry/index.mdx @@ -16,8 +16,6 @@ This document details Sentry's work in integrating and supporting [OpenTelemetry When Sentry performance monitoring was initially introduced, OpenTelemetry was in early stages. This lead to us adopt a slightly different model from OpenTelemetry, notably we have this concept of transactions that OpenTelemetry does not have. We've described this, and some more historical background, in our performance monitoring research document. -TODO: Add history about OpenTelemetry Sentry Exporter: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/sentryexporter - ## Approach TODO: Talk about the approach we are using, based on Matt's hackweek project - https://github.com/getsentry/sentry-ruby/pull/1876 @@ -30,6 +28,8 @@ import "./span-protocol.mdx" There is no concept of a transaction within OpenTelemetry, so we rely on promoting spans to become transactions. The span `description` becomes the transaction `name`, and the span `op` becomes the transaction `op`. Therefore, OpenTelemetry spans must be mapped to Sentry spans before they can be promoted to become a transaction. +**We should not set tags on transactions. Instead, we should populate the `attributes` field on the `otel` context, [defined below](./#opentelemetry-context)** + ## OpenTelemetry Context Aside from information from Spans and Transactions, OpenTelemetry has meta-level information about the SDK, resource, and service that generated spans. To track this information, we generate a new OpenTelemetry Event Context. @@ -39,8 +39,17 @@ The existence of this context on an event (transaction or error) is how the Sent It uses the following schema: ```ts +type Primitive = number | string | boolean | bigint; + +interface Attributes { + [key: string]: T | Array | Record; +} + interface OpenTelemetryContext { - type?: "opentelemetry", + type?: "otel", + + // https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L174-L186 + attributes?: Attributes; // https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/semantic_conventions/README.md#service service?: { @@ -55,7 +64,7 @@ interface OpenTelemetryContext { }; // https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/semantic_conventions/README.md#telemetry-sdk - sdk?: { + otel_sdk?: { // from: telemetry.sdk.name name?: string; // from: telemetry.sdk.language From 4cfca018ce6c2ff8a49f2ec3bcb6d3659ed1ab3b Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Mon, 17 Oct 2022 16:00:10 +0200 Subject: [PATCH 12/13] make the tags ultra clear --- src/docs/sdk/performance/opentelemetry/span-protocol.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/docs/sdk/performance/opentelemetry/span-protocol.mdx b/src/docs/sdk/performance/opentelemetry/span-protocol.mdx index 91b01f5fc1..9af9f5b63c 100644 --- a/src/docs/sdk/performance/opentelemetry/span-protocol.mdx +++ b/src/docs/sdk/performance/opentelemetry/span-protocol.mdx @@ -163,7 +163,7 @@ This is based on a mapping done as part of work on the [OpenTelemetry Sentry Exp - The OpenTelemetry Span Status message and span kind are set as tags on the Sentry span. + The OpenTelemetry Span Status message and span kind are set as tags on the Sentry span. Note, if you are constructing a transaction, *DO NOT ADD TO TAGS*. @@ -258,7 +258,6 @@ In OpenTelemetry, [Span Status is an enum of 3 values](https://github.com/open-t To map from OpenTelemetry Span Status to, you need to rely on both OpenTelemetry [Span Status](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L253-L255) and [Span attributes](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L174-L186). This approach was adapted from a PR by GH user [@anguisa](https://github.com/anguisa) to the [OpenTelemetry Sentry Exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/pull/13407). - ```go // OpenTelemetry span status can be Unset, Ok, Error. HTTP and Grpc codes contained in tags can make it more detailed. From cbcd399695f7098ef62469a463691eacb39d7786 Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Mon, 17 Oct 2022 17:21:42 +0200 Subject: [PATCH 13/13] fix link --- src/docs/sdk/performance/opentelemetry/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docs/sdk/performance/opentelemetry/index.mdx b/src/docs/sdk/performance/opentelemetry/index.mdx index fb9ba2ff04..78394ea2a2 100644 --- a/src/docs/sdk/performance/opentelemetry/index.mdx +++ b/src/docs/sdk/performance/opentelemetry/index.mdx @@ -28,7 +28,7 @@ import "./span-protocol.mdx" There is no concept of a transaction within OpenTelemetry, so we rely on promoting spans to become transactions. The span `description` becomes the transaction `name`, and the span `op` becomes the transaction `op`. Therefore, OpenTelemetry spans must be mapped to Sentry spans before they can be promoted to become a transaction. -**We should not set tags on transactions. Instead, we should populate the `attributes` field on the `otel` context, [defined below](./#opentelemetry-context)** +**We should not set tags on transactions. Instead, we should populate the `attributes` field on the `otel` context, see below** ## OpenTelemetry Context