struct-sdk 0.2.33__tar.gz → 0.3.1__tar.gz

struct_sdk-0.2.33/README.md → struct_sdk-0.3.1/PKG-INFO

@@ -1,3 +1,103 @@
+Metadata-Version: 2.5
+Name: struct-sdk
+Version: 0.3.1
+Summary: Struct agent observability SDK — auto-instruments AI agent frameworks with OpenTelemetry
+Project-URL: Homepage, https://struct.ai
+Project-URL: Documentation, https://struct.ai/docs
+Project-URL: Issues, https://struct.ai/support
+Author-email: Struct <support@struct.ai>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: agent,ai,anthropic,langchain,observability,openai,opentelemetry,struct,tracing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Requires-Dist: opentelemetry-api>=1.45.1
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27.0
+Requires-Dist: opentelemetry-sdk>=1.27.0
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.30.0; extra == 'anthropic'
+Provides-Extra: auto
+Requires-Dist: opentelemetry-instrumentation-aio-pika; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-aiohttp-client; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-aiohttp-server; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-aiokafka; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-aiopg; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-asyncpg; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-botocore; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-cassandra; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-celery; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-confluent-kafka; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-django; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-falcon; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-fastapi; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-flask; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-grpc; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-httpx; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-jinja2; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-kafka-python; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-logging; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-mysql; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-mysqlclient; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-pika; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-psycopg; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-psycopg2; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-pymemcache; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-pymongo; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-pymssql; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-pymysql; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-pyramid; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-redis; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-requests; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-sqlalchemy; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-sqlite3; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-starlette; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-system-metrics; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-threading; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-tornado; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-tortoiseorm; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-urllib; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation-urllib3; extra == 'auto'
+Requires-Dist: opentelemetry-instrumentation>=0.51b0; extra == 'auto'
+Requires-Dist: opentelemetry-resource-detector-containerid; extra == 'auto'
+Provides-Extra: azure
+Requires-Dist: azure-core-tracing-opentelemetry>=1.0.0b11; extra == 'azure'
+Provides-Extra: claude-agent-sdk
+Requires-Dist: claude-agent-sdk>=0.2.121; extra == 'claude-agent-sdk'
+Requires-Dist: mcp<2,>=1.30.0; extra == 'claude-agent-sdk'
+Provides-Extra: demo
+Requires-Dist: langchain-anthropic>=1.4.6; extra == 'demo'
+Requires-Dist: langchain-core>=1.3.3; extra == 'demo'
+Requires-Dist: langchain-openai>=0.2.0; extra == 'demo'
+Requires-Dist: langchain>=1.3.9; extra == 'demo'
+Requires-Dist: langgraph>=0.2.0; extra == 'demo'
+Requires-Dist: python-dotenv>=1.0.0; extra == 'demo'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
+Requires-Dist: pytest>=9.0.3; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: exceptions
+Requires-Dist: opentelemetry-instrumentation-exceptions; extra == 'exceptions'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=1.3.3; extra == 'langchain'
+Provides-Extra: openai
+Requires-Dist: openai>=1.66.0; extra == 'openai'
+Provides-Extra: structlog
+Requires-Dist: opentelemetry-instrumentation-structlog; extra == 'structlog'
+Provides-Extra: temporal
+Requires-Dist: temporalio>=1.11.0; extra == 'temporal'
+Description-Content-Type: text/markdown
+
 # struct-sdk
 
 OpenTelemetry instrumentation for AI agents in Python. Captures spans,
@@ -63,7 +163,7 @@ async with struct.agent(name="checkout"):
 | `anthropic` | `chat {model}` | Cache-token accounting; streaming chats with tool-use reconstruction. Bedrock and Vertex variants supported if installed. |
 | `openai` (Responses API) | `chat {model}` | Non-streaming `responses.create` on sync and async clients (Azure clients included). Cached-token accounting from `usage.input_tokens_details`. Streaming and `chat.completions` calls pass through untraced. Message-content capture at parity with the Anthropic integration: per-message events (`gen_ai.system/user/assistant/tool.message`) and `gen_ai.choice`, plus `gen_ai.input.messages` / `gen_ai.output.messages` in span-content mode. Reasoning items are skipped (`encrypted_content` is never emitted). |
 | `claude_agent_sdk` | `agent`, `chat`, `execute_tool` | Telemetry comes from Claude Code itself in the subprocess; ingest credentials are propagated to it via `ClaudeAgentOptions`. Subagents inherit the configuration. |
-| `langchain_core` `BaseChatModel` | `chat {model}` | Skipped when an underlying provider SDK is also instrumented (e.g. `ChatAnthropic` + `anthropic` → a single span). |
+| `langchain_core` `BaseChatModel` | `chat {model}` | When the underlying provider SDK is also instrumented (e.g. `ChatAnthropic` + `anthropic`), the provider's span is suppressed, so there is a single span. |
 | `langchain_core` `BaseTool` | `execute_tool {name}` | `tool_call_id` extracted from the LangChain ToolCall when present. |
 | `langchain_core` `BaseRetriever` | `retrieval {name}` | |
 | `langgraph` `Pregel` | `invoke_agent {name}` | Covers `create_react_agent`, `langchain.agents.create_agent`, and custom graphs. Reads conversation id from any of: `configurable.thread_id` (LangGraph canonical), or `metadata.{thread_id, session_id, conversation_id}` (LangSmith conventions). For multi-turn HTTP-style threading, wrap your entry point in [`struct.agent(session_id=conv_id)`](#recommended-pattern-wrap-langchain-entry-points-in-structagent) — that's the struct-native replacement for `ls.tracing_context(parent=run_tree)`. |
@@ -255,8 +355,8 @@ async with struct.agent(name="my-agent"):
 ```
 
 When you do use `ChatAnthropic` *and* have the `anthropic` SDK installed,
-the chat span comes from the Anthropic instrumentation (single span);
-the LangChain layer skips its own to avoid duplicates.
+the chat span comes from the LangChain layer (single span); the Anthropic
+instrumentation skips its own to avoid duplicates.
 
 ## Content capture
 
@@ -268,21 +368,23 @@ from struct_sdk import struct, ContentCaptureMode
 
 struct.init(
     ingest_key=...,
-    content_capture=ContentCaptureMode.EVENT_ONLY,  # default
-    # or ContentCaptureMode.NONE, SPAN_ONLY, SPAN_AND_EVENT
+    content_capture=ContentCaptureMode.EVENT_ONLY,  # opt in; the default is NONE
+    # or ContentCaptureMode.SPAN_ONLY, SPAN_AND_EVENT
 )
 ```
 
-- **`EVENT_ONLY`** (default): per-message content lands on OTel log
+- **`EVENT_ONLY`**: per-message content lands on OTel log
   records (`gen_ai.{user,assistant,system,tool}.message`,
   `gen_ai.choice`). Spans carry metadata only.
 - **`SPAN_ONLY`**: content on span attributes (`gen_ai.input.messages`,
   `gen_ai.output.messages`).
 - **`SPAN_AND_EVENT`**: both.
-- **`NONE`**: no content captured. Token counts, tool call IDs, finish
-  reasons, and other metadata still flow.
+- **`NONE`** (default since 0.3.0): no content captured, including the
+  user prompt on the agent span and tool arguments and results. Token
+  counts, tool call IDs, finish reasons, and other metadata still flow.
 
-`capture_content=False` is a shorthand for `ContentCaptureMode.NONE`.
+`capture_content=False` is a shorthand for `ContentCaptureMode.NONE`, and
+`capture_content=True` for `EVENT_ONLY`.
 
 ## Manual scopes
 
@@ -373,23 +475,175 @@ from `input_tokens`.
 ```python
 struct.init(
     ingest_key="pk-...",                # required
-    service_name="my-agent",            # default: "default-agent"
-    service_version="1.2.3",            # default: "0.0.0"
-    environment="production",           # default: "development"
+    service_name="my-agent",            # default: OTEL_SERVICE_NAME, else "default-agent"
+    service_version="1.2.3",            # default: from OTEL_RESOURCE_ATTRIBUTES, else "0.0.0"
+    environment="production",           # default: from OTEL_RESOURCE_ATTRIBUTES, else "development"
     endpoint="https://ingest.struct.ai", # default; override for self-hosted
     shutdown_timeout_seconds=5.0,        # default: 5.0
-    content_capture=ContentCaptureMode.EVENT_ONLY,
+    content_capture=ContentCaptureMode.EVENT_ONLY,  # default: NONE
+    auto_instrument=True,                # default; False = AI libraries only
+    instrumentation_options=None,        # per-library full-app settings
+    redact_attributes=["*.password"],    # default: STRUCT_REDACT_ATTRIBUTES
+)
+```
+
+With `auto_instrument=False` the SDK uses an isolated `TracerProvider` and
+`LoggerProvider` and instruments only the AI libraries; your existing OTel
+setup is unaffected. The default is [full-app mode](#full-app-mode).
+
+Service identity follows the standard OpenTelemetry variables when you don't
+pass it: `OTEL_SERVICE_NAME`, and `service.version` and
+`deployment.environment` in `OTEL_RESOURCE_ATTRIBUTES`. Arguments to `init()`
+win. The resource also carries host, runtime and (with the `[auto]` extra)
+container metadata, plus the commit when `STRUCT_GIT_COMMIT_SHA` and
+`STRUCT_GIT_REPOSITORY_URL` are set. It includes a `service.instance.id` so
+replicas stay distinguishable; an ID from `OTEL_RESOURCE_ATTRIBUTES` is
+preserved.
+
+In pre-fork servers (for example `gunicorn --preload`), call `struct.init()` in
+each worker (gunicorn's `post_fork` hook), not in the parent: forked workers
+would otherwise share the parent's instance id. A worker that exports after
+being forked from an initialized parent logs one INFO line saying so.
+
+### Redaction
+
+`redact_attributes` takes glob patterns, matched case-insensitively. Span,
+span-event and log attributes whose keys match leave the process as
+`[REDACTED]`, for example `["http.request.header.authorization", "*.password"]`.
+`STRUCT_REDACT_ATTRIBUTES` (comma-separated) sets them without code. Only what
+Struct sends is changed; your own exporters still see the real values.
+Metrics, log bodies and span names are not redacted.
+
+## Full-app mode
+
+Full-app mode is the default since 0.3.0: `struct.init()` adds APM-style
+telemetry for the whole service, like an OpenTelemetry distro: HTTP servers and
+clients, databases, caches, queues, app logs and process metrics, built on the
+OpenTelemetry contrib instrumentors. Every supported library you have installed
+is instrumented; turn individual ones off below. To keep the 0.2 behavior
+(AI libraries only, isolated providers), pass `auto_instrument=False`.
+
+```bash
+pip install "struct-sdk[auto]"           # needs opentelemetry-sdk 1.30+; add [azure] for Azure SDK tracing,
+                                         # [structlog] for structlog (opentelemetry-sdk 1.44+),
+                                         # [exceptions] for uncaught exceptions (1.43+)
+```
+
+```python
+import fastapi
+from struct_sdk import struct
+
+struct.init(ingest_key="pk-...", service_name="checkout-api")
+
+app = fastapi.FastAPI()  # resolve the class after init()
+```
+
+Framework instrumentors replace the framework's class when `init()` runs, so
+an app class bound earlier stays uninstrumented: `from fastapi import FastAPI`
+above `struct.init()` keeps the original class. Import framework classes after
+`init()`, or reference them through the module as above. For an app created
+before `init()`, call the contrib instrumentor directly (for example
+`FastAPIInstrumentor.instrument_app(app)`). In pre-fork servers, run
+`init()` in each worker, as described above.
+
+| Signal | Coverage |
+|---|---|
+| Traces | Django, FastAPI, Flask, Starlette, Tornado, Falcon, Pyramid, aiohttp (client and server), requests, httpx, urllib, urllib3, gRPC, psycopg2, psycopg, aiopg, asyncpg, PyMySQL, MySQL Connector, mysqlclient, pymssql, sqlite3, PyMongo, Cassandra, Redis, pymemcache, Tortoise ORM, Celery, botocore, aiobotocore, Kafka (confluent-kafka, aiokafka, kafka-python), RabbitMQ (pika, aio-pika), Jinja2, Azure SDK. Work handed to threads and `ThreadPoolExecutor` stays in the caller's trace. SQLAlchemy is off by default because its query spans duplicate the database driver's; enable it with `{"sqlalchemy": {"enabled": True}}` if you prefer ORM-level spans. |
+| Logs | Python `logging` records that reach the root logger, with trace context. The SDK's own and OpenTelemetry's records are excluded. With the `[structlog]` extra, structlog events that structlog writes itself (its default) are exported with their fields as attributes; events structlog hands to `logging` (`structlog.stdlib.LoggerFactory`) are exported once, through the `logging` bridge. Extras and structlog fields OpenTelemetry can't take as-is are exported as strings: dicts and mixed-type lists as JSON, everything else (UUIDs, datetimes, `None`, bytes) as its `str()`. Your other handlers still see the original values. With the `[exceptions]` extra, uncaught exceptions (main thread, other threads, asyncio) are exported as log records. If your app configures no logging, its warnings still print to stderr as they would without Struct. This is separate from `content_capture`, which only governs LLM content; disable `{"logging": {"enabled": False}}` and `{"structlog": {"enabled": False}}` (which also stops copies of your logs when Struct attaches to your OpenTelemetry setup), or redact attributes, if application logs can carry sensitive data. |
+| Metrics | Instrumentor metrics (for example `http.server.duration`) and process metrics (`process.cpu.*`, `process.memory.*`, threads, file descriptors, GC). Counters and histograms use delta temporality. |
+
+Each instrumentor activates only when its library is installed.
+`instrumentation_options` disables or configures one by name; other keys are
+passed to that instrumentor:
+
+```python
+struct.init(
+    ingest_key="pk-...",
+    instrumentation_options={
+        "fastapi": {"excluded_urls": "health,ready"},
+        "logging": {"enabled": False},
+    },
+)
+```
+
+As with `opentelemetry-instrument` and the Azure Monitor distro, the standard
+`OTEL_PYTHON_DISABLED_INSTRUMENTATIONS` environment variable also turns
+libraries off (`OTEL_PYTHON_DISABLED_INSTRUMENTATIONS=requests,urllib3`, or
+`*` for all of them). An explicit `instrumentation_options` entry takes
+precedence over it.
+
+Full-app mode installs Struct's providers as the global OpenTelemetry
+providers only when no tracer, meter or logger provider is installed. If the
+process already configured any of them (Azure Monitor, your own SDK setup),
+Struct adds its exporters to your SDK tracer and logger providers and
+instruments nothing: your setup keeps ownership of instrumentation, sampling
+and shutdown, and your metrics are not sent to Struct. Struct's own GenAI
+spans keep their isolated provider either way, so your sampler does not drop
+them.
+
+### Datadog ddtrace
+
+Under `ddtrace-run`, Struct leaves the libraries ddtrace patches to it, and
+`urllib3` beneath `requests` or `botocore`, to avoid duplicate spans and
+conflicting trace headers, and logs one INFO line listing them. Logs, process metrics, thread context, AI spans and libraries
+ddtrace doesn't patch still go to Struct. With `DD_TRACE_OTEL_ENABLED=true`,
+ddtrace's OpenTelemetry provider isn't the OpenTelemetry SDK, so full-app
+mode attaches nothing (an INFO line says so) and only AI spans reach Struct.
+
+### Zero-code activation
+
+```bash
+OTEL_PYTHON_DISTRO=struct \
+STRUCT_INGEST_KEY=pk-... \
+OTEL_SERVICE_NAME=checkout-api \
+opentelemetry-instrument python app.py
+```
+
+`opentelemetry-instrument` comes with `[auto]`. Struct calls `struct.init()`
+before your app starts, with `STRUCT_INGEST_URL` as the endpoint when set.
+Message content stays off; call `struct.init()` in code to turn it on.
+Installing the SDK never changes another distro: Struct's distro is used only
+when `OTEL_PYTHON_DISTRO=struct`. When selected, it also keeps other installed
+configurators (such as `opentelemetry-distro`'s) from installing competing
+providers, unless you set `OTEL_PYTHON_CONFIGURATOR` yourself. If you already run another distro, call
+`struct.init()` in code instead and Struct attaches to its providers.
+
+### Temporal
+
+```bash
+pip install "struct-sdk[temporal]"
+```
+
+```python
+from temporalio.client import Client
+from temporalio.runtime import Runtime
+from struct_sdk import struct, temporal
+
+struct.init(ingest_key="pk-...", service_name="billing-worker")
+runtime = Runtime(telemetry=temporal.telemetry_config(global_tags={"replica": replica_id}))
+client = await Client.connect(
+    "temporal:7233",
+    runtime=runtime,
+    interceptors=[temporal.tracing_interceptor()],
 )
 ```
 
-The SDK uses an isolated `TracerProvider` and `LoggerProvider` — your
-existing OTel setup is unaffected.
+`telemetry_config()` exports Temporal Core metrics (task slots,
+schedule-to-start latency, poll results, sticky cache) to Struct. It keeps
+Core's console logging at Temporal's defaults, except that failed metric
+exports are not printed. `tracing_interceptor()` (temporalio 1.11+) traces
+workflows and activities with Struct's tracer; a failing span processor never
+blocks a Temporal call or replaces its exception.
+Temporal server metrics are a Prometheus endpoint; scrape them with an
+OpenTelemetry Collector and export OTLP/HTTP to your Struct ingest endpoint
+with the `x-struct-ingest-key` header.
 
 ## Reliability
 
 The SDK is designed never to break your application. Instrumentation
-hooks, span exports, and shutdown all swallow exceptions internally; the
-first failure at each site logs at WARN, subsequent ones at DEBUG.
+hooks, span exports, and shutdown all swallow exceptions internally and log
+at DEBUG on the `struct_sdk` logger, with a traceback for the first failure
+at each site.
 Process exit is bounded by `shutdown_timeout_seconds` and runs in a
 background thread, so a slow or unreachable ingest endpoint cannot hang
 shutdown.
@@ -399,13 +653,12 @@ shutdown.
 - **Spans missing after instrumenting:** Call `struct.init()` *before*
   importing the instrumented libraries, so the SDK can wire up
   instrumentation before any instance is constructed.
-- **No log records appearing:** Log records only emit when the capture
-  mode is `EVENT_ONLY` or `SPAN_AND_EVENT` (the default). If you set
-  `capture_content=False`, content events are disabled.
+- **No message log records appearing:** they only emit when the capture
+  mode is `EVENT_ONLY` or `SPAN_AND_EVENT`. The default is `NONE`.
 - **Duplicate chat spans:** When an LLM provider SDK and a wrapping
   framework are both instrumented (e.g. `ChatAnthropic` calling through
-  to `anthropic`), the framework-level chat span is skipped to avoid
-  duplicates.
+  to `anthropic`), the provider-level chat span is skipped and the
+  framework's is kept.
 
 ## License
 

struct_sdk-0.2.33/PKG-INFO → struct_sdk-0.3.1/README.md

@@ -1,52 +1,3 @@
-Metadata-Version: 2.5
-Name: struct-sdk
-Version: 0.2.33
-Summary: Struct agent observability SDK — auto-instruments AI agent frameworks with OpenTelemetry
-Project-URL: Homepage, https://struct.ai
-Project-URL: Documentation, https://struct.ai/docs
-Project-URL: Issues, https://struct.ai/support
-Author-email: Struct <support@struct.ai>
-License: Apache-2.0
-License-File: LICENSE
-Keywords: agent,ai,anthropic,langchain,observability,openai,opentelemetry,struct,tracing
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-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: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Topic :: System :: Monitoring
-Requires-Python: >=3.10
-Requires-Dist: opentelemetry-api>=1.45.1
-Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27.0
-Requires-Dist: opentelemetry-sdk>=1.27.0
-Provides-Extra: anthropic
-Requires-Dist: anthropic>=0.30.0; extra == 'anthropic'
-Provides-Extra: claude-agent-sdk
-Requires-Dist: claude-agent-sdk>=0.2.121; extra == 'claude-agent-sdk'
-Requires-Dist: mcp<2,>=1.30.0; extra == 'claude-agent-sdk'
-Provides-Extra: demo
-Requires-Dist: langchain-anthropic>=1.4.6; extra == 'demo'
-Requires-Dist: langchain-core>=1.3.3; extra == 'demo'
-Requires-Dist: langchain-openai>=0.2.0; extra == 'demo'
-Requires-Dist: langchain>=1.3.9; extra == 'demo'
-Requires-Dist: langgraph>=0.2.0; extra == 'demo'
-Requires-Dist: python-dotenv>=1.0.0; extra == 'demo'
-Provides-Extra: dev
-Requires-Dist: mypy>=1.10; extra == 'dev'
-Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
-Requires-Dist: pytest>=9.0.3; extra == 'dev'
-Requires-Dist: ruff>=0.5; extra == 'dev'
-Provides-Extra: langchain
-Requires-Dist: langchain-core>=1.3.3; extra == 'langchain'
-Provides-Extra: openai
-Requires-Dist: openai>=1.66.0; extra == 'openai'
-Description-Content-Type: text/markdown
-
 # struct-sdk
 
 OpenTelemetry instrumentation for AI agents in Python. Captures spans,
@@ -112,7 +63,7 @@ async with struct.agent(name="checkout"):
 | `anthropic` | `chat {model}` | Cache-token accounting; streaming chats with tool-use reconstruction. Bedrock and Vertex variants supported if installed. |
 | `openai` (Responses API) | `chat {model}` | Non-streaming `responses.create` on sync and async clients (Azure clients included). Cached-token accounting from `usage.input_tokens_details`. Streaming and `chat.completions` calls pass through untraced. Message-content capture at parity with the Anthropic integration: per-message events (`gen_ai.system/user/assistant/tool.message`) and `gen_ai.choice`, plus `gen_ai.input.messages` / `gen_ai.output.messages` in span-content mode. Reasoning items are skipped (`encrypted_content` is never emitted). |
 | `claude_agent_sdk` | `agent`, `chat`, `execute_tool` | Telemetry comes from Claude Code itself in the subprocess; ingest credentials are propagated to it via `ClaudeAgentOptions`. Subagents inherit the configuration. |
-| `langchain_core` `BaseChatModel` | `chat {model}` | Skipped when an underlying provider SDK is also instrumented (e.g. `ChatAnthropic` + `anthropic` → a single span). |
+| `langchain_core` `BaseChatModel` | `chat {model}` | When the underlying provider SDK is also instrumented (e.g. `ChatAnthropic` + `anthropic`), the provider's span is suppressed, so there is a single span. |
 | `langchain_core` `BaseTool` | `execute_tool {name}` | `tool_call_id` extracted from the LangChain ToolCall when present. |
 | `langchain_core` `BaseRetriever` | `retrieval {name}` | |
 | `langgraph` `Pregel` | `invoke_agent {name}` | Covers `create_react_agent`, `langchain.agents.create_agent`, and custom graphs. Reads conversation id from any of: `configurable.thread_id` (LangGraph canonical), or `metadata.{thread_id, session_id, conversation_id}` (LangSmith conventions). For multi-turn HTTP-style threading, wrap your entry point in [`struct.agent(session_id=conv_id)`](#recommended-pattern-wrap-langchain-entry-points-in-structagent) — that's the struct-native replacement for `ls.tracing_context(parent=run_tree)`. |
@@ -304,8 +255,8 @@ async with struct.agent(name="my-agent"):
 ```
 
 When you do use `ChatAnthropic` *and* have the `anthropic` SDK installed,
-the chat span comes from the Anthropic instrumentation (single span);
-the LangChain layer skips its own to avoid duplicates.
+the chat span comes from the LangChain layer (single span); the Anthropic
+instrumentation skips its own to avoid duplicates.
 
 ## Content capture
 
@@ -317,21 +268,23 @@ from struct_sdk import struct, ContentCaptureMode
 
 struct.init(
     ingest_key=...,
-    content_capture=ContentCaptureMode.EVENT_ONLY,  # default
-    # or ContentCaptureMode.NONE, SPAN_ONLY, SPAN_AND_EVENT
+    content_capture=ContentCaptureMode.EVENT_ONLY,  # opt in; the default is NONE
+    # or ContentCaptureMode.SPAN_ONLY, SPAN_AND_EVENT
 )
 ```
 
-- **`EVENT_ONLY`** (default): per-message content lands on OTel log
+- **`EVENT_ONLY`**: per-message content lands on OTel log
   records (`gen_ai.{user,assistant,system,tool}.message`,
   `gen_ai.choice`). Spans carry metadata only.
 - **`SPAN_ONLY`**: content on span attributes (`gen_ai.input.messages`,
   `gen_ai.output.messages`).
 - **`SPAN_AND_EVENT`**: both.
-- **`NONE`**: no content captured. Token counts, tool call IDs, finish
-  reasons, and other metadata still flow.
+- **`NONE`** (default since 0.3.0): no content captured, including the
+  user prompt on the agent span and tool arguments and results. Token
+  counts, tool call IDs, finish reasons, and other metadata still flow.
 
-`capture_content=False` is a shorthand for `ContentCaptureMode.NONE`.
+`capture_content=False` is a shorthand for `ContentCaptureMode.NONE`, and
+`capture_content=True` for `EVENT_ONLY`.
 
 ## Manual scopes
 
@@ -422,23 +375,175 @@ from `input_tokens`.
 ```python
 struct.init(
     ingest_key="pk-...",                # required
-    service_name="my-agent",            # default: "default-agent"
-    service_version="1.2.3",            # default: "0.0.0"
-    environment="production",           # default: "development"
+    service_name="my-agent",            # default: OTEL_SERVICE_NAME, else "default-agent"
+    service_version="1.2.3",            # default: from OTEL_RESOURCE_ATTRIBUTES, else "0.0.0"
+    environment="production",           # default: from OTEL_RESOURCE_ATTRIBUTES, else "development"
     endpoint="https://ingest.struct.ai", # default; override for self-hosted
     shutdown_timeout_seconds=5.0,        # default: 5.0
-    content_capture=ContentCaptureMode.EVENT_ONLY,
+    content_capture=ContentCaptureMode.EVENT_ONLY,  # default: NONE
+    auto_instrument=True,                # default; False = AI libraries only
+    instrumentation_options=None,        # per-library full-app settings
+    redact_attributes=["*.password"],    # default: STRUCT_REDACT_ATTRIBUTES
+)
+```
+
+With `auto_instrument=False` the SDK uses an isolated `TracerProvider` and
+`LoggerProvider` and instruments only the AI libraries; your existing OTel
+setup is unaffected. The default is [full-app mode](#full-app-mode).
+
+Service identity follows the standard OpenTelemetry variables when you don't
+pass it: `OTEL_SERVICE_NAME`, and `service.version` and
+`deployment.environment` in `OTEL_RESOURCE_ATTRIBUTES`. Arguments to `init()`
+win. The resource also carries host, runtime and (with the `[auto]` extra)
+container metadata, plus the commit when `STRUCT_GIT_COMMIT_SHA` and
+`STRUCT_GIT_REPOSITORY_URL` are set. It includes a `service.instance.id` so
+replicas stay distinguishable; an ID from `OTEL_RESOURCE_ATTRIBUTES` is
+preserved.
+
+In pre-fork servers (for example `gunicorn --preload`), call `struct.init()` in
+each worker (gunicorn's `post_fork` hook), not in the parent: forked workers
+would otherwise share the parent's instance id. A worker that exports after
+being forked from an initialized parent logs one INFO line saying so.
+
+### Redaction
+
+`redact_attributes` takes glob patterns, matched case-insensitively. Span,
+span-event and log attributes whose keys match leave the process as
+`[REDACTED]`, for example `["http.request.header.authorization", "*.password"]`.
+`STRUCT_REDACT_ATTRIBUTES` (comma-separated) sets them without code. Only what
+Struct sends is changed; your own exporters still see the real values.
+Metrics, log bodies and span names are not redacted.
+
+## Full-app mode
+
+Full-app mode is the default since 0.3.0: `struct.init()` adds APM-style
+telemetry for the whole service, like an OpenTelemetry distro: HTTP servers and
+clients, databases, caches, queues, app logs and process metrics, built on the
+OpenTelemetry contrib instrumentors. Every supported library you have installed
+is instrumented; turn individual ones off below. To keep the 0.2 behavior
+(AI libraries only, isolated providers), pass `auto_instrument=False`.
+
+```bash
+pip install "struct-sdk[auto]"           # needs opentelemetry-sdk 1.30+; add [azure] for Azure SDK tracing,
+                                         # [structlog] for structlog (opentelemetry-sdk 1.44+),
+                                         # [exceptions] for uncaught exceptions (1.43+)
+```
+
+```python
+import fastapi
+from struct_sdk import struct
+
+struct.init(ingest_key="pk-...", service_name="checkout-api")
+
+app = fastapi.FastAPI()  # resolve the class after init()
+```
+
+Framework instrumentors replace the framework's class when `init()` runs, so
+an app class bound earlier stays uninstrumented: `from fastapi import FastAPI`
+above `struct.init()` keeps the original class. Import framework classes after
+`init()`, or reference them through the module as above. For an app created
+before `init()`, call the contrib instrumentor directly (for example
+`FastAPIInstrumentor.instrument_app(app)`). In pre-fork servers, run
+`init()` in each worker, as described above.
+
+| Signal | Coverage |
+|---|---|
+| Traces | Django, FastAPI, Flask, Starlette, Tornado, Falcon, Pyramid, aiohttp (client and server), requests, httpx, urllib, urllib3, gRPC, psycopg2, psycopg, aiopg, asyncpg, PyMySQL, MySQL Connector, mysqlclient, pymssql, sqlite3, PyMongo, Cassandra, Redis, pymemcache, Tortoise ORM, Celery, botocore, aiobotocore, Kafka (confluent-kafka, aiokafka, kafka-python), RabbitMQ (pika, aio-pika), Jinja2, Azure SDK. Work handed to threads and `ThreadPoolExecutor` stays in the caller's trace. SQLAlchemy is off by default because its query spans duplicate the database driver's; enable it with `{"sqlalchemy": {"enabled": True}}` if you prefer ORM-level spans. |
+| Logs | Python `logging` records that reach the root logger, with trace context. The SDK's own and OpenTelemetry's records are excluded. With the `[structlog]` extra, structlog events that structlog writes itself (its default) are exported with their fields as attributes; events structlog hands to `logging` (`structlog.stdlib.LoggerFactory`) are exported once, through the `logging` bridge. Extras and structlog fields OpenTelemetry can't take as-is are exported as strings: dicts and mixed-type lists as JSON, everything else (UUIDs, datetimes, `None`, bytes) as its `str()`. Your other handlers still see the original values. With the `[exceptions]` extra, uncaught exceptions (main thread, other threads, asyncio) are exported as log records. If your app configures no logging, its warnings still print to stderr as they would without Struct. This is separate from `content_capture`, which only governs LLM content; disable `{"logging": {"enabled": False}}` and `{"structlog": {"enabled": False}}` (which also stops copies of your logs when Struct attaches to your OpenTelemetry setup), or redact attributes, if application logs can carry sensitive data. |
+| Metrics | Instrumentor metrics (for example `http.server.duration`) and process metrics (`process.cpu.*`, `process.memory.*`, threads, file descriptors, GC). Counters and histograms use delta temporality. |
+
+Each instrumentor activates only when its library is installed.
+`instrumentation_options` disables or configures one by name; other keys are
+passed to that instrumentor:
+
+```python
+struct.init(
+    ingest_key="pk-...",
+    instrumentation_options={
+        "fastapi": {"excluded_urls": "health,ready"},
+        "logging": {"enabled": False},
+    },
+)
+```
+
+As with `opentelemetry-instrument` and the Azure Monitor distro, the standard
+`OTEL_PYTHON_DISABLED_INSTRUMENTATIONS` environment variable also turns
+libraries off (`OTEL_PYTHON_DISABLED_INSTRUMENTATIONS=requests,urllib3`, or
+`*` for all of them). An explicit `instrumentation_options` entry takes
+precedence over it.
+
+Full-app mode installs Struct's providers as the global OpenTelemetry
+providers only when no tracer, meter or logger provider is installed. If the
+process already configured any of them (Azure Monitor, your own SDK setup),
+Struct adds its exporters to your SDK tracer and logger providers and
+instruments nothing: your setup keeps ownership of instrumentation, sampling
+and shutdown, and your metrics are not sent to Struct. Struct's own GenAI
+spans keep their isolated provider either way, so your sampler does not drop
+them.
+
+### Datadog ddtrace
+
+Under `ddtrace-run`, Struct leaves the libraries ddtrace patches to it, and
+`urllib3` beneath `requests` or `botocore`, to avoid duplicate spans and
+conflicting trace headers, and logs one INFO line listing them. Logs, process metrics, thread context, AI spans and libraries
+ddtrace doesn't patch still go to Struct. With `DD_TRACE_OTEL_ENABLED=true`,
+ddtrace's OpenTelemetry provider isn't the OpenTelemetry SDK, so full-app
+mode attaches nothing (an INFO line says so) and only AI spans reach Struct.
+
+### Zero-code activation
+
+```bash
+OTEL_PYTHON_DISTRO=struct \
+STRUCT_INGEST_KEY=pk-... \
+OTEL_SERVICE_NAME=checkout-api \
+opentelemetry-instrument python app.py
+```
+
+`opentelemetry-instrument` comes with `[auto]`. Struct calls `struct.init()`
+before your app starts, with `STRUCT_INGEST_URL` as the endpoint when set.
+Message content stays off; call `struct.init()` in code to turn it on.
+Installing the SDK never changes another distro: Struct's distro is used only
+when `OTEL_PYTHON_DISTRO=struct`. When selected, it also keeps other installed
+configurators (such as `opentelemetry-distro`'s) from installing competing
+providers, unless you set `OTEL_PYTHON_CONFIGURATOR` yourself. If you already run another distro, call
+`struct.init()` in code instead and Struct attaches to its providers.
+
+### Temporal
+
+```bash
+pip install "struct-sdk[temporal]"
+```
+
+```python
+from temporalio.client import Client
+from temporalio.runtime import Runtime
+from struct_sdk import struct, temporal
+
+struct.init(ingest_key="pk-...", service_name="billing-worker")
+runtime = Runtime(telemetry=temporal.telemetry_config(global_tags={"replica": replica_id}))
+client = await Client.connect(
+    "temporal:7233",
+    runtime=runtime,
+    interceptors=[temporal.tracing_interceptor()],
 )
 ```
 
-The SDK uses an isolated `TracerProvider` and `LoggerProvider` — your
-existing OTel setup is unaffected.
+`telemetry_config()` exports Temporal Core metrics (task slots,
+schedule-to-start latency, poll results, sticky cache) to Struct. It keeps
+Core's console logging at Temporal's defaults, except that failed metric
+exports are not printed. `tracing_interceptor()` (temporalio 1.11+) traces
+workflows and activities with Struct's tracer; a failing span processor never
+blocks a Temporal call or replaces its exception.
+Temporal server metrics are a Prometheus endpoint; scrape them with an
+OpenTelemetry Collector and export OTLP/HTTP to your Struct ingest endpoint
+with the `x-struct-ingest-key` header.
 
 ## Reliability
 
 The SDK is designed never to break your application. Instrumentation
-hooks, span exports, and shutdown all swallow exceptions internally; the
-first failure at each site logs at WARN, subsequent ones at DEBUG.
+hooks, span exports, and shutdown all swallow exceptions internally and log
+at DEBUG on the `struct_sdk` logger, with a traceback for the first failure
+at each site.
 Process exit is bounded by `shutdown_timeout_seconds` and runs in a
 background thread, so a slow or unreachable ingest endpoint cannot hang
 shutdown.
@@ -448,13 +553,12 @@ shutdown.
 - **Spans missing after instrumenting:** Call `struct.init()` *before*
   importing the instrumented libraries, so the SDK can wire up
   instrumentation before any instance is constructed.
-- **No log records appearing:** Log records only emit when the capture
-  mode is `EVENT_ONLY` or `SPAN_AND_EVENT` (the default). If you set
-  `capture_content=False`, content events are disabled.
+- **No message log records appearing:** they only emit when the capture
+  mode is `EVENT_ONLY` or `SPAN_AND_EVENT`. The default is `NONE`.
 - **Duplicate chat spans:** When an LLM provider SDK and a wrapping
   framework are both instrumented (e.g. `ChatAnthropic` calling through
-  to `anthropic`), the framework-level chat span is skipped to avoid
-  duplicates.
+  to `anthropic`), the provider-level chat span is skipped and the
+  framework's is kept.
 
 ## License