Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.pandaprobe.com/llms.txt

Use this file to discover all available pages before exploring further.

For advanced use cases, you can work directly with the 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.

​
Programmatic initialization

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:
ParameterTypeDefaultDescription
api_keystr | NoneFrom envPandaProbe API key
project_namestr | NoneFrom envProject name
endpointstr | Nonehttps://api.pandaprobe.comBackend URL
environmentstr | NoneFrom envEnvironment tag (e.g., "production")
releasestr | NoneFrom envRelease/version tag
enabledbool | NoneTrueEnable/disable SDK
batch_sizeint | None10Traces per flush batch
flush_intervalfloat | None5.0Seconds between automatic flushes
max_queue_sizeint | None1000Max queued items before dropping
debugbool | NoneFalseEnable 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(). 
import pandaprobe

with pandaprobe.start_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

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)
Use pre-built TraceData when traces are assembled offline, replayed from logs, or produced by frameworks that already materialize a full trace object.

​
Scoring

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

Register callbacks to be notified of transport errors: 
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. 
# 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.