wardex-sdk 0.1.0b4

Open-source observability SDK for AI agents — zero-instrumentation capture, OpenTelemetry-native

wardex-sdk

Open-source observability SDK for AI agents — zero-instrumentation capture, OpenTelemetry-native.

⚠️ Beta. PII masking is on by default (see below), but the SDK is still early: review the caveats below before sending sensitive data through it.

Install

pip install wardex-sdk

Quickstart

import wardex_sdk as wardex
from wardex_sdk import OtlpHttpTransport

wardex.init(
    transport=OtlpHttpTransport(endpoint="https://<your-collector>/v1/traces"),
    intercept=True,  # zero-instrumentation capture of LLM calls
)

# your app code — OpenAI/Anthropic calls are captured automatically

wardex.close()   # optional — spans auto-flush every 5s, on buffer threshold, and at exit

Status

Works today

• Zero-instrumentation capture of LLM HTTP calls (OpenAI, Anthropic) over https, cleartext http, and h2c
• gen_ai semantics: model, tokens, parameters, finish reasons, input/output messages
• Transport metrics (TCP/TLS timing, TTFT), gRPC (grpclib), WebSocket (wss), MCP stdio
• Export to any OpenTelemetry backend via OtlpHttpTransport
• Manual span decorators: @workflow / @agent / @task / @tool / @span
• PII masking on by default: emails, phone numbers, credit cards (Luhn-verified), US SSNs, IP addresses, bank routing numbers, IBANs, and API-key/token secrets are masked before anything leaves the process (pii_mode=PIIMode.OFF to disable, pii_disabled_categories={PIICategory.IP_ADDRESS} for per-category opt-out)
• Background batching: automatic flush every 5s / on buffer threshold / at exit and on SIGINT/SIGTERM (chained; opt out with flush_on_signals=False)

Not yet (see Roadmap)

• Framework adapters (LangGraph, Anthropic/OpenAI Agent SDKs)
• Distributed context propagation (W3C traceparent)
• Node/TS and Java SDKs

Notes

• After os.fork() the worker respawns lazily in the child on first capture; spans buffered before the fork may be sent by both processes (duplicates are possible; a fork landing mid-export can also strand the child's pre-fork buffer — re-init in the child for a clean slate). Under uWSGI enable threads (--enable-threads).

Roadmap

1. PII masking (pre-send safety) — shipped
2. Batching & lifecycle (background worker, at-exit/periodic flush, concurrency) — shipped
3. Framework adapters
4. Distributed propagation (W3C)
5. Node/TS and Java SDKs

PII masking caveats: before_send sees pre-masking data (masking runs inside the encoder), the Console transport prints raw (local debugging only), and non-UTF-8 binary payloads pass through unmasked.

License

Apache-2.0. See LICENSE and NOTICE.

"Wardex" is a trademark of Wardex Labs.