This release is a pre-release and may not be stable for production use.
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. Versioning and stability promises are in VERSIONING.md.
Install
pip install wardex-sdk
Quickstart
import wardex_sdk as wardex
from wardex_sdk import BackendConfig
wardex.init(backend=BackendConfig(endpoint="https://<collector>/v1/traces", api_key="..."))
# your app code — LLM calls, tools and agent runs are captured automatically
wardex.close() # optional — spans auto-flush every 5s, on buffer threshold, and at exit
Interception is on by default: init() is the consent, and
zero-instrumentation capture of LLM traffic is the product (intercept=False
is the opt-out). api_key is sent as an Authorization: Bearer <key> header
by the default exporter. With WARDEX_ENDPOINT set in the environment, a bare
wardex.init() is a working first run — see
Environment variables.
Works with openai-agents
Install wardex next to the OpenAI Agents SDK, set one environment variable,
and every Runner.run / run_sync / run_streamed becomes one trace with
the agents, the tool calls and the handoffs in it — no decorator, no
callback, no processor to register. The framework's own tracing hooks give
wardex the structure; the LLM calls underneath are read from the wire, so
model, messages and token usage are the ones that actually crossed the
socket, and the tool call_id the framework echoes into the next turn joins
each execute_tool span to the chat span that requested it.
From a checkout of this repository (the example script is not in the
wheel), on Python 3.10 or newer, with a Phoenix started as in
examples/README.md:
git clone https://github.com/wardex-labs/wardex-sdk && cd wardex-sdk
python3 -m venv .venv-quickstart && source .venv-quickstart/bin/activate
pip install "wardex-sdk>=0.6.0b1" openai-agents # prebuilt wheel, nothing to compile
export OPENAI_API_KEY=sk-... # the framework's own requirement
export WARDEX_ENDPOINT=http://127.0.0.1:6006/v1/traces # a local Phoenix
python examples/openai_agents_quickstart.py
The adapter ships in 0.6.0b1. If pip cannot find that version, your
checkout is ahead of the last PyPI release: pip install ./sdks/python openai-agents builds it from the checkout instead (needs cargo, and the
build reports the checkout's own, lower, version number — expected). The
script makes six short gpt-4o-mini calls against
your key. Measured from a fresh clone and virtualenv following the
walkthrough, Phoenix image already pulled: under a minute in the terminal,
18 seconds of it the from-checkout build. That is the measured part; the
clicks in Phoenix to the tree below add an estimated half-minute on top,
paced by hand rather than clocked.
The receiving agent of a handoff is the sender's sibling, not its
child, so a long handoff chain stays one level deep; wardex.agent.parent
and a handoff_from link record who handed off to whom. Phoenix draws that
indentation only once its trace drawer is widened — the walkthrough in
examples/README.md says where to click and what to
drag, covers Langfuse, and explains the framework's own [non-fatal] Tracing client error 401 line if you see one.
Two cases where you do not get that tree, and what wardex says instead:
- Responses over WebSocket (
use_responses_websocket=True). The LLM calls are inside WebSocket frames wardex does not parse, so thechatspans are replaced by oneWS /v1/responsesspan per connection carrying the markerws_llm_semantics_unread— no model, tokens or messages. The agent, tool and handoff spans are unaffected. Use the framework's default HTTP transport forchatspans. - Framework tracing disabled (
OPENAI_AGENTS_DISABLE_TRACING=1oragents.set_tracing_disabled(True)). There is nothing for the adapter to hook, so you get thechatspans only, unparented, and one INFO log line (on stderr under default logging) atwardex.init():[wardex] openai-agents tracing is disabled, so wardex will show only the LLM calls its interceptor captures: no agent, handoff, tool or guardrail spans. …— followed by the two lines that re-enable the framework's tracing without sending anything to OpenAI. wardex never flips that setting for you.
Configuration
Settings are grouped by concern, and the group names are the same in every wardex SDK — a Node or Java service configured by the same team reads the same way.
| Group | What it decides |
|---|---|
backend=BackendConfig(...) |
Where the data goes and whose it is: endpoint, api_key |
pii=PIIConfig(...) |
What leaves the process: mode, disabled_categories |
batching=BatchingConfig(...) |
When buffered spans are sent: flush_interval, flush_on_signals, shutdown_timeout |
limits=LimitsConfig(...) |
How much is captured — see Resource limits |
propagation=PropagationConfig(...) |
Whether wardex touches outbound traffic: enabled, targets |
adapters=AdaptersConfig(...) |
Which framework adapters install, and each adapter's own options |
import wardex_sdk as wardex
from wardex_sdk import BackendConfig, BatchingConfig, PIIConfig, PIIMode
wardex.init(
backend=BackendConfig(endpoint="https://<collector>/v1/traces", api_key="..."),
batching=BatchingConfig(flush_interval=2.0),
pii=PIIConfig(mode=PIIMode.OFF),
)
Everything that belongs to no group stays top-level: service_name,
release, environment, debug, before_send_envelope, capture_mode, and
the interception trio intercept / intercept_hosts / interceptors. The
config dataclasses are keyword-only and frozen; each group validates its own
fields, so an invalid value fails on the line that constructed it. Collection
fields accept any iterable and read back canonicalized (tuple/frozenset);
enum-valued fields take enum members, not strings.
Adapters
Framework adapters auto-detect by default. adapters= selects and configures
them:
from wardex_sdk import AdapterName, AdaptersConfig, AnthropicAgentSdkConfig
wardex.init(
...,
adapters=AdaptersConfig(
enabled=( # None auto-detects; () installs none
AdapterName.ANTHROPIC_AGENT_SDK,
AdapterName.LANGGRAPH,
AdapterName.OPENAI_AGENTS,
),
anthropic_agent_sdk=AnthropicAgentSdkConfig(...), # per-adapter options
),
)
Selection and options are separate fields on purpose: setting an adapter's
options never touches enabled, so auto-detection of every other framework
survives. Options set for an adapter that enabled= excludes are announced
with a WardexConfigWarning.
Refused, never ignored
The flat spelling of a grouped setting (api_key=..., flush_interval=...,
the old before_send= and the adapters=(AdapterName.X,) tuple) is refused
with a TypeError naming its new home. Settings that were removed outright
(retention=, tags=, replay_buffer_size=) are refused with a message
saying why they are gone. There is no compatibility shim: a config setting
that is silently ignored is worse than one that stops the program on the line
that set it.
Environment variables
Per field, an explicit init() argument wins; an unset one falls back to its
environment variable; only then does the default apply. The contract:
| Variable | Fills |
|---|---|
WARDEX_API_KEY |
backend.api_key |
WARDEX_ENDPOINT |
backend.endpoint — else OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, else OTEL_EXPORTER_OTLP_ENDPOINT |
WARDEX_SERVICE_NAME |
service_name |
WARDEX_RELEASE |
release |
WARDEX_ENVIRONMENT |
environment |
WARDEX_DEBUG |
debug — true (case-insensitive) can only turn it ON |
A host already exporting OTLP elsewhere points wardex at the same collector
with zero new variables. The endpoint rule: a URL with no path component
(or /) gets /v1/traces appended when the default transport is built —
http://collector:4318 exports to http://collector:4318/v1/traces — while a
URL with an explicit path is used verbatim. The config always reads back
exactly as written.
With neither a transport= nor a resolved backend.endpoint, init()
installs NoOpTransport, captures into nothing, and says so once (see
Diagnostics).
Identifying your service
Three flat fields name the app in whatever OTel backend receives the data:
| Field | OTLP resource attribute |
|---|---|
service_name |
service.name (unset: unknown_service:python) |
release |
service.version (unset: not emitted) |
environment |
deployment.environment.name (unset: not emitted) |
telemetry.sdk.name is the constant "wardex" in every language — the SDK
travels in telemetry.sdk.*, never in your service's identity.
Tracing
Everything is captured without instrumentation; the tracing API exists to add structure — names, operations, and parents — around your own code.
Context managers take a positional name; decorators take an optional keyword name. That family rule is frozen across SDKs.
import wardex_sdk as wardex
from wardex_sdk import ToolAttributes
# A conversation: every span inside carries gen_ai.conversation.id.
with wardex.conversation("support-chat", id=session_id): # id=None mints a uuid4
...
# A hand-named span over a block, yielding a Span to enrich:
with wardex.span("rank-results") as s:
s.set_attribute("candidates", 42)
...
# Decorators — bare or with keywords; name defaults to the function's name:
@wardex.workflow
def nightly_sync(): ...
@wardex.agent(name="researcher")
def run_agent(): ...
@wardex.step
def plan(): ...
@wardex.tool(name="search", attributes=ToolAttributes(...))
def search(query: str): ...
conversation() is not a trace root: the span it opens joins the ambient
trace as a child, and an explicit id= is used verbatim — a multi-turn chat
app passes its own session id so every turn joins one conversation. It also
wins over a framework's own conversation id: an adapter run opened inside
the block (an OpenAI Agents RunConfig(group_id=…), say) keeps your id on
every span and carries the framework's as a separate attribute
(wardex.openai_agents.group_id), so one trace never has two conversation ids.
workflow / agent / step / tool map to the gen_ai.operation.name
values invoke_workflow / invoke_agent / execute_step / execute_tool,
so decorated spans appear on operation-keyed dashboards. span() and
conversation() are context managers only — using one as a decorator raises
a TypeError naming the decorators (a decorator would silently break async
functions).
Scope
Ambient data that rides on every span captured under it:
wardex.set_tag("tenant", "acme") # spans carry the tag
wardex.set_user(wardex.UserInfo(id="u1", email=...)) # spans carry user.*
wardex.set_user(None) # clears the user
wardex.set_context("job", {"attempt": 3}) # readable back; NOT exported
with wardex.isolation_scope(): # fork: inherits current tags/user, mutations stay inside
wardex.set_tag("tenant", "other") # this block only
...
set_tag / set_user / set_context write the isolation scope — inside
an isolation_scope() block (one request, one tenant, one job) they stay that
unit's and cannot bleed onto other threads' spans; outside any block they
behave like process-wide values in a simple script. Tags land on exported
spans (a span-local attribute with the same key wins); UserInfo maps to
user.id / user.email / user.name and client.address. Contexts are for
your own code to read back and are not stamped onto spans.
Distributed tracing
Trace context propagation is opt-in — a plain wardex.init(...) never
touches your outbound requests or headers. Turn it on with:
from wardex_sdk import PropagationConfig
wardex.init(
backend=BackendConfig(endpoint="https://<collector>/v1/traces"),
propagation=PropagationConfig(
enabled=True, # inject W3C headers on outbound calls
targets=(
"api.internal.example.com",
"*.svc.cluster.local",
), # optional glob allowlist; default None = all hosts
),
)
With propagation=PropagationConfig(enabled=True), outbound calls made through httpx (sync + async),
requests, or aiohttp get a traceparent (and tracestate, if one was
received) header attached automatically, as long as an active trace context
exists and the request doesn't already carry a traceparent. If
propagation.targets is left unset, the trace ID is sent to every host you
call — including third-party LLM providers. Set it to an allowlist of glob
patterns to scope injection to your own services; patterns are matched
case-insensitively, since hostnames are.
wardex only ever adds a header you did not write. A traceparent you set
yourself wins whether you set it per request or once as a session default, and
in that case nothing is injected at all; a tracestate you set is left exactly
as written rather than replaced or duplicated.
Joining an inbound trace
Drop the middleware in front of your app to join whatever trace the caller started:
# ASGI (FastAPI, Starlette, Django ASGI)
app.add_middleware(wardex.WardexAsgiMiddleware)
# WSGI (Flask, Django WSGI)
app.wsgi_app = wardex.WardexWsgiMiddleware(app.wsgi_app)
Both extract the incoming traceparent/tracestate and continue the trace
for the lifetime of the request; a missing or malformed header just starts a
fresh trace (never raises). One WSGI caveat: the joined context covers the
app callable only, so streaming responses (work done while iterating the
returned iterable) run outside it.
Manual propagation (the universal escape hatch)
The baton is just a string, so it travels over any channel that can carry
one — not just HTTP. get_traceparent() and get_trace_headers() are plain
functions that return the current trace headers; continue_trace(headers)
is a context manager — the remote parent is only installed inside the
with block, so it must be entered, not merely called. Use them directly
wherever the automatic client patches or ASGI/WSGI middleware don't reach:
# gRPC metadata
stub.Check(req, metadata=[("traceparent", wardex.get_traceparent())])
# WebSocket handshake
websockets.connect(uri, extra_headers=wardex.get_trace_headers())
# Celery: put get_trace_headers() on the task's headers when sending it,
# then inside the worker:
with wardex.continue_trace(task.request.headers):
... # task body
# Kafka: put get_trace_headers() on the message headers when producing,
# then inside the consumer:
with wardex.continue_trace(dict(msg.headers())):
... # process the message
Pass it a traceparent a caller actually sent you, and nothing else.
continue_trace() takes a string and takes it at its word — that is what makes
it work over any channel, and it is also its one sharp edge. Any string of the
right shape becomes a parent, so deriving one from something that is not a
propagated trace context (a framework's run_id, a request id, a hash of a job
name) manufactures a causal edge that never existed. Spans parented this way are
recorded with parent_source = header, which is how they stay distinguishable
from the in-process edges wardex derives itself; what wardex cannot tell you is
whether the header was genuine, because both are just strings. Everywhere else,
the parent comes from real context propagation and is never built from an
identifier.
with wardex.continue_from_otel(): is a one-line alternative to
continue_trace() for code that already runs under an active OpenTelemetry
span — it adopts that span as the remote parent for the duration of the
with block (no-op if opentelemetry isn't installed or there's no active
span). Like continue_trace(), it is a context manager and must be entered
with with.
Propagating into threads
asyncio tasks inherit the current trace context automatically; threads do
not. Wrap the target with wardex.bind_context() at the point where you
still have the right context:
thread = threading.Thread(target=wardex.bind_context(worker_fn), args=(...,))
thread.start()
capture_mode: what gets captured without an active span
capture_mode defaults to CaptureMode.AGENT: LLM-semantic traffic
(recognized gen_ai calls, MCP stdio) is always captured, but generic
HTTP/gRPC/WS traffic is only captured while it happens inside an active
local wardex span (a traceparent received from an upstream caller doesn't
count on its own — this keeps a service mesh stamping every request with a
traceparent from reviving "capture everything" noise).
A recognized provider's failed calls count as LLM-semantic traffic too, so
a 429 or a 401 is captured under the default mode even outside a local span —
the response status decides the span's status, never whether it exists.
This means a bare, unwrapped call to an LLM provider wardex doesn't
recognize — or a WebSocket provider whose path wardex doesn't recognize, such
as OpenAI Realtime — can be silently dropped if it isn't inside a local span.
Wrap that call with @wardex.workflow (or any of the span decorators), or set
capture_mode=wardex.CaptureMode.ALL to restore capture-everything behavior:
wardex.init(..., capture_mode=wardex.CaptureMode.ALL)
Responses over WebSocket (openai-agents use_responses_websocket=True).
This opt-in transport sends every call over one wss://…/v1/responses
connection, and it is the one WebSocket case that ships under the default
mode without a wrapper: once the first call crosses the connection it is
an LLM connection, and when the connection closes wardex counts it
(interceptors.seam.ws_llm_semantics_unread) and emits one
WS /v1/responses span marked
ws_llm_semantics_unread — LLM calls crossed it and wardex read none of
them, because Responses events inside WebSocket frames are not parsed. The
span carries ws.messages.sent (about one per call), byte counts and payload
samples (compressed bytes, marked payload_compressed, when
permessage-deflate was negotiated), no model or tokens; switch the framework
to its default HTTP transport for gen_ai spans. A connection that ends
without a WebSocket close handshake — a server drop, a timeout, process exit,
or wardex uninstalled first — still yields the span, additionally marked
ws_no_close. The connection counts as an LLM connection only when the host
is the provider's own — exactly api.openai.com or a subdomain of
openai.com; a host that merely contains the name, such as
openai-mock.corp, is not — or when the first client message carries a
Responses "type": "response.create" (anywhere in that message, whatever
the key order) on an uncompressed connection. The decision is made once,
on that first client message, for the life of the connection. A
Responses-path connection
to any other host (localhost, a gateway, a mock) with compression — the
websockets client's default — is only counted
(interceptors.seam.ws_llm_endpoint_unconfirmed) and yields no span under
the default mode. Under ALL, under an intercept_hosts entry,
or inside a local span that same connection does ship — but as an ordinary
WebSocket span, WS /v1/responses with status OK and no
ws_llm_semantics_unread marker (measured against a loopback server: one
span, markers ['payload_compressed'] only) — so the counter is the only
signal that unread LLM calls crossed it.
Plaintext hosts you've explicitly named via intercept_hosts are always
captured regardless of capture_mode — a targeted allowlist entry is a
stronger opt-in than the default policy.
One thing is never captured, in any mode and above any allowlist:
telemetry uploads. Any host, any path ending in /v1/traces/ingest — the
OpenAI Agents SDK POSTs its whole run record there by default. The rule is
by path: a custom exporter endpoint (BackendSpanExporter(endpoint=…)) that
keeps the /v1/traces/ingest path is covered; one on another path is not —
under ALL, under intercept_hosts, or inside a local span it ships as an
ordinary HTTP span with the run record as its input_data. That body is
yours on its way to a tracing backend, not agent activity, so wardex skips the
request before parsing it or attaching it to a span, and counts the skip
under interceptors.seam.path_excluded. To be precise about where that
body goes: the bytes pass through wardex's per-connection buffer like any
other request's (capped by LimitsConfig.max_body_bytes), and are then
discarded — never parsed, never on a span, never exported. If your own
service exposes that path, its requests are skipped by the same rule.
Server-side conversation state
(…/v1/conversations/…) is plain HTTP rather than an LLM call — no model,
no usage — so it follows the non-LLM rule above: captured inside a local
span, under ALL or under intercept_hosts, otherwise dropped and counted
under interceptors.seam.provider_state_dropped. With the OpenAI Agents
SDK's Runner.run(conversation_id=…) (measured on 0.22) each turn is still
a chat span, but its input is only the items the framework had not sent
yet — the second turn's input is the tool result alone — and the
conversation id that joins the turns is not yet surfaced as a span
attribute.
asyncio
wardex.flush(timeout=None) and wardex.close(timeout=None) are synchronous
and block the calling thread — a bare flush() waits as long as the
transport's own configured timeout, a bare close() follows
batching.shutdown_timeout (5s default). From async code, run them in an
executor so the event loop keeps breathing:
await asyncio.get_running_loop().run_in_executor(None, wardex.flush)
Capture itself never blocks your coroutines: spans are buffered, parsed
and exported from wardex's own worker threads. The expensive step — the
LLM-semantic parse of a completed response — runs on a dedicated
wardex-finalize-worker thread with the GIL released, so a large streamed
completion finishing does not stall the event loop; flush() finishes any
pending parses before it sends (which is also why calling it from async code
belongs in an executor, as above). asyncio tasks inherit the trace
context automatically; only hand-started threads need
wardex.bind_context() (above).
Errors
The exception contract has exactly two tiers:
- Configuration time raises.
init()and the config classes raiseTypeError/ValueErroron a bad argument, like any Python constructor — a config mistake stops the program on the line that made it. - Runtime never raises. Every capture and export path is fail-safe:
nothing wardex does after
init()returns raises into host code, and every public call (flush,close,set_tag, the tracing helpers, ...) is a safe no-op beforeinit()was ever called.
There is deliberately no WardexError base class — there is no wardex
exception a host is ever expected to catch.
Diagnostics
Everything wardex says about itself goes through the stdlib logger
wardex_sdk. Out of the box it carries one pre-attached stderr handler,
so with zero configuration you see one-line messages prefixed [wardex] —
announcements (the NoOp-transport notice, the debug=True config dump) at
INFO, losses and failures (a span dropped over the size cap, an export cut
off at shutdown) at WARNING. Some finer-grained lines — a disabled parser, a
buffer-full drop count — additionally sit behind debug=True; the gate
changes whether they fire, never their severity.
To route diagnostics into your own logging setup, replace the handler — the
[wardex] prefix lives in wardex's own handler, so yours receives clean
messages:
import logging
logger = logging.getLogger("wardex_sdk")
logger.handlers.clear()
logger.addHandler(my_handler) # or logging.NullHandler() to silence
The logger does not propagate to the root logger, so nothing double-prints
under logging.basicConfig(). A wardex_sdk logger you configure before
importing wardex is left untouched. Configuration conflicts — a setting
another setting disables — are not log lines but real warnings
(WardexConfigWarning), filterable with the warnings module.
Counters. Conditions a span cannot carry — a request wardex skipped, a
WebSocket connection it only counted — are tallied in-process:
wardex_sdk._assembly.counters.snapshot() returns {site: count}. This
section's neighbours mention interceptors.seam.path_excluded (telemetry
uploads skipped), interceptors.seam.provider_state_dropped (requests on a
Conversations-API-shaped path the mode did not capture),
interceptors.seam.ws_llm_semantics_unread (WebSocket connections that
carried LLM calls wardex did not read) and
interceptors.seam.ws_llm_endpoint_unconfirmed (Responses-path WebSocket
connections wardex could not corroborate); table-eviction counters are under
Resource limits.
Testing your instrumentation
RecordingTransport is the in-process test double: exports are recorded, not
sent, and read back as structural nodes.
import wardex_sdk as wardex
from wardex_sdk.testing import RecordingTransport
transport = RecordingTransport()
wardex.init(transport=transport)
run_the_code_under_test()
wardex.flush()
names = [node.name for node in transport.spans]
assert "execute_tool search" in names
transport.spans yields every recorded span in export order as SpanNodes
(name, span/parent/trace ids, parent-resolution confidence, limitation
markers). Note it records pre-masking, in-process data — what was
captured, not what a backend would have received.
Bring your own transport
Transport is the one advertised extension point: subclass it, implement
export(), and pass an instance as init(transport=...). An explicit
transport= carries its own address and wins over backend.endpoint (the
losing endpoint is announced with a WardexConfigWarning) — never configure
both expecting both to apply.
from wardex_sdk.transport import UNDELIVERED, Transport, Undelivered
from wardex_sdk import Envelope
class MyTransport(Transport):
def export(self, envelope: Envelope, *, timeout: float | None = None) -> Undelivered | None:
for body in self.encode(envelope): # masked, capped, split OTLP bodies
post(body) # one POST per body, in order
return None # or UNDELIVERED if nothing was sent
The contract, in brief — wardex_sdk.transport is the complete implementer
home (Transport, NoOpTransport, ConsoleTransport, OtlpHttpTransport,
Envelope, UNDELIVERED, Undelivered, CallerBudget, DEFAULT_TIMEOUT):
- Threading:
export/flush/closeare called from wardex's own worker thread, never from your event loop or request threads, and may block up to their budget. That is the cross-language contract (Node bindsexportas async and its pipeline awaits it; Java stays blocking). - The envelope is opaque. Its guaranteed surface is
span_countandTransport.encode(envelope), which returns the wire bodies — protobuf, gzipped by default, PII-masked, attribute-capped, and split atmax_otlp_request_bytes.export()itself receives pre-masking data: serialize the envelope yourself and you own PII masking. Do not overrideencode(). - Declines: return
UNDELIVEREDonly when the envelope was not put on the wire and an identical later attempt could succeed; the SDK then keeps the spans for the next drain. Anything else (includingNone) means "taken". - Timeouts:
timeoutis the remaining budget for this export (None= no deadline); honour it by narrowing your own configured timeout, never widening it. Declare how long a bareflush()should wait via theexport_timeoutattribute.CallerBudget(afloatsubclass marking budgets the application named) is a Python-only diagnostic refinement, not part of the cross-language SPI.
ConsoleTransport prints envelopes raw — pre-masking — to stdout; it is a
local debugging tool, never an export path.
before_send_envelope
The last-look hook before an export: init(before_send_envelope=hook) with
hook(envelope) -> Envelope | None. Return the received envelope object
to send (in v1 the only legal non-None return is that same object), or None
to drop the batch. It is synchronous, sees pre-masking data (masking runs
after it, inside the encoder), may run more than once for a batch a transport
declined, and a raise inside it drops the batch fail-closed with one
diagnostic line (traceback under debug=True).
Status
Works today
- Zero-instrumentation capture of LLM HTTP calls (OpenAI, Anthropic) over
https, cleartexthttp, and h2c — Chat Completions, the Responses API (the openai-agents SDK's default path, non-streaming and SSE, plus/v1/responses/compact), Embeddings, and Anthropic Messages gen_aisemantics: model, tokens, parameters, finish reasons, input/output messages- Open usage capture: every scalar leaf of the provider's
usageobject rides the span aswardex.usage.<provider path>, spelling preserved — a new billing counter (a cache-write tier, a web-search charge, a thinking tier) appears in your data the day the provider ships it, without an SDK release. Bounded bymax_extra_keys(default 64; a real usage object has 10–20 leaves), and a crossed bound says so: markerextra_keys_droppedpluswardex.usage_leaves.dropped_count - Failed provider calls (429 rate limits, 401s, 5xx) are captured with the same
gen_aiidentity and content as successful ones — only the response-side fields are empty - Transport metrics (TCP/TLS timing, TTFT), gRPC (grpclib), WebSocket (
wss; a Responses-over-WebSocket connection is captured at close and markedws_llm_semantics_unreadwhen the host isapi.openai.comor a subdomain ofopenai.com— on any other host with compression it is only counted, see capture_mode), MCP stdio - Export to any OpenTelemetry backend via
OtlpHttpTransport - Manual span decorators:
@workflow/@agent/@step/@tool - 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=PIIConfig(mode=PIIMode.OFF)to disable,pii=PIIConfig(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
batching=BatchingConfig(flush_on_signals=False)) - Shutdown closes agent runs that are still in flight, so an interrupted run
still exports its span — marked
unit_interruptedoradapter_uninstalled— instead of vanishing along with its open tool calls - Framework adapter: Anthropic Agent SDK (
claude_agent_sdk) — auto-detected, zero-instrumentationinvoke_agent/chatspans with tool-call correlation - Framework adapter: LangGraph (
langgraph>=1.2) — auto-detected, no callbacks and noLangChainTracer. Oneinvoke_workflowspan per graph run, oneexecute_stepspan per node (all retries of a node inside ONE span), oneexecute_toolspan per tool call dispatched by aToolNode, and every LLM and HTTP call underneath parented by in-process context propagation rather than by a frameworkrun_id. Coversinvoke/stream/ainvoke/astream/batch/abatch, the functional API (@entrypoint/@task), subgraphs, and agents built with eitherlanggraph.prebuilt.create_react_agentorlangchain.agents.create_agent.interrupt()andCommand(goto=…, graph=PARENT)are recorded as control flow, not as failures. ARemoteGraph(LangGraph Platform) call ships oneinvoke_workflowspan markedwardex.langgraph.remote, with the platform HTTP request underneath; the remote run's internals execute out of process and are not captured. A cached node ships no span — no work ran. - Framework adapter: OpenAI Agents SDK (
openai-agents>=0.22,<0.23) — auto-detected, hooked through the framework's ownTracingProcessor, nothing internal patched. Oneinvoke_workflowperRunner.run/run_sync/run_streamed, oneinvoke_agentper agent, ahandoff {from}→{to}marker with the receiving agent as the sender's sibling (not nested —wardex.agent.parentand ahandoff_fromlink carry the causality), oneexecute_toolper function tool with the call id recovered by a unique match against the response that requested it (labelledwardex.openai_agents.tool_call_id_source), oneevaluateper guardrail, andRunConfig(group_id=…)asgen_ai.conversation.idon every adapter span — unless the run sits inside the host's ownwardex.conversation(...), in which case the host's id stays on every span and the group id rides along on the root aswardex.openai_agents.group_id. The LLM calls stay the wire'schatspans, parented under the agent by context; the adapter discards the framework's usage so nothing is billed twice. By default the framework's own upload toapi.openai.com/v1/traces/ingestcontinues unchanged; wardex does not replace it. For the structure without that upload, IN THIS ORDER:agents.set_trace_processors([])and THENwardex.init()(the reverse order removes wardex's processor too).RunConfig(workflow_name=…)names the root; the default isAgent workflow. Runnable end to end inexamples/openai_agents_quickstart.py(see Works with openai-agents). Known limitations: the wirechatspans carry nogen_ai.agent.name— filter by walking up the tree to theinvoke_agentspan; a Responses-over-WebSocket run stays the counted, marked connection (ws_llm_semantics_unread) with no structure read from the frames; with the framework's tracing disabled wardex logs one INFO line at install and shows only the LLM calls; amax_turnshandled byerror_handlersstill ships ERROR on the agent and the root (the framework marks the span before consulting the handler); and withtrace_include_sensitive_data=Falsethe tool span carries thetool_call_id_unavailable_in_processmarker rather than a call id.
Not yet (see Roadmap)
- A LangChain adapter for plain LCEL chains (
prompt | model | parser) and tools invoked outside a graph — those produce no structural spans today, and a LangChain-built agent is covered by the LangGraph adapter above becausecreate_agentcompiles to aPregelgraph - The
conversationid in the request is not yet surfaced as a span attribute on the wirechatspans (nogen_ai.conversation.idthere). It is a plain field in the Responses request body — measured, present in every POST of aRunner.run(conversation_id=…)run — and the byte seam latches only the span context at request time, so the adapter'sgroup_iddoes not reach the chat spans either; it is a wire-side follow-up - Node/TS and Java SDKs
Notes
- After
os.fork()the SDK reinitializes its per-process state in the child viaos.register_at_fork: the inherited span buffer and any pending parse jobs are discarded (the parent still owns and exports them, so each span ships exactly once), locks and the worker threads are recreated, per-connection/per-session tracking tables are reset (a span assembled on a connection that crossed the fork carries thetracking_reset_at_forkmarker), and every batch stamps the liveprocess.pid, so a parent and its forked children are distinguishable at the backend.multiprocessingfork children flush their tail on exit; a hand-rolledos.fork()+os._exit()child should callwardex.flush()before exiting.spawn/forkserverstart methods launch a fresh interpreter and are unaffected. Under uWSGI enable threads (--enable-threads).
Resource limits
Every resource bound in the SDK — body size caps, buffer sizes, connection
and session tracking — is configurable through limits=LimitsConfig(...), but
the defaults suit most workloads and most users never need to touch this. The
body cap is set above the Anthropic Messages API's request size ceiling, so a
request the API itself accepts is never truncated by capture.
import wardex_sdk as wardex
from wardex_sdk import LimitsConfig
wardex.init(
limits=LimitsConfig(
max_body_bytes=64 * 1024 * 1024, # larger multimodal payloads
max_buffer_bytes=16 * 1024 * 1024, # tighter memory budget
)
)
The deferred-parse queue has its own pair: max_parse_backlog (2048) and
max_parse_backlog_bytes (64 MiB) bound how many completed-but-unparsed
transactions may wait for the finalize worker. Over either bound, the OLDEST
waiter ships immediately without its gen_ai block, carrying the
parse_backlog_full marker — never silently — and a transaction still
pending when a shutdown budget runs out ships the same way under
parse_skipped_at_shutdown. Resident memory is therefore at most one
backlog plus one span buffer.
max_body_bytes bounds two quantities, and only one of them is a message.
Besides capping a captured request or response body, it caps the bytes ONE
logical unit accumulates from its adapter-side records — a tool call's input
and output, an agent turn's payload — and the shaping budget an adapter derives
from that cap so it stops building a representation exactly where storage would
cut. Lowering it therefore lowers resident memory per live unit, which is the
reason to lower it. Raising it raises that memory: the worst case is about
2 x max_body_bytes per live unit, and the ceiling on live units is
max_units x max_entries_per_unit, not max_units — max_buffer_bytes bounds
the span buffer and does not cover a unit that is still open.
Raising it also raises a TRANSIENT cost that is paid on your own thread. The LangGraph adapter shapes a tool call's arguments synchronously inside the tool call, and building that representation peaks near four times the cap for escape-heavy text: measured at 128 MiB peak / 65 ms for one 64 MiB string argument at the 32 MiB default, and 256 MiB / 135 ms at the 64 MiB setting suggested above. Raise it for payloads you want captured whole, not by reflex.
Two of the bounds are about the wire rather than about capture. The OTLP surface encodes binary payloads as base64, so what leaves is up to a third larger than what was captured, and an OTLP request is accepted or rejected whole — a batch over the receiver's body limit does not arrive short, it does not arrive.
-
max_otlp_attribute_bytes(1 MiB) caps one attribute value as it appears on the wire. A value over it is truncated and the span says so with anotlp_attribute_truncatedmarker inwardex.limitations. -
max_otlp_request_bytes(4 MiB, gRPC's own receive ceiling) caps one request, measured both as the compressed body that goes on the wire and as the message it decompresses to — receivers check both. A batch over either is split across several POSTs instead of being sent whole and rejected. Raise it if your collector accepts more.A split is invisible in your traces, but that is the receiver's doing rather than the SDK's: the POSTs carry the same trace id, and a receiver keys spans by it, so what was one batch is stored and shown as one trace. Children routinely arrive in earlier requests than the parent they name — spans leave in completion order, so the root travels last — and a conforming receiver resolves the edge when the parent lands. A span so large it would not fit a request even with its payload removed is the one loss a split cannot absorb: it is dropped, the rest of its batch still goes, and the SDK says so on the diagnostic channel — once per process, at the first occurrence, with a count that covers that batch and is not a running total. That loss cannot be marked in
wardex.limitationsthe way a truncation is, because the marker would have to ride on the very span that never reaches the wire.
Requests are gzipped by default. OtlpHttpTransport(..., compress=False) turns
that off for a proxy or receiver that mishandles Content-Encoding.
max_extra_keys (64) bounds one open key family today: the provider-usage
mirror. wardex.usage.* is the one attribute family whose keys the provider
names rather than wardex, so it is the one place a pathological body could mint
unbounded keys. Lowering the knob prunes usage leaves only — every other
attribute is untouched — and a span that lost leaves carries
extra_keys_dropped with the count beside it as
wardex.usage_leaves.dropped_count. The normalized gen_ai.usage.* totals are
extracted separately and are never subject to this cap. (For scale: the mirror
adds ~5–10 attributes to an LLM span, and the richest span the test corpus
produces carries 47 attributes total against the OTel Collector's default
attribute_count_limit of 128.)
max_units, max_entries_per_unit and max_session_entries were on that list
until the logical-unit registry and the Agent SDK assembler became their
consumers. What crossing one of them looks like from your data depends on
whether the evicted entry has a span of its own.
Evictions you can see in your traces. A root unit evicted at max_units, a
child unit or an in-flight span evicted at max_entries_per_unit, and an open
tool call or a sub-agent evicted at max_session_entries, are each closed and
exported, marked unit_evicted, unit_table_full or
session_entry_table_full. Outgrowing one of these ceilings shows up as marked
spans rather than as traces that quietly stop appearing. Each marker names the
one knob that produced it, so the marker tells you which number to raise.
A span evicted at max_session_entries carries status unset rather than
ok or error: wardex stopped watching before the call's outcome, so ok
would claim a success it never observed and error would report wardex's own
full table as a failure of your agent.
One call, two observations. If an evicted tool call later completes, its
completion is reported as a second span with the same gen_ai.tool.call.id,
also marked session_entry_table_full, and the two overlap: the unset one is
[start, evicted] and holds the call's input, the other is [start, end] — the
whole call — and holds its output. When you aggregate tool latency, exclude
the spans that carry session_entry_table_full AND status unset, or you
count that call twice.
Evictions you cannot. The two per-table knobs also bound bookkeeping tables
whose entries are not spans — the lookup aliases that map a framework's own
identifiers onto units, the keys that de-duplicate two observers of one event,
the table of
in-process MCP servers wardex has wrapped, and the streamed tool metadata the
assembler holds until a result arrives. Evicting from any of them exports
nothing, because there is no span to mark. They are counted internally instead —
wardex_sdk._assembly.counters.snapshot() reports them under
assembly._units.alias_table_full, assembly._units.claim_table_full,
adapters.anthropic.server_table_full and
adapters.assembler.stream_tool_meta_table_full — and what reaches your data is
the consequence rather than the eviction. A dropped de-duplication key, or a
dropped server handle, can let one tool call be reported twice. A dropped
streamed metadata entry costs a tool call its byte-exact input, and if no hook
observed that call, its span entirely.
A dropped alias is the one to know about, because it does not look like a
loss. That identifier stops resolving, so the parent is decided one rung further
down: if the work carries an ambient wardex span, the span arrives at confidence
1.0 with no marker — hanging off the enclosing session instead of the
sub-agent it belonged to. A sub-agent's subtree flattens and nothing in the data
says so. Only when there is no ambient span does it arrive marked
unit_inferred_sole (0.5) or parent_unresolved.
The evictions that DO reach your traces are counted as well, so you can see one
coming before it is a shape in your data:
adapters.assembler.open_tool_table_full and
adapters.assembler.subagent_table_full for the two max_session_entries sites
that emit, plus adapters.assembler.tool_completion_after_evict for the second
half of a call the first one closed.
Which number to raise depends on which counter moved.
assembly._units.* and adapters.anthropic.server_table_full are
max_entries_per_unit; every adapters.assembler.*_table_full is
max_session_entries. The two are separate fields — the core limits table
calls the first a generalization of the second, but raising it leaves the second
exactly where it was.
Versioning
Version semantics, what 0.x betas may break, the deprecation mechanism, and
how the SDKs and the wire schema version relative to each other are recorded
in VERSIONING.md. wardex_sdk.__version__ is the canonical
runtime version probe.
Roadmap
PII masking (pre-send safety)— shippedBatching & lifecycle (background worker, at-exit/periodic flush, concurrency)— shippedDistributed propagation (W3C)— shipped- Framework adapters —
Anthropic Agent SDKshipped;LangGraphshipped;OpenAI Agents SDKshipped; LangChain (non-graph runnables) next - Node/TS and Java SDKs
PII masking caveats:
before_send_envelopesees 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.
Metadata
Release files for wardex-sdk 0.6.0b1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| wardex_sdk-0.6.0b1-cp310-abi3-win_amd64.whl | CPython 3.10 | abi3 | Windows x86-64 | Details for wardex_sdk-0.6.0b1-cp310-abi3-win_amd64.whl |
| wardex_sdk-0.6.0b1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl | CPython 3.10 | abi3 | Linux glibc 2.17+ x86-64 | Details for wardex_sdk-0.6.0b1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
| wardex_sdk-0.6.0b1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl | CPython 3.10 | abi3 | Linux glibc 2.17+ ARM64 | Details for wardex_sdk-0.6.0b1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
| wardex_sdk-0.6.0b1-cp310-abi3-macosx_11_0_arm64.whl | CPython 3.10 | abi3 | macOS 11.0+ ARM64 | Details for wardex_sdk-0.6.0b1-cp310-abi3-macosx_11_0_arm64.whl |
| wardex_sdk-0.6.0b1-cp310-abi3-macosx_10_12_x86_64.whl | CPython 3.10 | abi3 | macOS 10.12+ x86-64 | Details for wardex_sdk-0.6.0b1-cp310-abi3-macosx_10_12_x86_64.whl |
Total release size: 11.7 MB
Release files / wardex_sdk-0.6.0b1-cp310-abi3-win_amd64.whl
| Download URL | wardex_sdk-0.6.0b1-cp310-abi3-win_amd64.whl |
|---|---|
| Size | 2.1 MB |
| Tags | CPython 3.10 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
3ac22066a1bead86a3f1f1df72f08fef060d8b6cd5be56aac60d7f5fd7ac7670
|
|
BLAKE2b-256 checksum How to use checksums |
61bba3eddf0a7ce8f41c38ada9c96f3ffb0cc77e87700ada47de097d32ef0265
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 6, 2026.
Transparency logRelease files / wardex_sdk-0.6.0b1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | wardex_sdk-0.6.0b1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 2.5 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
08c6785cfc148a064509b36af13a4794f700ff8766b095115e93ea13d036e89a
|
|
BLAKE2b-256 checksum How to use checksums |
5158d5b49b8ef36e9e6379b83a77267fdce9be4eced80149e8c72b9bb6715c11
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 6, 2026.
Transparency logRelease files / wardex_sdk-0.6.0b1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | wardex_sdk-0.6.0b1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 2.5 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
52edd3887a82fbb96608c22099fa58f2482dd8c278b2e506b995d926fb27b46e
|
|
BLAKE2b-256 checksum How to use checksums |
5fe238762c3dc4f15bf7bc8f2abdae411ba40ddee13cb266e6ba894e716f7d8c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 6, 2026.
Transparency logRelease files / wardex_sdk-0.6.0b1-cp310-abi3-macosx_11_0_arm64.whl
| Download URL | wardex_sdk-0.6.0b1-cp310-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 2.2 MB |
| Tags | CPython 3.10 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
e46adcdc0190bf23ba9e4993abf56269a6c8ffb7eccdc2c50396d0cfc85e9044
|
|
BLAKE2b-256 checksum How to use checksums |
ac65fe67e2d57f400c95a79f3d13ac2a1ba8ac8322aabd1caf008bc2d4452a73
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 6, 2026.
Transparency logRelease files / wardex_sdk-0.6.0b1-cp310-abi3-macosx_10_12_x86_64.whl
| Download URL | wardex_sdk-0.6.0b1-cp310-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 2.4 MB |
| Tags | CPython 3.10 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
a423d06a31b7e38e0b7fe1037cadc0bf0a190401378f414e5d98a7eaba72876c
|
|
BLAKE2b-256 checksum How to use checksums |
99007fdb9723ea9bb7bcaee28e6386864a76b284bbe657c06310ae122328f0cb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 6, 2026.
Transparency logSecurity for wardex-sdk 0.6.0b1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 5 files in this release have been uploaded with provenance metadata.
Attestation for wardex_sdk-0.6.0b1-cp310-abi3-win_amd64.whl
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 6, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.