Low-Level Client API

For advanced use cases, you can work directly with the Python or TypeScript Client class. This gives you full control over initialization, trace submission, scoring, and lifecycle management.

We do not recommend using the low-level client API for normal tracing. You must manually construct traces and spans that match the standard PandaProbe schema, and the API endpoints expect that schema. Use wrappers, integrations, or decorators unless you have an advanced use case that needs direct client control.

Python client API

Programmatic initialization

Python

import pandaprobe

client = pandaprobe.init(
    api_key="your-api-key",
    project_name="your-project-name",
    endpoint="https://api.pandaprobe.com",
    environment="production",
    release="v1.2.3",
    enabled=True,
    batch_size=10,
    flush_interval=5.0,
    max_queue_size=1000,
    debug=False,
)

pandaprobe.init() parameters:

Parameter	Type	Default	Description
`api_key`	`str \| None`	From env	PandaProbe API key
`project_name`	`str \| None`	From env	Project name
`endpoint`	`str \| None`	`https://api.pandaprobe.com`	Backend URL
`environment`	`str \| None`	From env	Environment tag (e.g., `"production"`)
`release`	`str \| None`	From env	Release/version tag
`enabled`	`bool \| None`	`True`	Enable/disable SDK
`batch_size`	`int \| None`	`10`	Traces per flush batch
`flush_interval`	`float \| None`	`5.0`	Seconds between automatic flushes
`max_queue_size`	`int \| None`	`1000`	Max queued items before dropping
`debug`	`bool \| None`	`False`	Enable verbose debug logging

Returns the configured Client instance and sets it as the global singleton.

If init() is called when a client already exists, the existing client is shut down and replaced.

Creating traces via `Client`

client.trace() has the same signature as pandaprobe.start_trace().

Module API
Client instance

Python

import pandaprobe

with pandaprobe.start_trace("my-agent", input={"messages": [...]}) as t:
    with t.span("llm-call", kind="LLM") as s:
        ...

Python

client = pandaprobe.get_client()

with client.trace("my-agent", input={"messages": [...]}) as t:
    with t.span("llm-call", kind="LLM") as s:
        ...

Use get_client() after init() when you inject dependencies in tests or pass the client through your application layer.

Submitting pre-built traces

Python

from pandaprobe.schemas import TraceData, SpanData, SpanKind
from datetime import datetime, timezone

trace = TraceData(
    name="my-trace",
    input={"messages": [{"role": "user", "content": "Hello"}]},
    output={"messages": [{"role": "assistant", "content": "Hi!"}]},
    started_at=datetime.now(timezone.utc),
    ended_at=datetime.now(timezone.utc),
    session_id="session-1",
    spans=[
        SpanData(
            name="llm-call",
            kind=SpanKind.LLM,
            model="gpt-5.4",
            started_at=datetime.now(timezone.utc),
            ended_at=datetime.now(timezone.utc),
        ),
    ],
)

client.log_trace(trace)

When to use log_trace

Use pre-built TraceData when traces are assembled offline, replayed from logs, or produced by frameworks that already materialize a full trace object.

Scoring

Python

client.score(
    trace_id="your-trace-id",
    name="accuracy",
    value="0.95",
    data_type="NUMERIC",
    reason="Matched expected output",
)

Lifecycle management

client.flush(timeout=30.0)  # Block until all queued items are sent
client.shutdown()            # Flush remaining items and release resources

import pandaprobe

pandaprobe.flush()
# Process exit or explicit shutdown in your framework hook

Always call flush() before shutdown() in short-lived scripts. For long-running services, the SDK flushes automatically via a background thread and atexit handler.

Error handling

Python

def on_error(exc: Exception):
    print(f"PandaProbe error: {exc}")

client.on_error(on_error)

Properties

client.enabled — bool, whether the SDK is active
client.config — SdkConfig, the resolved configuration (frozen dataclass)

Auto-initialization

The global client auto-initializes from environment variables on first use. You only need to call pandaprobe.init() if you want to configure the SDK programmatically or override environment variables.

Python

# These all trigger auto-init if needed:
pandaprobe.start_trace(...)
pandaprobe.flush()
pandaprobe.score(...)

pandaprobe.get_client() returns None if auto-init fails (e.g., missing API key). pandaprobe.start_trace() raises RuntimeError if no client is available.

TypeScript client API

Programmatic initialization

TypeScript

import { init } from "pandaprobe";

const client = init({
  apiKey: "your-api-key",
  projectName: "your-project-name",
  endpoint: "https://api.pandaprobe.com",
  environment: "production",
  release: "v1.2.3",
  enabled: true,
  batchSize: 10,
  flushInterval: 5,
  maxQueueSize: 1000,
  debug: false,
});

The TypeScript client uses camelCase option names. init() sets and returns the global singleton. getClient() returns that client or attempts one-time initialization from environment variables.

Creating traces with a client

TypeScript

import { SpanKind, getClient } from "pandaprobe";

const client = getClient();
if (!client) throw new Error("PandaProbe is not configured");

await client.trace("my-agent", {
  input: { messages: [{ role: "user", content: "Hello" }] },
}).run(async (trace) => {
  await trace.span("llm-call", { kind: SpanKind.LLM }).run(async (span) => {
    span.setModel("gpt-4o-mini");
    span.setOutput({ messages: [{ role: "assistant", content: "Hi!" }] });
  });
  trace.setOutput({ messages: [{ role: "assistant", content: "Hi!" }] });
});

For application code, prefer withTrace() and withSpan(); they provide the same callback lifecycle with less client plumbing.

Submitting pre-built traces

TypeScript

import { SpanData, SpanKind, TraceData } from "pandaprobe";

const now = new Date();
const trace = new TraceData({
  name: "my-trace",
  input: { messages: [{ role: "user", content: "Hello" }] },
  output: { messages: [{ role: "assistant", content: "Hi!" }] },
  startedAt: now,
  endedAt: new Date(),
  sessionId: "session-1",
  spans: [
    new SpanData({
      name: "llm-call",
      kind: SpanKind.LLM,
      model: "gpt-4o-mini",
      startedAt: now,
      endedAt: new Date(),
    }),
  ],
});

client.logTrace(trace);

Scoring and lifecycle

TypeScript

import { ScoreDataType } from "pandaprobe";

client.score("your-trace-id", "accuracy", "0.95", {
  dataType: ScoreDataType.NUMERIC,
  reason: "Matched expected output",
});

client.onError((error) => console.error("PandaProbe transport error", error));
await client.flush(30);
await client.shutdown();

The enabled and config properties expose the resolved client state. TypeScript configuration is frozen after initialization; call init() again to replace the global client.

Get Started

Tracing

Low-Level Client API

Python client API

Programmatic initialization

Creating traces via `Client`

Submitting pre-built traces

Scoring

Lifecycle management

Error handling

Properties

Auto-initialization

TypeScript client API

Programmatic initialization

Creating traces with a client

Submitting pre-built traces

Scoring and lifecycle

​Python client API

​Programmatic initialization

​Creating traces via Client

​Submitting pre-built traces

​Scoring

​Lifecycle management

​Error handling

​Properties

​Auto-initialization

​TypeScript client API

​Programmatic initialization

​Creating traces with a client

​Submitting pre-built traces

​Scoring and lifecycle

Python client API

Programmatic initialization

Creating traces via `Client`

Submitting pre-built traces

Scoring

Lifecycle management

Error handling

Properties

Auto-initialization

TypeScript client API

Programmatic initialization

Creating traces with a client

Submitting pre-built traces

Scoring and lifecycle