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.

Python

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
)

The API key determines the owning AI Application. service_name is emitted as the standard OpenTelemetry service.name resource attribute and appears as a telemetry-derived service filter in Tracing. Set the deployment environment separately with:

Terminal

export OTEL_RESOURCE_ATTRIBUTES="deployment.environment.name=production"

Parameters

Parameter	Type	Default	Description
`api_key`	`str \| None`	`PROMPTIC_API_KEY`	API key for authentication. Falls back to env var, then config file.
`endpoint`	`str \| None`	`https://promptic.eu`	Promptic platform URL. Falls back to `PROMPTIC_ENDPOINT` env var.
`auto_instrument`	`bool`	`True`	When `True`, automatically detects and instruments installed LLM libraries.
`service_name`	`str \| None`	`None`	Optional service name for the OpenTelemetry `TracerProvider`.

Raises

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

What it does

Creates an OpenTelemetry TracerProvider with a BatchSpanProcessor
Configures OTLP/HTTP export to the Promptic platform
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.*).
Packages that are not installed are silently skipped; packages that are installed but fail to initialize are logged at WARNING level.
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 existing AI Component name. Optionally adds those traces to an existing dataset.

Python

with promptic_sdk.ai_component(
    name,                   # str — component name (e.g., "email-classifier")
    dataset_id=None,        # str | None — UUID of an existing dataset
):
    ...

Parameters

Parameter	Type	Default	Description
`name`	`str`	required	Existing AI Component display name.
`dataset_id`	`str \| None`	`None`	UUID of an existing dataset belonging to this AI Component. Traces in scope are added to it.

Datasets are created explicitly in the dashboard, CLI, or API; tracing never creates one. A malformed dataset ID fails immediately, before any spans are created; a well-formed but unknown ID is rejected later, during trace ingestion.

Example

Python

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

# Add the traces to an existing dataset
with promptic_sdk.ai_component(
    "my-classifier",
    dataset_id="550e8400-e29b-41d4-a716-446655440000",
):
    response = client.chat.completions.create(...)

How it works

Every LLM span created within the context is automatically tagged with the AI Component, and with the dataset when a dataset_id is provided, so the platform links those traces to the right AI Component and dataset.

`dataset()`

Context manager that tags spans with an existing dataset UUID. Use it inside an ai_component() block when only part of a component's traffic should be added to the dataset.

Python

with promptic_sdk.dataset(
    dataset_id,             # str — UUID of an existing dataset
):
    ...

Parameters

Parameter	Type	Default	Description
`dataset_id`	`str`	required	UUID of an existing dataset.

The dataset must already exist. A malformed UUID fails immediately, before the context is entered; a well-formed but unknown ID is rejected during trace ingestion.

Example

Python

with promptic_sdk.ai_component("my-agent"):
    # Normal traffic — not added to a dataset
    agent.run(user_query)

    # Only these traces are added to the dataset
    with promptic_sdk.dataset("550e8400-e29b-41d4-a716-446655440000"):
        for query in eval_queries:
            agent.run(query)

How it works

Every span created within the context is tagged with the dataset — including spans nested inside an ai_component() block — so the platform links those traces to it.

`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.

Python

ref = promptic_sdk.artifact(
    "/tmp/report.pdf",
    name=None,             # optional, defaults to the file's base name for local files
    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

Parameter	Type	Default	Description
`value`	`str \| bytes \| Path`	required	File path, raw bytes, or text to upload.
`name`	`str \| None`	file base name	Stored on the artifact and used as the default download filename. For local files it defaults to the file's base name; pass it explicitly for bytes or text content.
`mime_type`	`str \| None`	guessed / inferred	MIME type for rendering and download metadata.
`api_key`	`str \| None`	configured/env	API key override.
`endpoint`	`str \| None`	configured/env	Platform endpoint override.

Return value

artifact() returns an ArtifactReference with id, uri, mime_type, size_bytes, sha256, and name 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.

On this page