Workflow observability

This guide covers how worker telemetry (logs, traces, and metrics) is exported, and how to use OpenTelemetry traces for execution-level diagnostics.

By default, the worker exports OpenTelemetry logs, traces, and metrics to Mistral's hosted observability platform. No setup is required: telemetry is authenticated with your Mistral API key and sent to Mistral's telemetry endpoint. This is what makes your workflow logs and traces visible directly in Studio, on the execution page.

You can also send telemetry to your own observability stack or turn it off. See Configuring telemetry export at the end of this page.

Traces capture execution details (spans, timings, errors) and are optimized for debugging and performance analysis. They are independent from custom task events.

Execution logs are also available in Studio. Open Studio›Workflows›Executions ↗ and select an execution to inspect its logs on the execution page.

Activities automatically generate spans. Use the name parameter to make them more readable:

@workflows.activity(name="Processing customer emails")
async def process_emails(params: ActivityParams) -> ActivityResult:
    # Your activity code

@workflows.activity(name="Processing customer emails")
async def process_emails(params: ActivityParams) -> ActivityResult:
    # Your activity code

By default, all traces are exported (the worker samples at a 100% rate). To control sampling, pass a traceparent header at your workflow entry point (or API edge): the worker uses a parent-based sampler, so it honors the upstream sampling decision. This lets you force sampling on or off and propagate the parent trace consistently.

Three methods are available to retrieve trace data for a given execution:

• get_workflow_execution_trace_otel(): Returns the raw OpenTelemetry trace data (spans with timings, attributes, and parent-child relationships). Use this to feed traces into your own observability backend (Jaeger, Grafana Tempo, etc.).
• get_workflow_execution_trace_summary(): Returns a high-level summary of the execution (total duration, activity count, error count). Useful for dashboards and quick status checks.
• get_workflow_execution_trace_events(): Returns a chronological list of events in the execution. Set include_internal_events=False to filter out platform-internal events and see only your workflow and activity events.

from mistralai.client import Mistral

client = Mistral(api_key="your_api_key")

# Get raw OpenTelemetry trace data (spans, timings, attributes)
trace = client.workflows.executions.get_workflow_execution_trace_otel(
    execution_id=execution_id,
)

# Get high-level summary (duration, activity count, errors)
summary = client.workflows.executions.get_workflow_execution_trace_summary(
    execution_id=execution_id,
)

# Get chronological event list
events = client.workflows.executions.get_workflow_execution_trace_events(
    execution_id=execution_id,
    include_internal_events=False,  # Hide system events
)

from mistralai.client import Mistral

client = Mistral(api_key="your_api_key")

# Get raw OpenTelemetry trace data (spans, timings, attributes)
trace = client.workflows.executions.get_workflow_execution_trace_otel(
    execution_id=execution_id,
)

# Get high-level summary (duration, activity count, errors)
summary = client.workflows.executions.get_workflow_execution_trace_summary(
    execution_id=execution_id,
)

# Get chronological event list
events = client.workflows.executions.get_workflow_execution_trace_events(
    execution_id=execution_id,
    include_internal_events=False,  # Hide system events
)

Execution logs (the same ones shown in Studio) can also be retrieved programmatically:

• get_workflow_execution_logs(): Returns a page of log records for an execution. Filter with run_id, activity_id, and a time range (after, before), choose the first-page sort with order (asc or desc), and paginate with cursor and limit.
• stream_workflow_execution_logs(): Streams log records live over Server-Sent Events (SSE).

# Get the first page of execution logs (oldest first)
logs = client.workflows.executions.get_workflow_execution_logs(
    execution_id=execution_id,
    order="asc",
    limit=50,
)

# Fetch the next page using the returned cursor
if logs.next_cursor:
    next_page = client.workflows.executions.get_workflow_execution_logs(
        execution_id=execution_id,
        cursor=logs.next_cursor,
    )

# Get the first page of execution logs (oldest first)
logs = client.workflows.executions.get_workflow_execution_logs(
    execution_id=execution_id,
    order="asc",
    limit=50,
)

# Fetch the next page using the returned cursor
if logs.next_cursor:
    next_page = client.workflows.executions.get_workflow_execution_logs(
        execution_id=execution_id,
        cursor=logs.next_cursor,
    )

By default, every signal is exported to Mistral (see the Telemetry setup section above). You can override individual signals to your own OTLP endpoint, route everything to one endpoint, or disable export entirely.

To send worker telemetry to your own observability stack, point one or more signals at your own OTLP endpoint. Each signal is routed independently:

Provide the base OTLP HTTP endpoint (for example https://otel.example.com). The worker appends the standard signal path (/v1/traces, /v1/metrics, or /v1/logs) automatically.

Signals you don't override keep flowing to Mistral, so they stay visible in Studio. When you set a custom endpoint, the worker no longer attaches your Mistral API key for that signal, so you authenticate it yourself.

To authenticate a custom endpoint, use the signal-specific OTLP header variable (OTEL_EXPORTER_OTLP_TRACES_HEADERS, OTEL_EXPORTER_OTLP_METRICS_HEADERS, or OTEL_EXPORTER_OTLP_LOGS_HEADERS). For example, to send only metrics to your own stack while keeping logs and traces in Studio:

OTEL_METRICS_ENDPOINT=https://otel.example.com
OTEL_EXPORTER_OTLP_METRICS_HEADERS=Authorization=Bearer <your-token>

OTEL_METRICS_ENDPOINT=https://otel.example.com
OTEL_EXPORTER_OTLP_METRICS_HEADERS=Authorization=Bearer <your-token>

To route all signals to a single endpoint, set OTEL_ENDPOINT. This sends traces, metrics, and logs to that one endpoint and attaches no Mistral authentication. Use the per-signal variables above when you need different destinations or want to keep some signals in Studio.

You can disable export entirely or per signal: