botgauge-tracing 0.1.0__tar.gz

botgauge_tracing-0.1.0/LICENSE

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 BotGauge AI Inc.
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

botgauge_tracing-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+# The sdist carries the package source only. Tests live in the repository; their fixtures are not
+# packaged, so shipping the test files would ship tests that cannot run.
+prune tests

botgauge_tracing-0.1.0/PKG-INFO

@@ -0,0 +1,457 @@
+Metadata-Version: 2.4
+Name: botgauge-tracing
+Version: 0.1.0
+Summary: BotGauge captures AI-agent traces safely and privately without slowing the customer's application. Manual SDK tracing, zero-code instrumentation, and distributed trace propagation, built on OpenTelemetry.
+Author-email: "BotGauge AI Inc." <support@botgauge.com>
+License-Expression: FSL-1.1-ALv2
+Project-URL: Homepage, https://www.botgauge.com/
+Keywords: opentelemetry,otel,tracing,observability,llm,llm-observability,ai-agents,agents,langchain,openai,crewai,monitoring
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Framework :: OpenTelemetry
+Classifier: Framework :: OpenTelemetry :: Distros
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: botgauge-cli==0.1.0
+Requires-Dist: opentelemetry-api>=1.26
+Requires-Dist: opentelemetry-sdk>=1.26
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.26
+Provides-Extra: openai
+Requires-Dist: openinference-instrumentation-openai==0.1.65; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: openinference-instrumentation-anthropic==3.0.3; extra == "anthropic"
+Provides-Extra: langchain
+Requires-Dist: openinference-instrumentation-langchain==0.1.79; extra == "langchain"
+Provides-Extra: langgraph
+Requires-Dist: openinference-instrumentation-langchain==0.1.79; extra == "langgraph"
+Provides-Extra: crewai
+Requires-Dist: openinference-instrumentation-crewai==1.1.21; extra == "crewai"
+Requires-Dist: openinference-instrumentation-openai==0.1.65; extra == "crewai"
+Provides-Extra: llamaindex
+Requires-Dist: openinference-instrumentation-llama-index==4.6.0; extra == "llamaindex"
+Provides-Extra: google-adk
+Requires-Dist: openinference-instrumentation-google-adk==1.0.4; extra == "google-adk"
+Provides-Extra: openai-agents
+Requires-Dist: openinference-instrumentation-openai-agents==2.5.3; extra == "openai-agents"
+Provides-Extra: autogen-agentchat
+Requires-Dist: openinference-instrumentation-autogen-agentchat==0.1.22; extra == "autogen-agentchat"
+Provides-Extra: pydantic-ai
+Requires-Dist: openinference-instrumentation-pydantic-ai==0.1.30; extra == "pydantic-ai"
+Provides-Extra: mcp
+Requires-Dist: openinference-instrumentation-mcp==2.0.13; extra == "mcp"
+Provides-Extra: distributed
+Requires-Dist: opentelemetry-instrumentation-requests>=0.40b0; extra == "distributed"
+Requires-Dist: opentelemetry-instrumentation-httpx>=0.40b0; extra == "distributed"
+Requires-Dist: opentelemetry-instrumentation-urllib3>=0.40b0; extra == "distributed"
+Requires-Dist: opentelemetry-instrumentation-asgi>=0.40b0; extra == "distributed"
+Requires-Dist: opentelemetry-instrumentation-wsgi>=0.40b0; extra == "distributed"
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.40b0; extra == "distributed"
+Requires-Dist: opentelemetry-instrumentation-starlette>=0.40b0; extra == "distributed"
+Requires-Dist: opentelemetry-instrumentation-flask>=0.40b0; extra == "distributed"
+Requires-Dist: opentelemetry-instrumentation-django>=0.40b0; extra == "distributed"
+Requires-Dist: opentelemetry-instrumentation-grpc>=0.40b0; extra == "distributed"
+Provides-Extra: frameworks
+Requires-Dist: botgauge-tracing[anthropic,autogen-agentchat,crewai,distributed,google-adk,langchain,llamaindex,mcp,openai,openai-agents,pydantic-ai]; extra == "frameworks"
+Dynamic: license-file
+
+# botgauge-tracing
+
+**Status: early release (0.x). Public API shapes may still change before 1.0. Every framework in
+`producer_compat.v1.json` has a pinned, isolated certification test; combined or overlapping
+producer profiles are not verified.**
+
+> BotGauge captures AI-agent traces safely and privately without slowing the customer's
+> application.
+
+This is the `botgauge-tracing` distribution, the BotGauge tracing SDK, built
+on stock OpenTelemetry (`opentelemetry-api`/`-sdk`/`-exporter-otlp-proto-http`; the only BotGauge
+dependency is `botgauge-cli`, which provides the command). Customers install it through the `botgauge` meta-package
+(`pip install botgauge`, extras forwarded: `pip install "botgauge[langchain]"`) and import it as
+`from botgauge import tracing`; `botgauge` is a PEP 420 namespace that other BotGauge packages
+join. Its commands (`instrument`, `doctor`, `probe`, `setup`) run
+through the `botgauge` command, which belongs to `botgauge-cli` (a standard-library-only dependency);
+apart from that it depends only on OpenTelemetry.
+
+## What works today
+
+### Manual SDK tracing
+
+```python
+from botgauge import tracing
+
+tracing.init(api_key="...")  # or set BOTGAUGE_API_KEY and call tracing.init()
+
+with tracing.turn(session_id="ses_123"):
+    with tracing.agent("billing-agent"):
+        tracer = tracing.get_tracer()
+        with tracer.start_as_current_span("check_balance"):
+            ...
+
+tracing.flush()
+tracing.shutdown()
+```
+
+**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.
+
+`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.
+
+- One real OTel engine — no custom span class, no custom ID minting, no custom OTLP encoder.
+- Never blocks the calling thread: spans export through a `BatchSpanProcessor`, off-thread.
+- `tracing.agent()`/`tracing.turn()` stamp the frozen, dotted attribute names (see
+  `src/botgauge/tracing/_attributes.py`) onto every span created inside them.
+- Attaches to an existing `TracerProvider` (bring-your-own-OTel) rather than replacing it, and
+  never creates a second one if one is already active.
+- `flush()`/`shutdown()` enforce a hard deadline — a stuck exporter can't hang your process.
+- A FULL/SKELETON/DROP topology filter keeps generic infrastructure spans (HTTP transport,
+  database calls) out of your trace by default, bridging only what's structurally necessary to
+  connect Agent→Agent hops (`BOTGAUGE_TRACE_SCOPE=all` to see everything).
+- Privacy: `capture="metadata"|"text"|"full"` and `redacted=True|False`.
+  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.
+- With a customer `ConcurrentMultiSpanProcessor`, BotGauge runs its own start callbacks
+  through a caller-context bridge, preserving Agent/Revision/Session/Turn identity and the
+  customer's existing processor chain. The bridge is restored on shutdown; `doctor` reports
+  whether it is active.
+- Zero BotGauge baggage, ever. Standard W3C trace-context propagation only — your own propagator
+  and baggage are never touched or replaced.
+
+### Zero-code instrumentation
+
+```bash
+pip install "botgauge[langchain]"  # install only the producer you need
+export BOTGAUGE_API_KEY="..."
+# export BOTGAUGE_ENDPOINT="https://your-collector/v1/traces"  # only for a collector other than BotGauge's
+botgauge instrument python your_app.py
+```
+
+`botg` is a short alias for `botgauge` (`botg instrument python your_app.py`); `botgauge help` lists every
+command the installed BotGauge packages provide.
+
+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).
+
+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:
+
+```bash
+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.
+
+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.
+
+```bash
+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.
+
+`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](#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](#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.
+
+### Explicit ingest diagnostic
+
+```bash
+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.
+
+## Configuration
+
+### BotGauge environment variables
+
+Arguments to `tracing.init()` win over these. "Both" means `tracing.init()` and
+`botgauge instrument`; "instrument" means only the zero-code launcher reads it (with `init()`, use
+the matching argument).
+
+| Variable | Read by | Default | Effect |
+|---|---|---|---|
+| `BOTGAUGE_API_KEY` | Both | unset | Your BotGauge key, sent only as `Authorization: Bearer <key>`. The one setting you need |
+| `BOTGAUGE_ENDPOINT` | Both | `https://api.botgauge.com/v1/traces` when a key is set | Full OTLP/HTTP traces URL of the collector to send to |
+| `BOTGAUGE_CAPTURE` | instrument | `text` | `metadata`, `text` or `full`; see the privacy notes above |
+| `BOTGAUGE_REDACTED` | instrument | `true` | `false` exports the selected content without masking |
+| `BOTGAUGE_CAPTURE_ALLOW_KEYS` | Both | empty | Comma-separated extra attribute keys to keep, globs allowed (`app.tenant_tier,myco.*`); merged with `capture_allow_keys=` |
+| `BOTGAUGE_TRACE_SCOPE` | Both | filtered | `all` exports infrastructure spans (HTTP, database) in full instead of filtering them |
+| `BOTGAUGE_STRICT` | instrument | off | `1` stops the app from starting on instrumentation problems (same as `--strict`) |
+| `BOTGAUGE_VERIFIED_ONLY` | instrument | off | `1` traces only framework versions BotGauge verified |
+| `BOTGAUGE_PRODUCER_OWNER` | instrument | empty | `langchain=customer` (comma-separated) leaves a framework you already instrument to you |
+| `BOTGAUGE_ALLOW_INSECURE_HTTP` | Both | `false` | `true` allows sending the key to a remote `http://` endpoint. Local addresses need no opt-in |
+| `BOTGAUGE_CONSOLE_EXPORT` | Both | off | `1` prints spans to stdout when no key or endpoint is set. Local development only |
+
+### OpenTelemetry environment variables
+
+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.
+
+| Variable | Effect on BotGauge |
+|---|---|
+| `OTEL_SDK_DISABLED=true` | **Turns tracing off.** No spans are recorded or exported, with or without your own provider. Use it to disable BotGauge in tests or one environment without changing code |
+| `OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES` | Added to the exported resource when BotGauge creates the provider |
+| `OTEL_TRACES_SAMPLER`, `OTEL_TRACES_SAMPLER_ARG` | Apply when BotGauge creates the provider and `sample_ratio=` is not given. A sampler set for another tool therefore samples BotGauge's traces too; BotGauge prints a one-time warning at startup when it will drop traces, and `botgauge doctor` shows the active sampler. Pass `sample_ratio=1.0` to record everything regardless |
+| `OTEL_BSP_SCHEDULE_DELAY`, `OTEL_BSP_MAX_QUEUE_SIZE`, `OTEL_BSP_MAX_EXPORT_BATCH_SIZE`, `OTEL_BSP_EXPORT_TIMEOUT` | Tune the batching of BotGauge's own export. An unusable value is logged once on the `botgauge` logger and OpenTelemetry's default is used |
+| `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` and the other span limit variables | Apply when BotGauge creates the provider. Protected string values are already capped at 4096 characters |
+| `OTEL_PROPAGATORS` | Which headers carry trace context between services. BotGauge never replaces your propagator. For a service with untrusted callers, see [Public edges](#public-edges). The values for this and the sampler variables are in [OpenTelemetry's SDK configuration](https://opentelemetry.io/docs/languages/sdk-configuration/general/) |
+| `OTEL_EXPORTER_OTLP_*` | **Ignored** by BotGauge's exporter. They stay with your own exporters, which never receive the BotGauge key |
+
+### Logs
+
+BotGauge reports problems (a rejected key, an invalid setting, an untraced framework) as warnings on
+the standard Python logger named `botgauge`. Route or silence them like any other logger, for
+example `logging.getLogger("botgauge").setLevel(logging.ERROR)`. For a full picture of what is
+active, run `botgauge doctor`, or call `tracing.doctor.report()` inside your app.
+
+## Public edges
+
+If your application accepts requests from an untrusted or public caller, that caller's own
+`traceparent` header should not be trusted as the real parent span — an attacker could otherwise
+inject an arbitrary trace/span ID with no authority consequences intended.
+
+**If the service runs server or MCP instrumentation, turn off incoming trace context for the
+whole process.** That includes `botgauge instrument` and any web framework instrumentation you add
+(Flask, Django, FastAPI and other ASGI/WSGI servers, gRPC). These start the request's span from the
+caller's `traceparent`, and the MCP instrumentation from a request's `_meta` field, over stdio as
+well as HTTP, before your code runs. So the caller decides:
+
+- the trace ID of everything the request records;
+- whether the request is recorded at all: with OpenTelemetry's default sampler, a `traceparent`
+  ending in `-00` turns recording off for the whole request, and `-01` turns it on whatever
+  `sample_ratio` says.
+
+`extract_context()` (below) can't undo this, because the caller's context is already current when
+it runs. Turn incoming trace context off instead:
+
+- `OTEL_PROPAGATORS=none`, on OpenTelemetry 1.33 or newer. Older versions don't accept `none` and
+  stop at startup with "Propagator none not found".
+- On any version, once at startup:
+  ```python
+  from opentelemetry.propagate import set_global_textmap
+  from opentelemetry.propagators.composite import CompositePropagator
+
+  set_global_textmap(CompositePropagator([]))
+  ```
+
+Both also stop the service sending trace context to the services it calls, so use them only in
+processes that face untrusted callers. For HTTP only, removing `traceparent`, `tracestate` and
+`baggage` from incoming requests in middleware that runs before the instrumentation also works.
+
+**Without server or MCP instrumentation**, where your code reads the headers itself, extract
+context at that specific boundary (e.g. one public-facing route, not your whole process) with
+`trust_incoming_context=False`:
+
+```python
+from botgauge import tracing
+
+ctx, link = tracing.extract_context(request.headers, trust_incoming_context=False)
+tracer = tracing.get_tracer()
+with tracer.start_as_current_span("handle_request", context=ctx, links=[link] if link else []):
+    ...
+```
+
+With `trust_incoming_context=False`, `extract_context()` retains the current local context for parenting
+and returns a link to a valid incoming span. The example attaches that link with
+`botgauge.link.relation="continuation"`; the untrusted claim is not used as the parent. A new
+trace starts only when no valid local parent is active. Internal/trusted service-to-service
+hops should keep the default (`trust_incoming_context=True`), which is what most calls need.
+
+## Known limits
+
+- Each framework is verified on its own, at the exact versions the getting-started guide lists.
+  Combined or overlapping producer profiles are not verified.
+- A direct OpenAI + Anthropic mixed-producer test covers shared turn context and
+  duplicate/ownership handling. With LangChain and direct OpenAI both active, explicit ownership
+  emits one LLM span; activating both producers emits two sibling LLM spans on the same client.
+- PydanticAI 1.25.1 needs OpenTelemetry 1.39.1 in an isolated environment, so it is not part of
+  the compatible multi-extra set.
+- A nightly job tests the latest framework versions; a passing drift test never expands the
+  pinned compatibility registry by itself.