agent-observability-trace 0.1.0__tar.gz

agent_observability_trace-0.1.0/.gitignore

@@ -0,0 +1,64 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# uv
+.uv/
+
+# Testing and coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.sarif
+
+# Benchmarks output
+.benchmarks/
+benchmarks/results/latest.json
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Secrets and local config
+.env
+.env.*
+*.pem
+*.key
+
+# agent-trace runtime data — fixture files contain API keys and prompt content
+.agent-trace/
+*.db
+fixture.db
+
+# Docs build
+docs/_build/
+docs/site/
+
+# Pre-commit
+.pre-commit-config.yaml.bak

agent_observability_trace-0.1.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to agent-trace are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+### Added
+- gRPC transport interception (`pip install agent-trace[grpc]`) for LLM SDKs
+  that default to gRPC instead of REST (e.g. Vertex AI's mTLS-authenticated
+  path). Records/replays unary-unary and unary-stream gRPC calls the same
+  way `RecordingTransport`/`ReplayTransport` do for httpx; wired into
+  `Tracer._install_recording_transport`/`_uninstall_recording_transport` and
+  the replay engine alongside the existing httpx/requests patches. Covers
+  both sync `grpc` and async `grpc.aio` (unary-unary only for aio).
+- HTTP transport interception for `aiohttp.ClientSession` (`pip install agent-trace[aiohttp]`), closing a silent recording gap for LLM traffic routed through aiohttp-based clients (e.g. LiteLLM's default async transport)
+
+## [0.1.0] - 2026-06-19
+
+### Added
+- Core span and trace data model (`Span`, `Trace`, `SpanStatus`)
+- Clock abstraction (`core/clock.py`) enabling deterministic replay
+- HTTP transport interception for `httpx` and `requests`
+- SQLite-backed fixture store (`replay/fixture.py`) for record/replay
+- Replay engine with `AGENT_TRACE_NETWORK_GUARD` enforcement
+- `@tracer.instrument(record=True)` decorator API
+- `tracer.span()` context manager for manual span creation
+- LangGraph callback handler integration (`pip install agent-trace[langgraph]`)
+- OpenAI Agents SDK hook integration (`pip install agent-trace[openai-agents]`)
+- OTLP exporter for Jaeger/Grafana Tempo (`pip install agent-trace[otlp]`)
+- `stdout` and `file` exporters
+- Three benchmark scripts: overhead, fidelity, ingestion
+- CI pipeline with ruff, mypy --strict, pytest, Trivy, OpenSSF Scorecard
+- Apache 2.0 license

agent_observability_trace-0.1.0/LICENSE

@@ -0,0 +1,198 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or designated in writing by the copyright owner as "Not a
+      Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and incorporated
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within
+          the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the
+          Derivative Works, if and wherever such third-party notices
+          normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License.
+          You may add Your own attribution notices within Derivative
+          Works that You distribute, alongside or as an addendum to
+          the NOTICE text from the Work, provided that such additional
+          attribution notices cannot be construed as modifying the
+          License.
+
+      You may add Your own license statement for Your modifications and
+      may provide additional grant of rights to use, copy, modify, merge,
+      publish, distribute, sublicense, and/or sell copies of the
+      Contribution, either on an unchanged basis, or on the basis of
+      derivatives of it, solely to the extent these changes are necessary
+      to conform to other license requirements applicable to those
+      derivatives.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or reproducing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format in question. It is also
+      recommended that a file or directory name and a description of the
+      purpose of the file be included on the same "PRINT" or "on the
+      first page" of each appropriate file.
+
+   Copyright 2026 Rudrendu Paul and Sourav Nandy
+
+   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.

agent_observability_trace-0.1.0/PKG-INFO

@@ -0,0 +1,362 @@
+Metadata-Version: 2.4
+Name: agent-observability-trace
+Version: 0.1.0
+Summary: AI agent observability with deterministic record/replay — capture any LangGraph or OpenAI Agents SDK run, replay it offline at zero API cost.
+Project-URL: Homepage, https://github.com/RudrenduPaul/agent-observability
+Project-URL: Documentation, https://github.com/RudrenduPaul/agent-observability/blob/main/docs/getting-started.md
+Project-URL: Repository, https://github.com/RudrenduPaul/agent-observability
+Project-URL: Bug Tracker, https://github.com/RudrenduPaul/agent-observability/issues
+Project-URL: Changelog, https://github.com/RudrenduPaul/agent-observability/blob/main/CHANGELOG.md
+Author: Sourav Nandy
+Author-email: Rudrendu Paul <rkpaul.venture@gmail.com>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: agents,debugging,langgraph,llm,observability,openai,replay,tracing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+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 :: Debuggers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich>=13.0
+Provides-Extra: agno
+Requires-Dist: agno>=2.7; extra == 'agno'
+Provides-Extra: aiohttp
+Requires-Dist: aiohttp>=3.9; extra == 'aiohttp'
+Provides-Extra: autogen
+Requires-Dist: autogen-agentchat>=0.4; extra == 'autogen'
+Requires-Dist: autogen-ext[openai]>=0.4; extra == 'autogen'
+Provides-Extra: botocore
+Requires-Dist: boto3>=1.34; extra == 'botocore'
+Provides-Extra: crewai
+Requires-Dist: crewai>=1.0.0; extra == 'crewai'
+Provides-Extra: dev
+Requires-Dist: aiohttp>=3.9; extra == 'dev'
+Requires-Dist: aioresponses>=0.7; extra == 'dev'
+Requires-Dist: boto3>=1.34; extra == 'dev'
+Requires-Dist: groq>=0.9; extra == 'dev'
+Requires-Dist: grpcio-tools>=1.60; extra == 'dev'
+Requires-Dist: grpcio>=1.60; extra == 'dev'
+Requires-Dist: langchain-classic>=1.0; extra == 'dev'
+Requires-Dist: langchain-core>=0.3; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-benchmark[histogram]>=4.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest-env>=1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: requests>=2.31; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: types-requests>=2.31; extra == 'dev'
+Requires-Dist: websockets>=13.0; extra == 'dev'
+Provides-Extra: google-genai
+Requires-Dist: google-genai>=2.0; extra == 'google-genai'
+Requires-Dist: langchain-google-genai>=4.0; extra == 'google-genai'
+Provides-Extra: groq
+Requires-Dist: groq>=0.9; extra == 'groq'
+Provides-Extra: grpc
+Requires-Dist: grpcio>=1.60; extra == 'grpc'
+Provides-Extra: haystack
+Requires-Dist: haystack-ai>=2.0; extra == 'haystack'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == 'langchain'
+Provides-Extra: langgraph
+Requires-Dist: langchain-core>=0.3; extra == 'langgraph'
+Requires-Dist: langgraph>=1.0.10; extra == 'langgraph'
+Provides-Extra: llama-index
+Requires-Dist: llama-index-core>=0.14; extra == 'llama-index'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.26; extra == 'mcp'
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.0.3; extra == 'openai-agents'
+Provides-Extra: otlp
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.25; extra == 'otlp'
+Provides-Extra: pydantic-ai
+Requires-Dist: pydantic-ai>=2.0; extra == 'pydantic-ai'
+Provides-Extra: realtime
+Requires-Dist: websockets>=13.0; extra == 'realtime'
+Provides-Extra: requests
+Requires-Dist: requests>=2.31; extra == 'requests'
+Description-Content-Type: text/markdown
+
+# Agent Observability
+
+**Deterministic record/replay for LLM agents.** Capture a failing agent run once, reproduce it offline in under 2 ms with zero API calls, on any Python HTTP client.
+
+```
+# Record a 12-step LangGraph run that fails at step 7
+$ uv run --extra langgraph python demos/record_replay_demo.py
+
+=== RECORD MODE ===
+Running 12-step pipeline  (will fail at step 7)
+
+  ✓ step_01  completed
+  ...
+  ✓ step_06  completed
+  ✗ step_07  Step 7: upstream dependency returned null — cannot continue pipeline
+
+Recorded:
+  8 spans captured
+  fixture → /tmp/agent-trace-demo-.../pipeline-run-001/fixture.db
+  7 node spans
+  1 error span(s)
+
+=== REPLAY MODE ===
+(No network calls — all state served from local fixture)
+
+  ✓ step_01  completed
+  ...
+  ✓ step_06  completed
+  ✗ step_07  Step 7: upstream dependency returned null — cannot continue pipeline
+
+Replay complete — same failure reproduced offline.
+```
+
+[![PyPI](https://img.shields.io/pypi/v/agent-trace)](https://pypi.org/project/agent-trace/)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![CI](https://github.com/RudrenduPaul/agent-observability/actions/workflows/ci.yml/badge.svg)](https://github.com/RudrenduPaul/agent-observability/actions)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/RudrenduPaul/agent-observability/badge)](https://securityscorecards.dev/viewer/?uri=github.com/RudrenduPaul/agent-observability)
+
+---
+
+## Install
+
+```bash
+pip install agent-trace
+# or
+uv add agent-trace
+```
+
+LangGraph support:
+
+```bash
+pip install agent-trace[langgraph]
+```
+
+OpenAI Agents SDK support:
+
+```bash
+pip install agent-trace[openai-agents]
+```
+
+## The problem
+
+A LangGraph run fails after step 8. Your trace in LangSmith or Langfuse shows *what* broke. But to reproduce it you have to re-run the entire agent: 8 more LLM calls, 30 more seconds, another $0.15 in API cost. If the failure was caused by a specific tool response or a transient model output, you can't reproduce it at all. You're debugging against a moving target.
+
+**Agent Observability solves this at the HTTP transport layer.** It records every request and response verbatim to a local SQLite file. Replay serves those exact bytes back in sequence, in under 1 ms per exchange: same code path, same span tree, same failure. No API calls.
+
+```
+Recording overhead:   0.011%  (0.090 ms added per LLM call — 0.011% of GPT-4o p50)
+Replay latency:       0.93 ms mean  (vs ~8,500 ms live on GPT-4o × 10 steps)
+Replay fidelity:      100%  (response bytes byte-for-byte identical to recorded)
+CI cost per replay:   $0
+```
+
+---
+
+## Quick start
+
+```python
+from agent_trace import tracer
+import httpx
+
+@tracer.instrument(record=True)
+def fetch_data(query: str) -> dict:
+    with tracer.span("http-call") as span:
+        resp = httpx.get("https://httpbin.org/get", params={"q": query})
+        span.set_attribute("http.status_code", resp.status_code)
+        return resp.json()
+
+result = fetch_data("hello")
+# Trace and fixture saved to ~/.agent-trace/runs/run_<id>/
+```
+
+Replay offline — no API calls, no tokens:
+
+```python
+from agent_trace import replay
+
+with replay("run_<id>") as ctx:
+    result = fetch_data("hello")  # served from fixture, zero network
+    print(result)                 # identical to the original run
+```
+
+> To store the input for later retrieval in replay, call `ctx.fixture.set_metadata('input', query)` inside the recording context.
+
+> **Sync and async clients:** Agent Observability intercepts `httpx.Client`, `httpx.AsyncClient`, and `requests.Session` — including the async client used by default in the OpenAI Python SDK v1.x and Anthropic SDK. The patch is installed at request-dispatch time, so it also covers clients constructed before recording/replay starts (e.g. a module-level `openai.AsyncOpenAI()` instance).
+
+---
+
+## Use in CI: replay at zero cost
+
+Record once. Commit the fixture. Replay in every CI run at zero API cost:
+
+```python
+# tests/test_agent.py
+import pytest
+from pathlib import Path
+from agent_trace import replay
+
+FIXTURE_PATH = Path("fixtures/my_agent_run.db")
+
+@pytest.mark.skipif(
+    not FIXTURE_PATH.exists(),
+    reason="Run: python scripts/record_fixture.py to generate the fixture"
+)
+def test_agent_answer():
+    with replay(FIXTURE_PATH) as ctx:
+        from my_module import my_agent
+        result = my_agent("what is 2+2?")
+    assert "4" in result
+```
+
+Set `AGENT_TRACE_NETWORK_GUARD=1` in CI. Any HTTP call not in the fixture raises `NetworkGuardError` immediately — catching regressions before they hit production.
+
+```bash
+AGENT_TRACE_NETWORK_GUARD=1 uv run pytest tests/
+```
+
+---
+
+## How Agent Observability compares
+
+Most observability tools for LLM agents are **observe-only** — they show you a trace of what happened, but reproducing a failure still requires re-running the full agent against live APIs.
+
+| Capability | Agent Observability | LangSmith | Langfuse | Helicone | OpenLLMetry |
+|---|---|---|---|---|---|
+| Offline replay from local fixture | **Yes** | Partial ¹ | No | No | No |
+| Works with any HTTP client | **Yes** | No | No | No | No |
+| CI replay without API keys | **Yes** | Partial ¹ | No | No | No |
+| Deterministic span timing in replay | **Yes** | No | No | No | No |
+| Captures raw HTTP request/response bytes | **Yes** | No | No | Yes | No |
+| Span-level tracing | Yes | Yes | Yes | Yes | Yes |
+| OTLP export (Jaeger, Grafana Tempo) | Yes | No | Yes | No | Yes |
+| Open-source core | Yes | No | Yes | No | Yes |
+| Local-only, no server required | Yes | No | Self-host | No | Self-host |
+
+¹ LangSmith has `LANGSMITH_TEST_CACHE` / VCR cassettes (`langsmith[vcr]`) for Python + LangChain only. It captures HTTP to `api.openai.com` but not arbitrary HTTP clients, does not record full wire-level bytes, and requires a LangSmith account.
+
+**Choose LangSmith** if your team is on LangChain and needs dataset management, prompt versioning, and human feedback loops.
+
+**Choose Langfuse** if you want a fully open-source, self-hostable observability stack with strong Postgres-backed storage.
+
+**Choose OpenLLMetry** if your team already runs on OpenTelemetry and wants standard `gen_ai.*` spans without adding a new observability system.
+
+**Agent Observability** is not a replacement for dashboards and eval pipelines. It solves the specific upstream problem: reproducing a specific failed run without any LLM API cost, for any agent built on any Python HTTP client.
+
+---
+
+## Try it with Docker
+
+Agent Observability emits OTLP spans. Run a local observability stack to browse trace trees:
+
+```bash
+git clone https://github.com/RudrenduPaul/agent-observability
+cd agent-observability
+docker compose up -d
+```
+
+Starts three services (all optional):
+
+- **Jaeger** (`http://localhost:16686`) — OTLP span ingestion and trace UI
+- **Grafana** (`http://localhost:3000`) — dashboards and alerts
+- **Tempo** (port 3200) — long-term trace storage backend
+
+Then point your exporter at the collector:
+
+```python
+from agent_trace.exporters.otlp import OTLPExporter
+
+# 4317 = OTLP gRPC ingestion endpoint
+exporter = OTLPExporter(endpoint="http://localhost:4317")
+exporter.export(trace)
+```
+
+---
+
+## Known limitations
+
+Agent Observability's capture model is HTTP-interceptor-based (plus
+instrumented framework callbacks for the integrations under
+`src/agent_trace/integrations/`) and process-local. That model has real
+edges — stated explicitly here so they're clear before you hit one, not
+after:
+
+- **Process-local only.** Recording/replay happens inside the Python
+  process you import `agent_trace` into (`httpx.Client(transport=
+  RecordingTransport(...))`, `session.mount(..., RecordingAdapter(...))`,
+  or `ReplayEngine.replay()`'s monkeypatches — see
+  `src/agent_trace/interceptor/`). It cannot observe or replay calls made
+  by a third-party **hosted** service you don't run or deploy yourself
+  (e.g. a vendor's own hosted chat assistant) — only your own process's
+  outbound calls.
+
+- **gRPC coverage is partial.** `src/agent_trace/interceptor/grpc_hook.py`
+  patches `grpc.secure_channel`/`grpc.insecure_channel` (and the `grpc.aio`
+  equivalents) to capture Gemini/Vertex AI traffic that bypasses `httpx`
+  entirely — unary-unary calls (e.g. `GenerateContent`) and sync
+  unary-stream calls (e.g. `StreamGenerateContent`) are fully recorded and
+  replayed. Client-streaming and bidirectional-streaming gRPC calls, and
+  any `grpc.aio` streaming call, are **not** captured — those go straight
+  to the live network unintercepted, both during recording and (if
+  attempted) replay.
+
+- **Capture starts once a request object exists.** `RecordingTransport.
+  handle_request`/`AsyncRecordingTransport.handle_async_request`
+  (`httpx_hook.py`) and `RecordingAdapter.send`
+  (`requests_patch.py`) only run once a fully-constructed
+  `httpx.Request`/`PreparedRequest` reaches them. Any exception raised
+  *before* that — while an SDK is serializing a tool schema, building
+  headers, or otherwise assembling the call, or even earlier, during plain
+  Python object construction (e.g. `TypeError` from `abc.ABCMeta` when
+  instantiating an abstract class incorrectly) — happens entirely upstream
+  of the interceptor's capture surface and produces zero fixture rows.
+  A wired-in framework integration's own error callback (e.g.
+  `LangGraphTracer.on_llm_error`) *does* still capture such pre-HTTP
+  exceptions when they propagate through that framework's own
+  `try`/`except` — so "invisible to the interceptor" is not the same as
+  "invisible everywhere": it depends on whether a framework integration is
+  wired in for the exception to pass through.
+
+- **No visibility into a framework's own print/display code.** Exceptions
+  raised inside local logging/printing/display machinery — e.g. `rich`
+  Console output, IPython/Jupyter display hooks, triggered by a framework's
+  own `verbose=True` logging — have zero HTTP traffic and zero framework
+  callback surface. No existing or planned capture mechanism (HTTP
+  interceptor, MCP stdio-transport hook, or any framework integration)
+  observes this category of failure.
+
+---
+
+## Security
+
+- **Supply chain:** SLSA Level 2 via GitHub Actions provenance. All releases signed with Sigstore. SBOM attached to every GitHub Release.
+- **Vulnerability scanning:** Dependabot keeps all GitHub Actions and Python dependencies current. Secret scanning auto-enables when the repo goes public.
+- **Fixture safety:** Fixture files at `~/.agent-trace/runs/` contain full HTTP request and response bodies, including API keys and prompt contents. Add `.agent-trace/` and `*.db` to your `.gitignore`. Never commit a fixture generated against a production API key.
+- **Disclosure:** [SECURITY.md](SECURITY.md) — report vulnerabilities to `agent.obs.oss.security@gmail.com` with a 48-hour response SLA.
+
+---
+
+## Contributing
+
+- Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR
+- Good first issues are labeled in [GitHub Issues](https://github.com/RudrenduPaul/agent-observability/issues)
+- Replay engine (`src/agent_trace/_replay/`) requires 80% test coverage — correctness-critical
+- Interceptor (`src/agent_trace/interceptor/`) requires 80% test coverage
+- GitHub Discussions for design questions and ideas
+
+Apache 2.0. Contributions welcome.
+
+---
+
+*Built by Rudrendu Paul*