From 9b542e595247c163ac551c57e08a8db394af5f7c Mon Sep 17 00:00:00 2001 From: Michael Hoffmann Date: Tue, 5 Nov 2024 08:37:13 +0100 Subject: [PATCH 1/2] docs(sdks): New Span API --- develop-docs/sdk/telemetry/spans/span-api.mdx | 61 +++++++++++++++++++ .../spans/span-trace-propagation.mdx | 28 +++++++++ 2 files changed, 89 insertions(+) create mode 100644 develop-docs/sdk/telemetry/spans/span-api.mdx create mode 100644 develop-docs/sdk/telemetry/spans/span-trace-propagation.mdx diff --git a/develop-docs/sdk/telemetry/spans/span-api.mdx b/develop-docs/sdk/telemetry/spans/span-api.mdx new file mode 100644 index 0000000000000..9eac1d6823ec1 --- /dev/null +++ b/develop-docs/sdk/telemetry/spans/span-api.mdx @@ -0,0 +1,61 @@ +--- +title: Span API +--- + + + This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels. + + +Spans are measuring the duration of certain operations in an application. +The topmost member of a span tree is called the root span. This span has no parent span and groups together its children with a representative name for the entire operation, such as `GET /` in case of a request to a backend application. + +## Creating a root span + +The SDK must expose a method for creating a root span. The user must be able to set certain properties on this root span, such as its name, the type of operation (`op`) and others. + +```js +span = sentry.tracing.startSpan() + ->setName('GET /') + ->setOp('http.server') + +span.end() +``` + +## Creating nested spans + +To create nested spans, the SDK must expose an explicit way for a user to perform this task. + +Additionally, the SDK may expose alternative APIs to create nested spans, such as allowing a user to wrap an operation into a callback or apply a decorator to certain blocks. These alternative APIs must never create a root span and no-op if no parent span is present. + +```js +childSpan = span.startChild() + ->setName('authentication middleware') + ->setOp('middleware.handle') + +childSpan.end() +``` + +## Setting the span status + +A span has two statuses, `ok` and `error`. By default, the status of a span is set to `ok`. +The SDK must allow a user to modify the status of a span. + +```js +span.setStatus('error') +``` + +## Setting span attributes + +The SDK must expose a method to allow a user to set data attributes onto a span. +These attributes should use pre-defined keys whenever possible. + +```js +span.setAttribute(SpanAttributes.HTTP_METHOD, 'GET') +span.setAttribute(SpanAttributes.HTTP_RESPONSE_STATUS_CODE, 200) +``` + +## Additional, optional span APIs + +`span.setStartTimestamp()` - overwrite the span's start time + +`span.setEndTimestamp()` - overwrites the span's end time diff --git a/develop-docs/sdk/telemetry/spans/span-trace-propagation.mdx b/develop-docs/sdk/telemetry/spans/span-trace-propagation.mdx new file mode 100644 index 0000000000000..9b944c2b633f1 --- /dev/null +++ b/develop-docs/sdk/telemetry/spans/span-trace-propagation.mdx @@ -0,0 +1,28 @@ +--- +title: Span Trace Propagation +--- + + + This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels. + + +## Continue an incoming trace + +To continue a trace from an upstream service, the SDK must expose a method to extract the traceparent and baggage information and apply these to the applicable scope. + +```js +scope.setPropagationContext({ + traceparent: request.headers.SENTRY_TRACE, + baggage: request.headers.SENTRY_BAGGAGE, +}) +``` +Newly created root spans should now contain these properties, such as `trace_id` and `parent_span_id`. + +## Continue an outgoing trace + +To propagate a trace to a downstream service, the SDK must expose methods to fetch the required information to allow the next service to continue the trace. + +```js +traceparent = scope.getTraceparent() +baggage = scope.getBaggage() +``` From 485758ae665fb2758cad03270a6902efe1856597 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Wed, 29 Oct 2025 17:46:00 +0100 Subject: [PATCH 2/2] update specification with new span API design --- develop-docs/sdk/telemetry/spans/span-api.mdx | 150 ++++++++++++++---- 1 file changed, 116 insertions(+), 34 deletions(-) diff --git a/develop-docs/sdk/telemetry/spans/span-api.mdx b/develop-docs/sdk/telemetry/spans/span-api.mdx index 9eac1d6823ec1..4993fcaae1a4b 100644 --- a/develop-docs/sdk/telemetry/spans/span-api.mdx +++ b/develop-docs/sdk/telemetry/spans/span-api.mdx @@ -3,59 +3,141 @@ title: Span API --- - This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels. + This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels. + + + + The APIs specified in this documents MUST be implemented by all SDKs that don't use OpenTelemetry as their underlying tracing implementation. + SDKs using OTel SHOULD follow their own already established span APIs but MAY orient themselves on this document if applicable. Spans are measuring the duration of certain operations in an application. -The topmost member of a span tree is called the root span. This span has no parent span and groups together its children with a representative name for the entire operation, such as `GET /` in case of a request to a backend application. -## Creating a root span +The topmost member of a (distributed) span tree is called the "Root Span". +This span has no parent span and groups together its children with a representative name for the entire operation, such as `GET /` in case of a request to a backend application. -The SDK must expose a method for creating a root span. The user must be able to set certain properties on this root span, such as its name, the type of operation (`op`) and others. +The topmost span within a service boundary is called the "Segment Span". +Segment spans have a `parent_span_id` pointing to a "remote" span from the parent service. -```js -span = sentry.tracing.startSpan() - ->setName('GET /') - ->setOp('http.server') +For example, a distributed trace from backend to frontend, would have a segment span for the backend, and a segment span for the frotnend. +The frontend segment span is also the root span of the entire span tree. -span.end() -``` +SDKs MUST NOT expose names like "segment span" (e.g. in APIs) to users and SHOULD NOT (read "avoid") exposing "root span" if possible. -## Creating nested spans +## Span Interface -To create nested spans, the SDK must expose an explicit way for a user to perform this task. +SDKs' span implementations MUST at minimum implement the following span interface. -Additionally, the SDK may expose alternative APIs to create nested spans, such as allowing a user to wrap an operation into a callback or apply a decorator to certain blocks. These alternative APIs must never create a root span and no-op if no parent span is present. - -```js -childSpan = span.startChild() - ->setName('authentication middleware') - ->setOp('middleware.handle') +```ts +interface Span { + private _spanId: string; -childSpan.end() -``` + end(endTimestamp?: SpanTimeInput): void; + + setAttribute(key: string, value: SpanAttributeValue | undefined): this; + setAttributes(attributes: SpanAttributes): this; -## Setting the span status + setStatus(status: 'ok' | 'error'): this; -A span has two statuses, `ok` and `error`. By default, the status of a span is set to `ok`. -The SDK must allow a user to modify the status of a span. + setName(name: string): this; -```js -span.setStatus('error') + addLink(link: SpanLink): this; + addLinks(links: SpanLink[]): this; + + getName(): string; + getAttributes(): Record +} ``` -## Setting span attributes +When implementing the span interface, consider the following guidelines: -The SDK must expose a method to allow a user to set data attributes onto a span. -These attributes should use pre-defined keys whenever possible. +- SDKs MAY implement additional APIs, such as getters/setters for properties (e.g. `span.getStatus()`), or additional methods for convenience (e.g. `Span::spanContext()`). +- SDK implementers SHOULD dissalow direct mutation (without setters) of span properties such as the span name, depending on the plaform and the challenges involved. +- SDK implementers MAY disallow direct read access to span properties, depending on the platform and the challenges involved. -```js -span.setAttribute(SpanAttributes.HTTP_METHOD, 'GET') -span.setAttribute(SpanAttributes.HTTP_RESPONSE_STATUS_CODE, 200) +## Span Starting APIs + +SDKs MUST expose at least one API to start a span. SDKs MAY expose additional APIs, depending on the platform, language conventions and requirements. + +### Default `startSpan` API + +SDKs MUST expose a default `startSpan` API that takes options and returns a span: + +```ts +function startSpan(options: StartSpanOptions): Span; + +interface StartSpanOptions { + name: string; + attributes?: Record; + parentSpan?: Span | null; + active?: boolean; +} ``` -## Additional, optional span APIs +SDKs MUST allow specifying the following options to be passed to `startSpan`: + +| Option | Required | Description | +|---------------|----------|----------------------------------------------| +| `name` | Yes | The name of the span. MUST be set by users | +| `attributes` | No | Attributes to attach to the span. | +| `parentSpan` | No | The parent span. See description below for implications of allowed values | +| `active` | No | Whether the started span should be _active_ (i.e. if spans started while this span is active should become children of the started span). | + +Behaviour: +- Spans MUST be started as active by default. This means that any span started, while the initial span is active, MUST be attached as a child span of the active span. +- Only if users set `active: false`, the span will be started as inactive, meaning spans started while this span is not yet ended, will not become children, but siblings of the started span. +- If a `Span` is passed via `parentSpan`, the span will be started as the child of the passed parent span. This has precedence over the currently active span. +- If `null` is passed via `parentSpan`, the new span will be started as a root/segment span. +- SDKs MUST NOT end the span automatically. This is the responsibility of the user. +- `startSpan` MUST always return a span instance, even if the started span's trace is negatively sampled. + + +### Additional Span Starting APIs + +SDKs MAY expose additional span starting APIs or variants of `startSpan` that make sense for the platform. +These could be decorators, annotations, or closure- or callback-based APIs. +Additional APIs MAY e.g. end spans automatically (for example, when a callback terminates, the span is ended automatically). +Likewise, additional APIs MAY also adjust the span status based on errors thrown. + +### Explicitly creating a child span + +At this time, SDKs MUST NOT expose APIs like `Span::startChild` or similar functionality that explicitly creates a child span. +This is still TBD but the `parentSpan` option should suffice to serve this use case. + +## Utility APIs + +SDKs MAY expose additional utility APIs for users, or internal usage to access certain spans. For example, + +- `Scope::getSpan()` - returns the currently active span. +- `Scope::_INTERNAL_getSegmentSpan()` - returns the segment span of the currently active span (MUST NOT be documented for users) + +## Example + +```ts + +const checkoutSpan = Sentry.startSpan({ name: 'on-checkout-click', attributes: { 'user.id': '123' } }) + +const validationSpan = Sentry.startSpan({ name: 'validate-shopping-cart'}) +startFormValidation().then((result) => { + validationSpan.setAttribute('valid-form-data', result.success); + processSpan.end(); +}) + +const processSpan = Sentry.startSpan({ name: 'process-order', parentSpan: checkoutSpan}); +processOrder().then((result) => { + processSpan.setAttribute('order-processed', result.success); + processSpan.end(); +}).catch((error) => { + processSpan.setStatus('error'); + processSpan.setAttribute('error', error.message); + processSpan.end(); +}); -`span.setStartTimestamp()` - overwrite the span's start time +const unrelatedSpan = Sentry.startSpan({ name: 'log-order', parentSpan: null}); +logOrder() +unrelatedSpan.end(); -`span.setEndTimestamp()` - overwrites the span's end time +on('checkout-finished', ({ timestamp }) => { + checkoutSpan.end(timestamp); +}) +``` \ No newline at end of file