Defaults are capture="text", redacted=True: prompts, responses and tool data, but no images, audio or embedding vectors (most tracing platforms keep media bytes out of spans by default; capture="full" exports them inline when you ask for it). metadata selects structural attributes (IDs, models, timing, usage counts, HTTP/RPC/DB structure); text adds readable prompts, responses, tools, errors, events, and link attributes while excluding recognized media and embedding vectors; full captures all supported content. With redacted=True, background cleaning masks detected PII and credentials only. Harmless SQL, URL parameters/fragments, exception details, custom metadata, names, and scope versions remain readable when selected. Sensitive values within SQL, DB URLs, URLs, events, and links are cleaned without hiding the complete record. The configured key (api_key=, or a Bearer token passed in headers=) is removed from protected export copies. To select extra metadata keys, use capture_allow_keys=["app.tenant_tier", "myco.*"] or BOTGAUGE_CAPTURE_ALLOW_KEYS=app.tenant_tier,myco.*; protected values are still cleaned. redacted=False overrides capture selection in every mode: metadata/false, text/false, and full/false export the same original supported FULL records, including sensitive data, without privacy scanning, masking, or sanitizer truncation. FULL/SKELETON/DROP topology filtering still applies; skeletons remain minimal. Raw export cannot recover content already discarded by a customer-owned producer or exceed OTel's supported data types and limits. BotGauge-owned producers use capture controls matching the resolved policy; raw configuration disables BotGauge's own content hiding. Your OPENINFERENCE_HIDE_* settings still apply to them in every mode and can only hide more. Customer-owned instrumentation and exporters remain intact. Privacy patterns do not detect every sensitive fact or credential format. Protected values retain documented technical size/work limits. Supported numeric PII is inspected across integers, integral floats, numeric strings, and serialized structures. Recognized numeric usage, cost, and duration measurements retain their values and types; arbitrary numeric IDs still receive PII inspection. A subtree beyond the sanitizer's depth limit is replaced by [omitted: inspection limit], indicating a technical omission rather than detected PII. Native containers have an 8-level limit and parsed structures a 64-level limit. String caps and sequence caps can truncate content separately: a list keeps its first 128 elements, and a map its first 128 entries plus an [omitted: inspection limit] entry counting the rest. These sanitizer limits do not apply with redacted=False. Metadata omissions and text media exclusions are capture selection, separate from sensitive-value masking. Zero-code settings are BOTGAUGE_CAPTURE=metadata|text|full and BOTGAUGE_REDACTED=true|false. Invalid capture values, including the previous redacted spelling, fall back to protected metadata. Migrate to capture="text", redacted=True. Invalid boolean environment values enable protection. Reconfigure export policy through shutdown() and a new init(); restart zero-code processes to change producer capture controls. Forks preserve both settings. doctor reports requested/effective capture and protection without payloads or credentials.

Run each capture mode separately with protection enabled. Use the virtual environment containing the updated SDK and your application's dependencies, with the endpoint/API-key settings above:

BOTGAUGE_CAPTURE=metadata BOTGAUGE_REDACTED=true botgauge instrument python your_app.py

BOTGAUGE_CAPTURE=text BOTGAUGE_REDACTED=true botgauge instrument python your_app.py

BOTGAUGE_CAPTURE=full BOTGAUGE_REDACTED=true botgauge instrument python your_app.py

Replace your_app.py with your script. Each command starts a new process. Metadata selects structural content, text adds readable text while excluding recognized media/vectors, and full selects all supported content. With BOTGAUGE_REDACTED=true, selected content receives sensitive value cleaning. Setting BOTGAUGE_REDACTED=false enables original supported FULL content in all three modes, bypassing their capture exclusions and privacy cleaning.

BotGauge is built on the OpenTelemetry SDK, so some standard variables affect it too. Where a row says "when BotGauge creates the provider", it applies when you call tracing.init() without tracer_provider= and no provider is set up yet; otherwise your own provider's configuration applies.

init() sends the key as Authorization: Bearer <key>, BotGauge's only credential. An Authorization header passed in headers= replaces it. Arguments win over the environment: without api_key= or endpoint=, init() reads BOTGAUGE_API_KEY / BOTGAUGE_ENDPOINT, and a key with no endpoint exports to https://api.botgauge.com/v1/traces. It never reads .env files (load them in your app, e.g. with python-dotenv) or OTEL_EXPORTER_OTLP_*. The first 401/403 from the endpoint logs one botgauge: BotGauge rejected the API key (...) line with the server's reason. The line names the Authorization header instead when headers= supplied it, and says that no credential was sent when an endpoint is set without a key.

BotGauge disables export when a key or custom headers would be sent to a remote http:// endpoint, or to an endpoint with no http:// or https:// scheme. Local HTTP collectors remain available. Use https:// for remote collectors, and add a scheme to an endpoint that has none. If you deliberately need remote cleartext HTTP, set BOTGAUGE_ALLOW_INSECURE_HTTP=true; BotGauge still warns that the connection sends headers without transport encryption. Ambiguous URL authorities are treated as remote.

With neither a key nor an endpoint, BotGauge emits a configuration notice to stderr and discards its exports; it does not print spans. For local development only, set BOTGAUGE_CONSOLE_EXPORT=1 to explicitly send sanitized spans to stdout. A customer-owned OTel exporter attached to the same provider continues to operate independently.

Streaming generators: Keep a turn() scope within one execution context. Do not leave it open across yield when a framework may resume each chunk in a fresh context (for example, a synchronous generator consumed through Starlette's thread pool). Later chunks can lose their turn and parent span, and closing the scope can log Failed to detach context. Finish traced work before yielding, or keep the entire iteration in one context. If chunks run in separate contexts, start and end each tracing scope within the context that processes that chunk; preserving one Turn across the whole stream requires the application to preserve its context as well.

Or keep the settings in a .env file: botgauge instrument --env-file .env python your_app.py. It reads KEY=VALUE lines the way uv run --env-file and docker run --env-file do: comments, an optional export prefix, and quotes are handled, and variables aren't expanded. It never overrides a variable that is already set, so real deployment settings win. The flag can be repeated; an earlier file wins over a later one. Manual tracing.init() does not read .env; load it in your app (e.g. with python-dotenv).

Zero-code export reads only BOTGAUGE_ENDPOINT (default https://api.botgauge.com/v1/traces when BOTGAUGE_API_KEY is set) for its destination. Customer OTEL_EXPORTER_OTLP_* settings are left to the customer's OTel exporters in both directions: BotGauge never uses them as a fallback destination for its connection token, and BotGauge's own exporter ignores them, so customer collector headers, TLS files, timeout, and compression are never applied to BotGauge export (which always uses gzip). With neither variable set, BotGauge export is disabled by default and a configuration notice is written to stderr; the explicit development-only BOTGAUGE_CONSOLE_EXPORT=1 setting still enables console output.

Selects certified framework producers from the versioned compatibility registry and activates compatible OTel transport instrumentors via standard opentelemetry_instrumentor entry points. The registry covers pinned LangChain/LangGraph, direct OpenAI, direct Anthropic, LlamaIndex+OpenAI, CrewAI, OpenAI Agents, Google ADK, AutoGen AgentChat and MCP (each with only its own producer). Certification records the versions BotGauge verified, as (framework, instrumentor) pairs: a framework version is verified only with an instrumentor version it passed certification with. Only those exact pairs are verified, never a range: a version older than the oldest verified, between two verified versions, newer than the latest verified, or a pre-release is not verified. Verified pairs stay verified when newer ones are added. It is not a requirement. An installed framework at a version that isn't verified is still traced, and startup logs one line per framework saying why: botgauge: tracing openai at a version BotGauge has not verified: openai 3.40.0 is newer than the latest version BotGauge verified (3.35.1); verified: .... Inside the app, tracing.doctor.report()["instrumentors"]["not_verified"] returns them; a separate botgauge doctor process cannot see the app's activation. Set BOTGAUGE_VERIFIED_ONLY=1 to trace only verified versions. Versions the registry lists as known to break tracing are never traced, and startup says why. AI instrumentors that aren't in the registry are still skipped. BotGauge checks the public OTel already-instrumented marker and supports explicit customer ownership via BOTGAUGE_PRODUCER_OWNER=langchain=customer. Set BOTGAUGE_STRICT=1 to make selection failures and versions that aren't verified fatal for CI (or use botgauge instrument --strict python your_app.py): the launcher logs botgauge: --strict: not starting the application: <reasons> and exits 1 before the app runs. Ownership also accepts registered entry-point names such as llama_index=customer (the canonical target is llamaindex); unknown names produce a warning. A producer that traces several frameworks (the LangChain instrumentor also traces LangGraph) stays off when the customer owns any of them; the others are then not traced by BotGauge, so they are not reported as not verified, and importing one logs missing-producer guidance that names that ownership. An installed producer extra without its framework is reported as absent and does not fail strict mode. Resolve actual selection findings or disable strict mode; setting BOTGAUGE_VERIFIED_ONLY=1 alone does not clear strict failures. Strict mode also stops the app if the target Python cannot import BotGauge or if interpreter options -I, -E, or -S would bypass the startup hook. When an app imports a registered framework without an active producer, startup logs one recommendation for the BotGauge extra, or points to botgauge doctor if the extra is installed but did not activate. Client libraries that frameworks import themselves (openai, anthropic, mcp) get no hint while a framework producer is active, so --strict does not fail a correctly traced framework app; importing langchain_core (as langchain_openai does) counts as importing LangChain. Unknown frameworks are not guessed. If a missing producer is discovered on a later framework import, strict mode logs the guidance and exits the whole process with code 1, including when the import occurs in a worker thread; the application may already have started by then. Selected instrumentors use the same FULL/SKELETON/DROP filtering and privacy pipeline. Works with python -m pkg, any python3.x binary, sibling imports next to your script, and child processes your app spawns (they inherit instrumentation the same way gunicorn --preload workers would). The directory you run botgauge instrument from is importable by the launched app, after the standard library and installed packages so it can't shadow them. Unlike opentelemetry-instrument, it is not put on PYTHONPATH: child processes don't inherit it, a sitecustomize.py in it is never run, and python -P or PYTHONSAFEPATH keep it off the path.

Zero-code mode opens an implicit Turn only at a top-level certified Agent span, with no active tracing.turn() and no inbound remote parent. An app that only runs chains or LLM calls (a plain LangChain prompt | llm, or a LangGraph graph, whose root span is a CHAIN) produces no Agent span, so its spans carry no botgauge.turn.* attributes; wrap each interaction in tracing.turn() to group it. An Agent label set after a span starts is read when a nested Agent decides whether it is top-level, but a label set on an outer span only after a nested Agent's Turn decision (at its start, or at its end if it was labelled late) cannot move the root back to the outer span; set the outer Agent's label at start, or use tracing.turn().

Forking servers (gunicorn --preload, multiprocessing): under botgauge instrument, each forked worker rebuilds its own BotGauge pipeline automatically (new exporter connection and batch thread, same settings), so the application needs no post_fork hook. With manual tracing.init(), call init() again after the fork, as before. Either way, a fork-context multiprocessing or billiard worker sends its queued spans when it exits normally, waiting at most one second (none when export is already failing). A pool closed with terminate(), which includes leaving a with Pool(...) as pool: block, stops its workers before that, so their spans are lost: use pool.close() and pool.join(), or call tracing.flush() at the end of each task. On macOS only, a forked worker that makes any HTTP request after the parent has started threads is killed by the Objective-C runtime; this affects preload apps with or without BotGauge, and not Linux. For local development on macOS, set OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES in the server's environment.

PydanticAI is a zero-code producer at its verified versions (PydanticAI 1.25.1 and 2.57.0 with openinference-instrumentation-pydantic-ai 0.1.30, and 1.25.1 with 0.1.27). It instruments itself natively and OpenInference ships a span processor rather than an instrumentor, so BotGauge activates it through its own botgauge.native_producers entry point: botgauge instrument calls Agent.instrument_all() on BotGauge's provider (GenAI span names, text content recorded with capture="text" or "full", and with every raw override) and attaches OpenInferenceSpanProcessor. If your application already instruments PydanticAI, BotGauge reports a duplicate and leaves it unchanged; set BOTGAUGE_PRODUCER_OWNER=pydantic-ai=customer to declare that ownership explicitly. The PydanticAI 1.25 cohort runs on OTel 1.39.1, which conflicts with the currently tested non-PydanticAI multi-extra OTel 1.44.0 constraints. A resolver dry-run with only PydanticAI's OTel 1.39.1 constraints succeeds for [frameworks] (every instrumentor at once), but no installed combined runtime, pip check, or framework tests have been validated. Do not infer that [frameworks] or a mixed PydanticAI producer is verified merely because the extra resolves.

botgauge doctor   # read-only report: what's active, what's missing, no side effects
botgauge doctor --strict  # exit 1 for uninitialized tracing, propagation or selection problems
botgauge doctor --json    # the same read-only report as machine-readable JSON

doctor observes only the current process: running it separately from your app cannot inspect the app's activation report. doctor --strict does not emit a probe span or mutate instrumentation.

botgauge setup --detect lists recommended producer extras without importing frameworks or installing anything. botgauge setup --install explicitly installs the listed extras with pip; no automatic installation occurs on startup.

Explicit ingest diagnostic

BOTGAUGE_API_KEY="..." botgauge probe --endpoint https://your-collector/v1/traces

Unlike doctor, probe sends data: one metadata-only botgauge.probe span through the BotGauge privacy/filter/batch pipeline to the specified OTLP HTTP endpoint. It requires an explicit URL (no console fallback), runs in its own process, and exits nonzero if ingest acceptance cannot be confirmed. A success confirms OTLP export was acknowledged, not that a downstream worker normalized or stored the span. The key is read from the environment, not CLI arguments. Never point it at production without authorization; it creates a real trace.

tracing.init(sample_ratio=0.5) enables opt-in head sampling for a provider BotGauge creates; default is record everything, unless OTEL_TRACES_SAMPLER is set, in which case BotGauge says so at startup (see Configuration). With the default sampler and with sample_ratio (both parent-based, as in OpenTelemetry), a request that continues a caller's trace follows the caller's sampling decision (the last two characters of its traceparent): -00 is not recorded, and -01 is recorded whatever sample_ratio says. An OTEL_TRACES_SAMPLER that isn't parent-based, such as always_on or traceidratio, decides on its own. For a service with untrusted callers, see Public edges. After shutdown(), re-initialization may specify the same ratio for that BotGauge-created global provider. A different ratio or an existing customer provider is rejected because its sampler cannot be changed. A head-dropped trace can't be recovered downstream, and policy/authority/verifier evidence must never depend on sampling. Protected string attribute values are capped at 4096 characters after secret sanitization (only the first 5120 characters are inspected, so sanitizer cost stays bounded; the rest is discarded); TTFT/streaming fields are reserved in the attributes contract but not automatically measured by these isolated producers.