mainwave

Python SDK for the Mainwave AI observability platform.

Install

pip install "mainwave[openai]"        # one platform
pip install "mainwave[langchain]"     # LangChain + LangGraph, captured automatically
pip install "mainwave[all]"           # everything (kick-the-tires only)

Per-platform pinning is recommended in production.

Quickstart

import mainwave

mainwave.init(
    api_key="...",  # or MAINWAVE_API_KEY
    use_case_key="invoice-workflow",  # or MAINWAVE_USE_CASE_KEY — a stable name; the SDK derives the use-case UUID
    collector_url="https://collector.mainwave.com",  # default
)

with mainwave.run("INV-12345", metadata={"customer": "acme"}):
    # ... do work; auto-instrumented LLM calls land under this run
    ...

mainwave.flush()  # before exit

init() auto-wires every supported instrumentor that's already importable, so the snippet above needs no instrument() call. Reach for instrument() only to wire a framework imported after init() ran (lazy import, CLI subcommand, FastAPI lifespan) — see Public API.

mainwave.run(...) is optional — without it, every OTel trace becomes its own logical run. Wrap explicitly when one logical operation spans multiple traces (loops, fan-out, multiple LLM invocations per request); the integration guide wraps every agent execution for exactly this reason.

Naming your use case (use_case_key vs use_case_id)

use_case_id means you bring the UUID (created in the Mainwave app); use_case_key means you bring a stable name and the SDK derives the UUID deterministically — same key, same identity, across runs, restarts, and machines. Passing both raises. The first run under a new key surfaces in the app under Unassigned Agents, named by the key, ready to adopt in one click.

Resolution, innermost wins:

1. explicit use_case_id — anywhere
2. use_case_key= on run() / bind_identity() (top-level roots)
3. use_case_key= on init(), or MAINWAVE_USE_CASE_KEY
4. (default) an agent_name bound at a run root → f"{service_name}/{agent_name}" — one use case per agent
5. (default) service_name — one use case per deployable

Treat the key like a database key: renaming it forks the use case. Keys are case-sensitive and trimmed; mainwave.use_case_id_for("my-key") (or agent_name="…") predicts the derived UUID for scripts and CI. Set ucid_namespace= / MAINWAVE_UCID_NAMESPACE to your org's issued namespace (shown in the app) so derived identities survive API-key rotation — without it, derivation seeds on the API key and rotating the key moves every derived identity (the SDK warns at init).

Not seeing data?

The SDK never raises into your app, so a misconfigured endpoint or key fails quietly. Turn on its logger to see what's happening:

import logging

logging.getLogger("mainwave").setLevel(logging.INFO)  # add a handler if you have none

At INFO it logs the first successful export, which instrumentors wired, and a WARNING for any framework that didn't. mainwave.flush() returns False on a failed drain — check it before a hard exit. Confirm collector_url and the API key, and that the framework's extra is installed (pip install "mainwave[openai]").

Process exit and signals

init() registers an atexit hook that flushes buffered spans on normal interpreter shutdown. It also installs a SIGTERM handler (main thread only) so containers stopped with SIGTERM still flush before exit. The handler chains: it flushes, then hands control back to whatever SIGTERM disposition was in place before init() ran — if your app had its own handler, it runs after the flush and owns the exit; if SIGTERM was default, the process exits with the conventional 128+signum status; if it was ignored, the SDK stays out of the way. Repeat init() calls don't re-install, so the SDK never chains to itself.

Set MAINWAVE_DISABLE_SIGNAL_HANDLER=1 to skip installing the SIGTERM handler entirely (the atexit flush still registers) — use this if your process manages SIGTERM itself and doesn't want the SDK touching it.

Public API

• mainwave.init(...) — set up the SDK once, at process start.
• mainwave.instrument(name=None) — re-wire instrumentors after late imports.
• mainwave.run(...) / mainwave.arun(...) / mainwave.start_run(...) — open a logical run (sync CM, async CM, imperative).
• mainwave.span(name, attrs=...) — escape hatch for manual spans.
• mainwave.flush(timeout=30.0) / mainwave.aflush(timeout=30.0) — drain buffers.
• mainwave.testing — reset() + install_in_memory_provider() for tests.

LangChain users

init() wires LangChain / LangGraph capture automatically when mainwave[langchain] is installed — nothing is passed to .invoke() / .stream(). The registry entry langchain points at mainwave.langchain.LangChainInstrumentor, the SDK's subclass of the official opentelemetry-instrumentation-genai-langchain package: upstream owns span lifecycle and structure (invoke_agent / invoke_workflow / chat {model} / execute_tool / retrieval spans), and the subclass adds graph-node spans, corrected chat content and tokens, and reasoning. Opt out with init(skip_instrumentors=["langchain"]).

Several agents in one process

Each agent reported as its own use case is the default: bind the agent's name at its run root and the per-agent identity derives automatically —

with mainwave.run("INV-12345", agent_name="divergence"):
    ...  # lands in the "your-service/divergence" use case

# or around a LangChain call directly, with no enclosing run():
with mainwave.bind_identity(agent_name="divergence"):
    graph.invoke(payload)  # a LangChain ROOT run starting here derives the
    # per-agent default from the bound name

To group several agents under ONE use case instead, bind the identity at the outermost root you own and leave the inner surfaces identity-free — they inherit:

with mainwave.run("INV-12345", use_case_key="invoice-workflow", agent_name="extractor"):
    ...  # every agent inside shares the invoice-workflow use case

An explicit use_case_id= / use_case_key= bound in a nested bind_identity() (or a nested run()) wins over an enclosing root's binding (a deliberately multi-use-case run). Omit identity args to inherit; an empty value is ignored rather than applied. If your process identity is an explicit use_case_id, agent names stay a display axis and never move telemetry.

Running inside a service that already uses OpenTelemetry

If your process already has its own OpenTelemetry setup (FastAPI/DB auto-instrumentation, background-job spans, …), the SDK coexists with it. It attaches to your existing TracerProvider rather than replacing it, and it exports a trace to Mainwave only when that trace involves an LLM call — your service's own infrastructure traces stay out of Mainwave. When a trace does contain an LLM call, it's sent in full, so the surrounding request span that triggered the call is preserved and correlated. This mirrors how Langfuse filters export on a shared provider; you don't have to isolate the SDK or wire a separate provider.

Redacting sensitive data

Give the SDK rules and it replaces every match in a span's content before the span leaves your process. You can turn on built-in rule packs, write your own regular-expression rules, or pass a masking function. Without any of them, nothing changes.

import mainwave

mainwave.init(
    redaction={
        "packs": ["secrets", "pii.contact"],
        "blocked_values": [{"name": "account", "pattern": r"ACCT-[0-9]{8}"}],
        "allowed_values": [r"[A-Za-z0-9._%+-]+@example\.com"],
    },
)

With these rules, the prompt Mail jo@acme.com, cc ops@example.com, key sk-A1b2C3d4E5A1b2C3d4E5XYZ, account ACCT-12345678 is exported as Mail [REDACTED:pii.contact.email], cc ops@example.com, key [REDACTED:secrets.openai_api_key], account [REDACTED:account], and the span carries mainwave.redaction.count = 3.

The same rules as a JSON file (the same shape as the dict) work through an environment variable, so a deployment can change them without a code change:

export MAINWAVE_REDACTION_FILE=/etc/mainwave/redaction.json

When both are set, the init(redaction=...) argument wins, the file is not read, and the SDK logs one warning saying so. The masking function (mask=) is passed in code only.

Rule set

Every key is optional. Any other key is an error.

A rule is a pattern string, or {"name": ..., "pattern": ..., "case_insensitive": true}; name and case_insensitive are optional. Each replacement counts 1. The field names follow the OpenTelemetry Collector's redactionprocessor, so existing patterns carry over once they fit the grammar below.

Rule packs

Each pack is a set of tuned patterns. A pack only runs when packs lists it, and its rules are named <pack>.<rule>. Packs always run in one fixed order, whatever order you list them in: secrets, pii.contact, pii.us_gov_id, pii.payment_card (so a card rule never reads the digits inside a Slack token before the secrets pack has replaced the token). Pack rules run before blocked_values and obey allowed_values, ignored_keys, ignored_key_patterns and blocked_key_patterns like any other rule. The patterns favour precision over recall: they miss unusual formats rather than redact ordinary text. Every quantifier in them is bounded, so a pattern cannot run away on a long input.

Trade-offs to know before turning one on:

• Length bounds: tokens and keys longer than 255 or 256 characters, a PEM body over 8,192 characters, a PEM header of more than 4 words or with a word over 16 letters, and JWT segments over 1,024 (header) or 8,192 are not matched at all, or only up to the bound.
• pii.contact also matches addresses such as git@github.com. The E.164 rule treats + plus 8-15 digits as a phone number, so it also matches +2024-01-15 and other signed decimals, coordinates and IP-like numbers (+40.7127753-074.0059728, +1.23456789, +192.168.100.200), because . and - may separate digits. A phone number followed by one space and more digits absorbs them up to 15 digits in total.
• pii.us_gov_id matches any 123-45-6789 shaped group.
• About 1 in 10 random digit strings starting 2-6 passes the Luhn check, so pii.payment_card can redact an order number. A 16-digit card followed by a 3-digit number can pass as one 19-digit match. Card groupings 4-6-6, 4-4-8, 8-8 and 4-12 are not covered.
• pii.contact matches image names such as image@2x.png, and does not match parenthesized international numbers (+44 (0)20 7183 8750) or numbers with a 00 prefix.
• Only string attribute values are scanned. An integer, float or bytes attribute is sent as is, so a card number stored as an integer is not redacted (numbers inside a JSON string attribute are).
• The prefixed token rules match even when the token is glued to other text (after a literal \n, %0A or _); the bare sk- and AKIA rules do not. The scoped sk- rule matches only the prefixes proj, svcacct, admin, None and or-v1, so ordinary words (risk-management-..., flask-api-...) are left alone and a key with another prefix is not matched. A word ending in sk followed by a listed prefix and a 20+ character body still matches (flask-admin-..., task-admin-..., desk-proj-...), so benign text can be over-redacted, but nothing leaks. A GitHub token ending in _ and the tail of an encrypted JWE are not matched.
• The AWS key rule matches AWS's published example keys but not the 40-character secret access key.

Pattern grammar

Patterns use one grammar, shared by the Python and Node SDKs, so one rules file redacts identically in both. The SDK checks every pattern against an allowlist when init() loads it and then translates it for Python's re; your text is never handed to the regex engine as written. Anything outside the grammar is rejected, naming the rule.

What the elements mean, which is not always what your regex engine does:

Rejected, because the engines disagree or the construct is unsafe: lookahead and lookbehind, inline flags ((?i); use case_insensitive), named, atomic and comment groups, backreferences, \A \Z \z \p{..} \u, possessive and stacked quantifiers (a*+, a**), a quantifier on an anchor or on a group that can be empty ((a*)*), a stray {, } or ], and in a class a ] first, an unescaped [, &&, -- and ~~, a reversed range, a range ending in an escape, and a stray -. Write a literal && or ~~ in a class as \x26\x26 or \x7e\x7e, and a literal -- as \-\-.

A pattern that can match without consuming a character (a*, \b, ^, (?:ab)?) is rejected: it has nothing to replace.

Five cost limits cap a pattern and reject the classic exponential forms when init() loads it:

Unbounded quantifiers at the top level (a+b) stay allowed, and so do alternatives of the same length that overlap ((?:a|a)*c).

What is scanned

JSON in place. An attribute that is one strict JSON text (an object or an array, RFC 8259, with only JSON whitespace around it) is redacted in place. The SDK scans each string and number value on its own, so a rule never matches across two values, and rewrites only the values that change: key order, duplicate keys, whitespace, number spelling and untouched escapes (é, \/) stay exactly as they were. A changed string is written back as a JSON string; a changed number becomes a string, so a card number stored as the JSON number 4111111111111111 is exported as "[REDACTED:...]". Text that is not strictly valid JSON (a trailing comma, NaN, single quotes, a raw tab, text after the value, a non-breaking-space pad) is scanned as one plain string. Nesting depth is not limited.

Resource, link and event attributes follow the same rules and exemptions as span attributes; the span name and status description have no key, so key rules and key exemptions never apply to them. The replacement count is written to the span's own attributes, including replacements made in its resource, links, events and status description.

Attributes that are never scanned

Identity and accounting attributes are exempt, and no rule, pack or masking function can change that: a rule that matches them leaves them as they were, and ignored_keys only adds to the list. The exempt keys are those the platform reads back verbatim as identifiers, enums and references, including mainwave.ucid, mainwave.run_id, mainwave.user_email, user.email, gen_ai.agent.name, gen_ai.operation.name, gen_ai.provider.name, gen_ai.tool.name, gen_ai.tool.call.id, gen_ai.conversation.id, service.name and mainwave.redaction.count. An email address stored under mainwave.user_email or user.email is therefore sent as is. Model names (gen_ai.request.model) and all other attributes are scanned.

Masking function

For anything a pattern cannot express, pass a function. It receives each scanned string and the attribute key it came from, and returns the replacement:

import hashlib


def mask(value: str, key: str) -> str:
    if key == "customer.note":
        return "[note withheld]"
    if "internal-host" in value:
        return value.replace(
            "internal-host", "host-" + hashlib.sha256(value.encode()).hexdigest()[:8]
        )
    return value


mainwave.init(mask=mask)  # works with or without `redaction=`

A masking function with no redaction rules still runs on every span.

Order of operations and size limits

Redaction runs after the SDK normalizes a span and before it shortens long values, so a secret that straddles a length cut is replaced whole and no part of it is exported. The length limits still apply to the redacted text. Three places cut strings before the exporter would:

• The LangChain and CrewAI integrations shorten very long strings (8192 characters by default) when they capture them. With rules configured they end that cut before any match it would split, so the exporter still sees the whole secret; a cut text can therefore be a little shorter than the limit. The check looks only at a window around the cut: as wide as the rule's longest possible match, so its cost does not grow with the string. A user rule with an unbounded quantifier at the top level (*, +, {n,}) gets a fixed window of 16,384 characters each side (every pack rule is bounded and uses its own), and a match longer than that can still be split. Give user rules bounded quantifiers. A masking function sees the text after that cut.
• OpenTelemetry's attribute value length limit (OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT, OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT) cuts a value when it is recorded. When init() owns the provider and redaction or a masking function is configured, the SDK lifts that limit from the provider and applies the same limit itself, after redaction, to the attributes the span was recorded with and to event and link attributes. The result is what the provider would have produced, except that a match on the boundary is replaced whole.
• A provider you own (the SDK sharing your TracerProvider) is not the SDK's to change. If a value length limit is set there and redaction is on, init() logs one warning: the provider cuts values before redaction, so a secret straddling the cut can leave a prefix no rule matches. Remove the limit or let the SDK own the provider.

Pattern cost

The grammar's cost limits are the only static cost rules. Beyond them your patterns are your responsibility, and they run synchronously with no timeout: on the exporter thread when a span is exported, and on the request thread for the LangChain and CrewAI capture-time cut. A slow pattern stalls that thread.

• Adjacent overlapping quantifiers are accepted and cost O(n^(k+1)) for k of them: \w*\w*\w*\w*\w*\w*x on 64 as with no x takes about 4 s in Python (in Python, about 0.4 s with five \w* and 0.04 s with four).
• A bounded quantifier over a variable-length group (different-length alternatives, an optional member or a nested quantifier) and bounded nesting are accepted and can be exponential on a run of as with no x: (?:a|aa){1,1000}x takes 4.6 s in Python (6.9 s in Node) on 38 characters, and (?:a?a){1,40}x 2.0 s in Python (2.9 s in Node) on 36. The fixed-length rule only constrains unbounded quantifiers.
• A top-level a+b is quadratic on a long input of as.

Prefer bounded quantifiers ({1,64} rather than +) and test patterns against long inputs. The built-in packs are bounded and tested at 256 KiB per input (the slowest, the PEM rule on repeated headers, takes about 0.5 s in Python).

Failure behavior

When the SDK shares a TracerProvider with your own OpenTelemetry setup, only the export to Mainwave is redacted. Exporters you configured yourself receive the original, unredacted spans.