Temporal (tracing)

Temporal is a durable execution platform for long-running applications. Respan instruments the Temporal Python SDK through Temporal’s official replay-aware OpenTelemetry interceptor, preserving Temporal context propagation and replay behavior while emitting canonical Respan workflow and task spans.

Setup

$
pip install respan-ai respan-instrumentation-temporal temporalio

$
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"

1
import asyncio
2
from datetime import timedelta
3
4
from respan import Respan
5
from respan_instrumentation_temporal import TemporalInstrumentor
6
from temporalio import activity, workflow
7
from temporalio.client import Client
8
from temporalio.worker import Worker
9
10
11
@activity.defn
12
async def compose_greeting(name: str) -> str:
13
    return f"Hello, {name}!"
14
15
16
@workflow.defn
17
class GreetingWorkflow:
18
    @workflow.run
19
    async def run(self, name: str) -> str:
20
        return await workflow.execute_activity(
21
            compose_greeting,
22
            name,
23
            start_to_close_timeout=timedelta(seconds=10),
24
        )
25
26
27
async def main() -> None:
28
    instrumentor = TemporalInstrumentor()
29
    respan = Respan(instrumentations=[instrumentor])
30
31
    try:
32
        # The Respan interceptor is injected automatically here.
33
        client = await Client.connect("localhost:7233")
34
35
        async with Worker(
36
            client,
37
            task_queue="greeting-task-queue",
38
            workflows=[GreetingWorkflow],
39
            activities=[compose_greeting],
40
        ):
41
            result = await client.execute_workflow(
42
                GreetingWorkflow.run,
43
                "Ada",
44
                id="greeting-workflow-1",
45
                task_queue="greeting-task-queue",
46
            )
47
            print(result)
48
    finally:
49
        respan.shutdown()
50
51
52
asyncio.run(main())

How automatic injection works

Passing TemporalInstrumentor() to Respan activates a patch on temporalio.client.Client.connect. Every client connected after initialization receives instrumentor.interceptor; workers created with that client use the same interceptor and preserve trace context across Temporal boundaries.

1
from respan import Respan
2
from respan_instrumentation_temporal import TemporalInstrumentor
3
from temporalio.client import Client
4
5
instrumentor = TemporalInstrumentor()
6
respan = Respan(instrumentations=[instrumentor])
7
8
client = await Client.connect("localhost:7233")

If the interceptors argument already contains a Temporal TracingInterceptor, Respan does not append a second tracing interceptor. This prevents duplicate spans.

Initialize Respan before the first Client.connect() call. Clients created before activation are not retrofitted.

Explicit interceptor wiring

Temporal test environments and custom client factories expose an explicit interceptors list. Use the same interceptor instance through instrumentor.interceptor:

1
from respan import Respan
2
from respan_instrumentation_temporal import TemporalInstrumentor
3
from temporalio.testing import WorkflowEnvironment
4
5
instrumentor = TemporalInstrumentor()
6
respan = Respan(instrumentations=[instrumentor])
7
8
environment = await WorkflowEnvironment.start_time_skipping(
9
    interceptors=[instrumentor.interceptor]
10
)
11
12
try:
13
    client = environment.client
14
    # Create a Worker with this client, then start or execute workflows.
15
finally:
16
    await environment.shutdown()
17
    respan.shutdown()

The Temporal example suite uses this wiring with Temporal’s official time-skipping test server, so it does not require an external Temporal cluster. The first run downloads the official test-server binary.

Captured operations

The instrumentor adapts the operations emitted by Temporal’s official Python tracing interceptor.

Operation names include the workflow, activity, signal, query, or update type when Temporal exposes it. Workflow lifecycle operations are classified as Respan workflow spans; the other Temporal operations are classified as task spans.

Workflow-side spans follow Temporal’s replay safeguards. By default, the official interceptor creates them only when an overarching client span is present. See always_create_workflow_spans below if workflows are started from schedules, the CLI, or another source without that parent context.

Configuration

TemporalInstrumentor options

Respan options

Content controls

Content capture is enabled by default. It can include operation arguments and fields such as workflow or activity type, workflow ID, update ID, and task queue when Temporal exposes those values to the interceptor. Temporal headers and RPC metadata are never captured.

Disable content capture when arguments or identifiers can contain sensitive data:

1
from respan import Respan
2
from respan_instrumentation_temporal import TemporalInstrumentor
3
4
respan = Respan(
5
    instrumentations=[TemporalInstrumentor(capture_content=False)]
6
)

With content capture disabled, spans retain the stable operation and workflow/activity type needed to inspect the trace, but omit arguments and Temporal IDs. Error details are reduced to the exception class rather than the exception message.

Errors and lifecycle

Successful Temporal operations receive backend-visible success status. Failed operations receive OpenTelemetry error status together with status_code and error.message, and their canonical output records an error result. When capture_content=False, the error message contains only the exception class.

activate() and deactivate() are idempotent and safe across multiple instrumentor instances. The Client.connect() patch remains active until the last active Temporal instrumentor is deactivated. Existing clients retain the interceptor they received at connection time.

When Respan owns the instrumentor lifecycle, call respan.shutdown() during application shutdown to flush pending telemetry and deactivate instrumentation:

1
instrumentor = TemporalInstrumentor()
2
respan = Respan(instrumentations=[instrumentor])
3
4
try:
5
    client = await Client.connect("localhost:7233")
6
    # Run workers and workflows.
7
finally:
8
    respan.shutdown()

More examples

• Workflow and remote activity
• Signals and queries
• Child workflow, local activity, content disabled, and expected failure
• Workflow update and signal completion