observra

Framework-agnostic agent behavior analytics.

Capture every meaningful agent action (token usage, tool calls, cost, errors) with structured context based on the Common Information Model (CIM).

Zero custom instrumentation per-agent. Answer "what happened, how much did it cost, and was it normal?" for any agent on any framework.

Install

pip install observra

With framework extras:

pip install observra[adk]           # Google ADK
pip install observra[claude]        # Claude Agent SDK
pip install observra[openai-agents] # OpenAI Agents SDK
pip install observra[langchain]     # LangChain / LangGraph
pip install observra[pydantic-ai]   # Pydantic AI

With backend extras:

pip install observra[otel]          # OTel span + log export

Install everything:

pip install observra[all]

Quick Start

Attach observra to your agent framework — no manual logging calls. For Google ADK:

import observra
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService

observra.initialize(backend="jsonl", path="telemetry.jsonl")  # pip install observra[adk]
plugin = observra.create_plugin("adk")

runner = Runner(
    agent=root_agent,  # your existing ADK agent, unchanged
    app_name="my-agent",
    session_service=InMemorySessionService(),
    plugins=[plugin],  # the only change — telemetry is now automatic
)

Every LLM call, tool use, and cost lands in telemetry.jsonl, one event per line (representative model_response; real records also carry event_id, trace_id, and host context):

{"timestamp": 1718115781.882, "event_type": "model_response", "framework": "adk", "agent_name": "research-agent", "model_name": "gemini-2.0-flash", "session_id": "s-a1f6c2e3", "library_version": "1.0.3", "data": {"input_tokens": 1240, "output_tokens": 387, "cost_usd": 0.0019, "action": "call_llm", "result": "success"}}

Other frameworks follow the same two-step pattern — see the getting-started guides for Claude, OpenAI, LangChain, and Pydantic AI.

Supported Frameworks

Backends

OTel Export (Dynatrace, Grafana, etc.)

from observra.backends.otel import OTelExportBackend
from observra.backends.otel_log import OTelLogBackend
from observra.backends.multi import MultiBackend

# Spans only
span_backend = OTelExportBackend(
    endpoint="https://your-collector/v1/traces",
    headers={"Authorization": "Api-Token ..."},
    service_name="my-agent-svc",
)

# Logs only
log_backend = OTelLogBackend(
    endpoint="https://your-collector/v1/logs",
    headers={"Authorization": "Api-Token ..."},
    service_name="my-agent-svc",
)

# Both spans and logs
backend = MultiBackend([span_backend, log_backend])

Key Features

• Cost tracking — per-session cost with model-specific pricing catalog and threshold alerts
• PII redaction — automatic secret/PII masking with configurable patterns
• Non-blocking — drop-oldest queue guarantees zero latency impact on the host agent
• CIM-normalized — structured events compatible with SIEM/analytics pipelines
• Safe regex — ReDoS-proof pattern matching via RE2 (optional: [safe-regex])
• Encryption at rest — AES field-level encryption for sensitive telemetry (optional: [encryption])
• Prompt injection detection — built-in heuristics for injection attempt classification
• Observability — get_metrics() / get_stats() for pipeline health introspection
• Deduplication — automatic event dedup across backends
• Session context — trace/span/session ID propagation with scoped contexts

All Extras

Documentation

• Getting Started — per-framework setup guides
• Event Schema — CIM event contract
• Architecture — system design overview
• Compatibility — supported versions
• Stability Contract — API + event/CIM-schema stability guarantees
• API Reference — auto-generated reference for the public Python SDK

Project sponsor

observra is sponsored by Exabeam. Exabeam contributed the initial code and continues to provide ongoing support and contributions to the project as part of its commitment to security in an increasingly agentic world.

License

Apache 2.0 — see LICENSE