Tracing API

The tracing API sets up observability, tags your LLM calls, and attaches file artifacts when needed.

init()

Configures OpenTelemetry and installs auto-instrumentation for all detected LLM libraries. Call once at application startup, before any LLM calls.

import promptic_sdk

promptic_sdk.init(
    api_key=None,           # str | None — defaults to PROMPTIC_API_KEY env var
    endpoint=None,          # str | None — defaults to https://promptic.eu
    auto_instrument=True,   # bool — auto-detect and instrument LLM libraries
    service_name=None,      # str | None — sets the OpenTelemetry service name
)

Parameters

Raises

• ValueError — if no API key is found via argument, env var, or config file.

What it does

1. Creates an OpenTelemetry TracerProvider with a BatchSpanProcessor
2. Configures OTLP/HTTP export to the Promptic platform
3. If auto_instrument=True, detects and instruments each of: OpenAI, Anthropic, Google Generative AI, Vertex AI, Bedrock, Mistral, Cohere, LangChain (+ LangGraph, create_agent, deepagents), OpenAI Agents SDK, Claude Agent SDK. All emit official OpenTelemetry GenAI semantic conventions (gen_ai.*).
4. Packages that are not installed are silently skipped; packages that are installed but fail to initialize are logged at WARNING level.
5. Rewrites large inline media/base64 payloads into promptic-artifact://... references before export so trace payloads stay small.

ai_component()

Context manager that tags all LLM spans within its scope with an AI Component name. Optionally tags with a dataset and run for evaluation.

with promptic_sdk.ai_component(
    name,                   # str — component name (e.g., "email-classifier")
    *,
    dataset=None,           # str | None — dataset name for evaluation grouping
    run=None,               # str | None — run name within the dataset
):
    ...

Parameters

Example

# Basic — just tag with component
with promptic_sdk.ai_component("my-classifier"):
    response = client.chat.completions.create(...)

# With dataset and run — for evaluation
with promptic_sdk.ai_component("my-agent", dataset="regression", run="v2"):
    for query in queries:
        agent.run(query)

How it works

Sets contextvars.ContextVar values that are read by an OpenTelemetry SpanProcessor. Every span created within the context automatically gets promptic.ai_component, promptic.dataset, and promptic.run attributes.

dataset()

Context manager that tags spans with a dataset name. Can be used inside an ai_component block for more granular control.

with promptic_sdk.dataset(
    name,                   # str — dataset name
):
    ...

Parameters

Example

with promptic_sdk.ai_component("support-agent"):
    # Normal traffic — no dataset
    agent.run(user_query)

    # Tagged for evaluation
    with promptic_sdk.dataset("nightly-eval"):
        for query in test_queries:
            agent.run(query)

artifact()

Uploads a local file, bytes, or text string and returns a trace-safe artifact reference. Use this for local files or custom payloads that are not already captured inline by auto-instrumentation. When direct object-storage upload is available, the SDK should upload bytes to the private storage backend first and send Promptic only artifact metadata plus the final reference.

ref = promptic_sdk.artifact(
    "/tmp/report.pdf",
    mime_type=None,        # optional, guessed for local files
    api_key=None,          # optional, defaults to configured/env key
    endpoint=None,         # optional, defaults to configured/env endpoint
)

span.set_attribute("retrieval.input_file", ref.uri)

Parameters

Return value

artifact() returns an ArtifactReference with id, uri, mime_type, size_bytes, and sha256 fields. Store ref.uri in span attributes when you want the trace UI and API to link back to the uploaded artifact.

Local file safety

The SDK does not silently read paths that happen to appear in span attributes. Local file upload is explicit so applications do not accidentally trace private files.