Tracing

Sending Your Own Traces

Traces are created two ways:

1. Automatically — every agent, prompt, and data source run on PromptRails is traced for you.
2. From your own code — send spans to PromptRails from any application, even one that does not manage its prompts or agents on the platform. This lets you use PromptRails as a standalone LLM observability backend for LangChain, the OpenAI / Anthropic / Google GenAI SDKs, OpenTelemetry, or your own pipelines.

External spans only need an API key with the traces:write scope. They are tagged with a source attribute such as sdk or otlp, so you can separate them from PromptRails-managed runs in the trace list.

From an SDK

The Python, JavaScript, and Go SDKs each ship a tracing module that batches spans and sends them in the background.

Python

from promptrails.tracing import Tracer
 
tracer = Tracer(api_key="pr_...")
 
with tracer.span("agent-run", kind="agent") as root:
    root.set_input({"q": "weather?"})
    with tracer.span("llm-call", kind="llm") as llm:
        llm.set_model("gpt-4o").set_usage(prompt_tokens=120, completion_tokens=30)
 
tracer.flush()

JavaScript / TypeScript

import { Tracer } from '@promptrails/sdk/tracing'
 
const tracer = new Tracer({ apiKey: 'pr_...' })
 
await tracer.span('agent-run', { kind: 'agent' }, async (root) => {
  root.setInput({ q: 'weather?' })
  await tracer.span('llm-call', { kind: 'llm' }, async (llm) => {
    llm.setModel('gpt-4o').setUsage(120, 30)
  })
})
 
await tracer.flush()

Go

import "github.com/promptrails/go-sdk/tracing"
 
tracer := tracing.NewTracer("pr_...")
defer tracer.Shutdown()
 
_ = tracer.Span(ctx, "agent-run", tracing.KindAgent, func(ctx context.Context, root *tracing.Span) error {
    root.SetInput(map[string]any{"q": "weather?"})
    return tracer.Span(ctx, "llm-call", tracing.KindLLM, func(ctx context.Context, llm *tracing.Span) error {
        // SetUsage(promptTokens, completionTokens, totalTokens); -1 = auto-compute total
        llm.SetModel("gpt-4o").SetUsage(120, 30, -1)
        return nil
    })
})

Nested spans automatically share a trace and link to their parent, so the tree renders correctly in the trace viewer.

Framework auto-instrumentation

The Python and JavaScript SDKs include integrations that turn framework calls into spans with no manual instrumentation:

• LangChain — a callback handler that traces chains, LLMs, tools, and retrievers.
• OpenAI — wrap an OpenAI-compatible client to auto-trace every chat completion (model, tokens, latency, output).
• Anthropic — wrap an Anthropic client to auto-trace every messages.create call.
• Google GenAI — wrap a Google GenAI client to auto-trace every generateContent call.

See the Python SDK and JavaScript SDK pages for setup.

OpenTelemetry (OTLP)

If you already instrument with OpenTelemetry, point an OTLP/HTTP exporter at the PromptRails OTLP endpoint — no custom code required. GenAI semantic-convention attributes (gen_ai.*) are mapped onto the span model.

POST <base-url>/api/v1/otel/v1/traces
Header: X-API-Key: pr_...               # key with the traces:write scope
Content-Type: application/x-protobuf    (or application/json)

Configure an OpenTelemetry exporter with the endpoint <base-url>/api/v1/otel and an X-API-Key header; the standard exporter appends /v1/traces.

Native ingest endpoint

SDKs post to a simple batch endpoint you can also call directly:

POST <base-url>/api/v1/traces/ingest
Header: X-API-Key: pr_...               # key with the traces:write scope

{
  "spans": [
    {
      "trace_id": "a1b2c3...",
      "span_id": "1111...",
      "parent_span_id": "0000...",
      "name": "llm-call",
      "kind": "llm",
      "model_name": "gpt-4o",
      "prompt_tokens": 120,
      "completion_tokens": 30,
      "started_at": "2026-06-01T10:00:00Z",
      "ended_at": "2026-06-01T10:00:01Z"
    }
  ]
}

Set parent_span_id to a parent span's span_id to nest spans; omit it (or leave it empty) for a root span. The workspace is taken from the API key. Up to 1000 spans per request.

Span Kinds

PromptRails currently defines these span kinds:

Span Hierarchy

Spans are organized in a tree structure using trace IDs, span IDs, and parent span IDs:

• trace_id -- Groups all spans belonging to the same execution
• span_id -- Uniquely identifies a single span
• parent_span_id -- Links a span to its parent (empty for root spans)

Example Trace for a Simple Agent

[agent] Customer Support Bot (15ms total)
  [guardrail] prompt_injection input scan (2ms)
  [prompt] Render main prompt (1ms)
  [llm] gpt-4o call (10ms, 450 prompt + 120 completion tokens, $0.003)
  [guardrail] pii output scan (2ms)

Example Trace for a Chain Agent

[chain] Data Analysis Pipeline (45ms total)
  [agent_step] Step 1: Data Extraction
    [datasource] Query analytics DB (8ms)
    [prompt] Render extraction prompt (1ms)
    [llm] gpt-4o call (15ms)
  [agent_step] Step 2: Analysis
    [memory] Retrieve analysis templates (2ms)
    [prompt] Render analysis prompt (1ms)
    [llm] claude-3.5-sonnet call (18ms)

Span Status and Levels

Status

Level

Span Attributes

Each span carries an attributes JSON object with kind-specific metadata:

LLM Span Attributes

{
  "model": "gpt-4o",
  "provider": "openai",
  "temperature": 0.7,
  "max_tokens": 1024,
  "prompt_tokens": 450,
  "completion_tokens": 120,
  "total_tokens": 570,
  "cost": 0.003
}

Guardrail Span Attributes

{
  "scanner_type": "prompt_injection",
  "direction": "input",
  "action": "block",
  "triggered": false
}

Tool Span Attributes

{
  "tool_name": "weather_api",
  "tool_type": "api",
  "parameters": { "location": "New York" }
}

Media Span Attributes (Speech / Image / Video)

{
  "provider": "fal",
  "model": "fal-ai/flux/schnell",
  "media_type": "image_gen",
  "prompt": "A futuristic city skyline at sunset",
  "asset_url": "https://storage.example.com/assets/image.png",
  "content_type": "image/png"
}

traces = client.traces.list(
    agent_id="your-agent-id",          # Filter by agent
    execution_id="execution-id",        # Filter by execution
    kind="llm",                         # Filter by span kind
    status="ok",                        # Filter by status
    model_name="gpt-4o",               # Filter by model
    session_id="session-id",            # Filter by session
    user_id="user-id",                  # Filter by user
    page=1,
    limit=50
)

JavaScript SDK

const traces = await client.traces.list({
  agentId: 'your-agent-id',
  kind: 'llm',
  status: 'ok',
  page: 1,
  limit: 50,
})

Trace Fields