From 08ff98b34374f6dca728083eb3beae1865cc66bf Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Thu, 27 Nov 2025 14:53:40 +0100 Subject: [PATCH 1/3] feat: Add Python examples to Spans v2 API page --- develop-docs/sdk/telemetry/spans/span-api.mdx | 48 +++++++++++++++++-- 1 file changed, 44 insertions(+), 4 deletions(-) diff --git a/develop-docs/sdk/telemetry/spans/span-api.mdx b/develop-docs/sdk/telemetry/spans/span-api.mdx index 06e446ddfb4cd..ca774a25a924f 100644 --- a/develop-docs/sdk/telemetry/spans/span-api.mdx +++ b/develop-docs/sdk/telemetry/spans/span-api.mdx @@ -28,7 +28,7 @@ SDKs MUST NOT expose names like "segment span" (e.g. in APIs) to users and SHOUL SDKs' span implementations MUST at minimum implement the following span interface. -```ts +```ts {tabTitle:TypeScript} interface Span { private _spanId: string; @@ -49,6 +49,17 @@ interface Span { } ``` +```Python {tabTitle:Python} +class Span: + span_id: str + + def set_attribute(self, key: str, value: SpanAttributeValue) -> None: ... + def set_status(self, status: Literal["ok", "error"]) -> None: ... + def get_name(self) -> str: ... + def set_name(self) -> None: ... + def get_attributes(self) -> SpanAttributes: ... +``` + When implementing the span interface, consider the following guidelines: - SDKs MAY implement additional APIs, such as getters/setters for properties (e.g. `span.getStatus()`), or additional methods for convenience (e.g. `Span::spanContext()`). @@ -63,7 +74,7 @@ SDKs MUST expose at least one API to start a span. SDKs MAY expose additional AP SDKs MUST expose a default `startSpan` API that takes options and returns a span: -```ts +```ts {tabTitle:TypeScript} function startSpan(options: StartSpanOptions): Span; interface StartSpanOptions { @@ -74,6 +85,16 @@ interface StartSpanOptions { } ``` +```Python {tabTitle:Python} +with start_span( + name, # type: str + attributes, # type: SpanAttributes + parent_span, # type: Span + active, # type: bool +) as span: + ... +``` + SDKs MUST allow specifying the following options to be passed to `startSpan`: | Option | Required | Description | @@ -113,7 +134,7 @@ SDKs MAY expose additional utility APIs for users, or internal usage to access c ## Example -```ts +```ts {tabTitle:TypeScript} const checkoutSpan = Sentry.startSpan({ name: 'on-checkout-click', attributes: { 'user.id': '123' } }) @@ -140,4 +161,23 @@ unrelatedSpan.end(); on('checkout-finished', ({ timestamp }) => { checkoutSpan.end(timestamp); }) -``` \ No newline at end of file +``` + +```Python {tabTitle:Python} + +with sentry_sdk.start_span(name="checkout", attributes={"user.id": "123"}) as checkout_span: + with sentry_sdk.start_span(name="process-order") as process_order_span: + result = process() + process_order_span.set_attribute("order-status", result.message) + + with sentry_sdk.start_span(name="process-payment") as process_payment_span: + try: + result = process_payment() + process_payment_span.set_attribute("order-status", result.message) + except: + process_payment_span.set_status("error") + process_payment_span.set_attribute("order-status", "error") + + with sentry_sdk.start_span(name="log-order", parent_span=None) as unrelated_span: + log_order() +``` From 8c34b5c636ef2258938dac888145ada902c48341 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Thu, 27 Nov 2025 15:04:43 +0100 Subject: [PATCH 2/3] Update span-api.mdx --- develop-docs/sdk/telemetry/spans/span-api.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/telemetry/spans/span-api.mdx b/develop-docs/sdk/telemetry/spans/span-api.mdx index ca774a25a924f..f66c8f83bbdf7 100644 --- a/develop-docs/sdk/telemetry/spans/span-api.mdx +++ b/develop-docs/sdk/telemetry/spans/span-api.mdx @@ -56,7 +56,7 @@ class Span: def set_attribute(self, key: str, value: SpanAttributeValue) -> None: ... def set_status(self, status: Literal["ok", "error"]) -> None: ... def get_name(self) -> str: ... - def set_name(self) -> None: ... + def set_name(self, name: str) -> None: ... def get_attributes(self) -> SpanAttributes: ... ``` From 33bad4176f9179243010bc7d5c3dbde24a7c1a35 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Tue, 2 Dec 2025 12:50:36 +0100 Subject: [PATCH 3/3] Add non context manager API --- develop-docs/sdk/telemetry/spans/span-api.mdx | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/develop-docs/sdk/telemetry/spans/span-api.mdx b/develop-docs/sdk/telemetry/spans/span-api.mdx index f66c8f83bbdf7..d8d76a387dc14 100644 --- a/develop-docs/sdk/telemetry/spans/span-api.mdx +++ b/develop-docs/sdk/telemetry/spans/span-api.mdx @@ -86,6 +86,9 @@ interface StartSpanOptions { ``` ```Python {tabTitle:Python} +# The context-manager way of starting a span. The span will be finished +# automatically when exiting the context manager. + with start_span( name, # type: str attributes, # type: SpanAttributes @@ -93,6 +96,12 @@ with start_span( active, # type: bool ) as span: ... + +# Alternative API without the use of a context manager, to allow for more +# flexibility when to end the span: + +span = start_span(name, attributes, parent_span, active) +span.end() ``` SDKs MUST allow specifying the following options to be passed to `startSpan`: @@ -178,6 +187,7 @@ with sentry_sdk.start_span(name="checkout", attributes={"user.id": "123"}) as ch process_payment_span.set_status("error") process_payment_span.set_attribute("order-status", "error") - with sentry_sdk.start_span(name="log-order", parent_span=None) as unrelated_span: - log_order() + span = sentry_sdk.start_span(name="log-order", parent_span=None) + log_order() + span.end() ```