eigenh-observe 0.4.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- eigenh_observe-0.4.0/.gitignore +8 -0
- eigenh_observe-0.4.0/LICENSE +21 -0
- eigenh_observe-0.4.0/PKG-INFO +92 -0
- eigenh_observe-0.4.0/README.md +50 -0
- eigenh_observe-0.4.0/SKILL.md +436 -0
- eigenh_observe-0.4.0/pyproject.toml +34 -0
- eigenh_observe-0.4.0/src/eigenh_observe/__init__.py +27 -0
- eigenh_observe-0.4.0/src/eigenh_observe/_core.py +307 -0
- eigenh_observe-0.4.0/src/eigenh_observe/context.py +48 -0
- eigenh_observe-0.4.0/src/eigenh_observe/gen_ai.py +337 -0
- eigenh_observe-0.4.0/tests/test_basic.py +107 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 EigenH
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: eigenh-observe
|
|
3
|
+
Version: 0.4.0
|
|
4
|
+
Summary: EigenH observability — structured logs + AI events + distributed traces
|
|
5
|
+
License: MIT License
|
|
6
|
+
|
|
7
|
+
Copyright (c) 2026 EigenH
|
|
8
|
+
|
|
9
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
10
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
11
|
+
in the Software without restriction, including without limitation the rights
|
|
12
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
13
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
14
|
+
furnished to do so, subject to the following conditions:
|
|
15
|
+
|
|
16
|
+
The above copyright notice and this permission notice shall be included in all
|
|
17
|
+
copies or substantial portions of the Software.
|
|
18
|
+
|
|
19
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
20
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
21
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
22
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
23
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
24
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
25
|
+
SOFTWARE.
|
|
26
|
+
License-File: LICENSE
|
|
27
|
+
Requires-Python: >=3.11
|
|
28
|
+
Requires-Dist: opentelemetry-api>=1.20.0
|
|
29
|
+
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20.0
|
|
30
|
+
Requires-Dist: opentelemetry-sdk>=1.20.0
|
|
31
|
+
Requires-Dist: posthog>=3.0.0
|
|
32
|
+
Provides-Extra: dev
|
|
33
|
+
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
|
|
34
|
+
Requires-Dist: pytest>=7; extra == 'dev'
|
|
35
|
+
Provides-Extra: fastapi
|
|
36
|
+
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.40b0; extra == 'fastapi'
|
|
37
|
+
Provides-Extra: http
|
|
38
|
+
Requires-Dist: opentelemetry-instrumentation-aiohttp-client>=0.40b0; extra == 'http'
|
|
39
|
+
Requires-Dist: opentelemetry-instrumentation-httpx>=0.40b0; extra == 'http'
|
|
40
|
+
Requires-Dist: opentelemetry-instrumentation-requests>=0.40b0; extra == 'http'
|
|
41
|
+
Description-Content-Type: text/markdown
|
|
42
|
+
|
|
43
|
+
# eigenh-observe
|
|
44
|
+
|
|
45
|
+
Observability package for EigenH services — structured logs, AI generation events, and distributed traces, all routed to PostHog.
|
|
46
|
+
|
|
47
|
+
## Install
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
pip install eigenh-observe
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## Quick start
|
|
54
|
+
|
|
55
|
+
```python
|
|
56
|
+
import eigenh_observe
|
|
57
|
+
|
|
58
|
+
eigenh_observe.init(
|
|
59
|
+
service_name="my-service",
|
|
60
|
+
env="prod",
|
|
61
|
+
instrument_http=True,
|
|
62
|
+
)
|
|
63
|
+
|
|
64
|
+
token = eigenh_observe.set_call_context(call_id="room-123", org_id="org-abc", caller="+1234567890")
|
|
65
|
+
try:
|
|
66
|
+
with eigenh_observe.session_span():
|
|
67
|
+
with eigenh_observe.llm_span("gemini-2.5-flash") as span:
|
|
68
|
+
# ... call your LLM ...
|
|
69
|
+
span.set_usage(input_tokens=100, output_tokens=50)
|
|
70
|
+
finally:
|
|
71
|
+
eigenh_observe.reset_call_context(token)
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## Features
|
|
75
|
+
|
|
76
|
+
- Structured logs → PostHog Logs (with `call_id`, `org_id`, `caller` as filterable attributes)
|
|
77
|
+
- AI generation events → PostHog AI Observability (`$ai_generation`, `$ai_span`)
|
|
78
|
+
- Distributed traces → PostHog Traces (session → llm → tool span tree)
|
|
79
|
+
- HTTP auto-instrumentation (`requests`, `httpx`, `aiohttp`)
|
|
80
|
+
- FastAPI inbound `traceparent` extraction
|
|
81
|
+
|
|
82
|
+
## Environment variables
|
|
83
|
+
|
|
84
|
+
| Variable | Purpose |
|
|
85
|
+
|---|---|
|
|
86
|
+
| `POSTHOG_API_KEY` | PostHog project API key |
|
|
87
|
+
| `POSTHOG_HOST` | PostHog host (default: `https://us.i.posthog.com`) |
|
|
88
|
+
| `APP_ENV` | Environment name (`dev`, `stage`, `prod`) |
|
|
89
|
+
|
|
90
|
+
## License
|
|
91
|
+
|
|
92
|
+
MIT
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# eigenh-observe
|
|
2
|
+
|
|
3
|
+
Observability package for EigenH services — structured logs, AI generation events, and distributed traces, all routed to PostHog.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
pip install eigenh-observe
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Quick start
|
|
12
|
+
|
|
13
|
+
```python
|
|
14
|
+
import eigenh_observe
|
|
15
|
+
|
|
16
|
+
eigenh_observe.init(
|
|
17
|
+
service_name="my-service",
|
|
18
|
+
env="prod",
|
|
19
|
+
instrument_http=True,
|
|
20
|
+
)
|
|
21
|
+
|
|
22
|
+
token = eigenh_observe.set_call_context(call_id="room-123", org_id="org-abc", caller="+1234567890")
|
|
23
|
+
try:
|
|
24
|
+
with eigenh_observe.session_span():
|
|
25
|
+
with eigenh_observe.llm_span("gemini-2.5-flash") as span:
|
|
26
|
+
# ... call your LLM ...
|
|
27
|
+
span.set_usage(input_tokens=100, output_tokens=50)
|
|
28
|
+
finally:
|
|
29
|
+
eigenh_observe.reset_call_context(token)
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## Features
|
|
33
|
+
|
|
34
|
+
- Structured logs → PostHog Logs (with `call_id`, `org_id`, `caller` as filterable attributes)
|
|
35
|
+
- AI generation events → PostHog AI Observability (`$ai_generation`, `$ai_span`)
|
|
36
|
+
- Distributed traces → PostHog Traces (session → llm → tool span tree)
|
|
37
|
+
- HTTP auto-instrumentation (`requests`, `httpx`, `aiohttp`)
|
|
38
|
+
- FastAPI inbound `traceparent` extraction
|
|
39
|
+
|
|
40
|
+
## Environment variables
|
|
41
|
+
|
|
42
|
+
| Variable | Purpose |
|
|
43
|
+
|---|---|
|
|
44
|
+
| `POSTHOG_API_KEY` | PostHog project API key |
|
|
45
|
+
| `POSTHOG_HOST` | PostHog host (default: `https://us.i.posthog.com`) |
|
|
46
|
+
| `APP_ENV` | Environment name (`dev`, `stage`, `prod`) |
|
|
47
|
+
|
|
48
|
+
## License
|
|
49
|
+
|
|
50
|
+
MIT
|
|
@@ -0,0 +1,436 @@
|
|
|
1
|
+
# eigenh-observe — OTEL Observability Integration Skill
|
|
2
|
+
|
|
3
|
+
Invoked via `/eigenh-observe`. Integrates the `eigenh-observe` package into any Python project to ship:
|
|
4
|
+
- **Structured logs** → OTEL collector → PostHog Logs section (with `call_id`, `org_id`, `caller` as filterable attributes)
|
|
5
|
+
- **gen_ai.* traces** → OTEL collector → PostHog Traces / Generations section as a connected call tree
|
|
6
|
+
|
|
7
|
+
Works for voice agents, FastAPI services, chat agents, pipelines — anything Python.
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## What you will do
|
|
12
|
+
|
|
13
|
+
1. Discover the project structure and entry point
|
|
14
|
+
2. Add `eigenh-observe` to the project's dependencies
|
|
15
|
+
3. Call `eigenh_observe.init()` at startup
|
|
16
|
+
4. Set call/session context at the entry point of each concurrent unit of work
|
|
17
|
+
5. Wrap the entire session in `session_span()` — the root of the trace tree
|
|
18
|
+
6. Wrap LLM calls with `llm_span()` and tool calls with `tool_span()`
|
|
19
|
+
7. Wire HTTP instrumentation and FastAPI if applicable
|
|
20
|
+
8. Set the required env vars
|
|
21
|
+
9. Verify logs and traces appear in PostHog
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## Step 1 — Discover the project
|
|
26
|
+
|
|
27
|
+
Read:
|
|
28
|
+
- Package manifest: `pyproject.toml`, `setup.py`, or `requirements.txt`
|
|
29
|
+
- Entry point: `main.py`, `app.py`, `agent.py`, `server.py` — wherever the app or worker starts
|
|
30
|
+
- Framework: FastAPI, LiveKit agent, plain asyncio, Flask, etc.
|
|
31
|
+
- HTTP clients in use: `requests`, `httpx`, `aiohttp`
|
|
32
|
+
- How concurrent sessions are identified (room name, call id, request id, user id)
|
|
33
|
+
|
|
34
|
+
Ask the developer if not obvious:
|
|
35
|
+
- "What identifies a single session or call?" (default: `session_id`)
|
|
36
|
+
- "What is your `OTEL_EXPORTER_OTLP_ENDPOINT`?" (the OTEL collector base URL, e.g. `http://localhost:4318`)
|
|
37
|
+
- "What is `APP_ENV`?" (`dev`, `stage`, `prod`)
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
## Step 2 — Install the package
|
|
42
|
+
|
|
43
|
+
`eigenh-observe` is in a **private GitHub repo**. The install method depends on the environment.
|
|
44
|
+
|
|
45
|
+
### Local dev (SSH — recommended if the developer has GitHub SSH keys)
|
|
46
|
+
|
|
47
|
+
Add to `pyproject.toml` dependencies:
|
|
48
|
+
|
|
49
|
+
```toml
|
|
50
|
+
"eigenh-observe @ git+ssh://git@github.com/EigenH/eigenh-observe.git",
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
With HTTP instrumentation extras:
|
|
54
|
+
|
|
55
|
+
```toml
|
|
56
|
+
"eigenh-observe[http] @ git+ssh://git@github.com/EigenH/eigenh-observe.git",
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
For FastAPI services:
|
|
60
|
+
|
|
61
|
+
```toml
|
|
62
|
+
"eigenh-observe[http,fastapi] @ git+ssh://git@github.com/EigenH/eigenh-observe.git",
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Then install:
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
uv pip install -e ".[dev]"
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
### CI/CD / Cloud Run build (HTTPS with GitHub token)
|
|
72
|
+
|
|
73
|
+
In GitHub Actions, `GITHUB_TOKEN` is available automatically. In other CI systems, create a PAT with `repo` scope and store it as a secret.
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
uv pip install "eigenh-observe @ git+https://x-access-token:${GITHUB_TOKEN}@github.com/EigenH/eigenh-observe.git"
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Or pin it in `requirements.txt` for Docker builds:
|
|
80
|
+
|
|
81
|
+
```
|
|
82
|
+
eigenh-observe @ git+https://x-access-token:${GITHUB_TOKEN}@github.com/EigenH/eigenh-observe.git
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
In the Dockerfile:
|
|
86
|
+
|
|
87
|
+
```dockerfile
|
|
88
|
+
ARG GITHUB_TOKEN
|
|
89
|
+
RUN uv pip install "eigenh-observe @ git+https://x-access-token:${GITHUB_TOKEN}@github.com/EigenH/eigenh-observe.git"
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
Pass the token at build time via GitHub Actions secret:
|
|
93
|
+
|
|
94
|
+
```yaml
|
|
95
|
+
- name: Build image
|
|
96
|
+
run: docker build --build-arg GITHUB_TOKEN=${{ secrets.GITHUB_TOKEN }} .
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
**Never hardcode the token in source files.**
|
|
100
|
+
|
|
101
|
+
---
|
|
102
|
+
|
|
103
|
+
## Step 3 — Init at startup
|
|
104
|
+
|
|
105
|
+
Find the app's startup location (lifespan, `prewarm`, module level, `create_app`) and add one of the following depending on the backend:
|
|
106
|
+
|
|
107
|
+
### Direct PostHog (no collector needed — use this now)
|
|
108
|
+
|
|
109
|
+
```python
|
|
110
|
+
import eigenh_observe
|
|
111
|
+
|
|
112
|
+
eigenh_observe.init(
|
|
113
|
+
service_name="your-service-name",
|
|
114
|
+
env=os.getenv("APP_ENV", "dev"),
|
|
115
|
+
instrument_http=True,
|
|
116
|
+
# posthog_api_key read from POSTHOG_API_KEY env var automatically
|
|
117
|
+
)
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Or pass the key explicitly:
|
|
121
|
+
|
|
122
|
+
```python
|
|
123
|
+
eigenh_observe.init(
|
|
124
|
+
posthog_api_key=os.getenv("POSTHOG_API_KEY"),
|
|
125
|
+
posthog_host="https://us.i.posthog.com", # or https://eu.i.posthog.com
|
|
126
|
+
service_name="your-service-name",
|
|
127
|
+
env=os.getenv("APP_ENV", "dev"),
|
|
128
|
+
instrument_http=True,
|
|
129
|
+
)
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### OTEL collector (future — swap PostHog → Datadog via collector config only)
|
|
133
|
+
|
|
134
|
+
```python
|
|
135
|
+
eigenh_observe.init(
|
|
136
|
+
service_name="your-service-name",
|
|
137
|
+
env=os.getenv("APP_ENV", "dev"),
|
|
138
|
+
instrument_http=True,
|
|
139
|
+
# otlp_endpoint read from OTEL_EXPORTER_OTLP_ENDPOINT env var automatically
|
|
140
|
+
)
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
**Priority when both are set:** `otlp_endpoint` / `OTEL_EXPORTER_OTLP_ENDPOINT` takes precedence over `posthog_api_key`.
|
|
144
|
+
|
|
145
|
+
**`instrument_http=True`** auto-instruments any of `requests`, `httpx`, `aiohttp-client` that are installed, so outbound HTTP calls carry the `traceparent` header. Missing libs are silently skipped.
|
|
146
|
+
|
|
147
|
+
**Rules:**
|
|
148
|
+
- Call `init()` once, before the server starts accepting requests or workers start handling calls.
|
|
149
|
+
- If neither PostHog key nor OTLP endpoint is set, logs go to stdout — safe for local dev.
|
|
150
|
+
- Do NOT call `logging.basicConfig()` after `init()` — it will interfere with the log handler.
|
|
151
|
+
|
|
152
|
+
---
|
|
153
|
+
|
|
154
|
+
## Step 4 — Wire FastAPI (if applicable)
|
|
155
|
+
|
|
156
|
+
If the project is a FastAPI service that receives requests from other services (e.g. a frontend or API gateway), wire inbound context extraction so the full request path is one connected trace:
|
|
157
|
+
|
|
158
|
+
```python
|
|
159
|
+
from fastapi import FastAPI
|
|
160
|
+
import eigenh_observe
|
|
161
|
+
|
|
162
|
+
app = FastAPI()
|
|
163
|
+
|
|
164
|
+
# After init(), before the app starts serving
|
|
165
|
+
eigenh_observe.init(service_name="my-api", env=os.getenv("APP_ENV", "dev"))
|
|
166
|
+
eigenh_observe.instrument_fastapi(app)
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
This reads the `traceparent` header from inbound requests so spans created inside the handler appear as children of whatever span the caller started.
|
|
170
|
+
|
|
171
|
+
Skip this step for voice agents (LiveKit, Plivo, Twilio) — the telephony boundary has no HTTP header.
|
|
172
|
+
|
|
173
|
+
---
|
|
174
|
+
|
|
175
|
+
## Step 5 — Set call/session context
|
|
176
|
+
|
|
177
|
+
At the **entry point** of each concurrent unit of work (each call, session, or request), set the context so every log line inside carries the identifiers as OTLP attributes.
|
|
178
|
+
|
|
179
|
+
### asyncio / LiveKit agent pattern
|
|
180
|
+
|
|
181
|
+
```python
|
|
182
|
+
import eigenh_observe
|
|
183
|
+
|
|
184
|
+
async def entrypoint(ctx):
|
|
185
|
+
token = eigenh_observe.set_call_context(
|
|
186
|
+
call_id=ctx.room.name,
|
|
187
|
+
org_id=getattr(runtime, "org_id", ""),
|
|
188
|
+
caller=getattr(userdata, "phone", ""),
|
|
189
|
+
)
|
|
190
|
+
try:
|
|
191
|
+
# ... all session logic here ...
|
|
192
|
+
finally:
|
|
193
|
+
eigenh_observe.reset_call_context(token)
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
### FastAPI middleware pattern
|
|
197
|
+
|
|
198
|
+
```python
|
|
199
|
+
import uuid
|
|
200
|
+
from fastapi import Request
|
|
201
|
+
import eigenh_observe
|
|
202
|
+
|
|
203
|
+
@app.middleware("http")
|
|
204
|
+
async def session_context_middleware(request: Request, call_next):
|
|
205
|
+
session_id = request.headers.get("X-Session-ID") or str(uuid.uuid4())
|
|
206
|
+
token = eigenh_observe.set_call_context(
|
|
207
|
+
call_id=session_id,
|
|
208
|
+
org_id=request.headers.get("X-Org-ID", ""),
|
|
209
|
+
)
|
|
210
|
+
try:
|
|
211
|
+
return await call_next(request)
|
|
212
|
+
finally:
|
|
213
|
+
eigenh_observe.reset_call_context(token)
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
**Rules:**
|
|
217
|
+
- Always call `reset_call_context(token)` in a `finally` block — never skip it.
|
|
218
|
+
- If a shutdown callback or background task runs in a fresh async context (e.g. LiveKit shutdown hooks), re-call `set_call_context()` at the top of that callback too.
|
|
219
|
+
- `call_id` must be unique per session. Room name, request ID, or UUID all work.
|
|
220
|
+
|
|
221
|
+
---
|
|
222
|
+
|
|
223
|
+
## Step 6 — Wrap the session in session_span()
|
|
224
|
+
|
|
225
|
+
`session_span()` creates the **root span** of the trace. Every `llm_span()` and `tool_span()` called inside it automatically becomes a child — forming a connected tree in PostHog Traces instead of disconnected individual spans.
|
|
226
|
+
|
|
227
|
+
### asyncio / LiveKit agent
|
|
228
|
+
|
|
229
|
+
```python
|
|
230
|
+
async def entrypoint(ctx):
|
|
231
|
+
token = eigenh_observe.set_call_context(
|
|
232
|
+
call_id=ctx.room.name,
|
|
233
|
+
org_id=getattr(runtime, "org_id", ""),
|
|
234
|
+
caller=getattr(userdata, "phone", ""),
|
|
235
|
+
)
|
|
236
|
+
try:
|
|
237
|
+
with eigenh_observe.session_span(): # reads call context automatically
|
|
238
|
+
await run_agent(ctx) # all spans inside are children
|
|
239
|
+
finally:
|
|
240
|
+
eigenh_observe.reset_call_context(token)
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
### FastAPI request handler
|
|
244
|
+
|
|
245
|
+
```python
|
|
246
|
+
@app.post("/chat")
|
|
247
|
+
async def chat(request: ChatRequest):
|
|
248
|
+
with eigenh_observe.session_span(call_id=request.session_id, org_id=request.org_id):
|
|
249
|
+
response = await handle_chat(request)
|
|
250
|
+
return response
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
**What you get in PostHog Traces:**
|
|
254
|
+
```
|
|
255
|
+
session [2.4s] ← session_span() — root
|
|
256
|
+
├── chat gemini-2.5-flash [1.1s] ← llm_span() — child
|
|
257
|
+
│ └── tool book_appointment ← tool_span() — grandchild
|
|
258
|
+
└── chat gemini-2.5-flash [0.8s] ← llm_span() — child
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
**Rules:**
|
|
262
|
+
- Place `session_span()` AFTER `set_call_context()` — it reads from the context if no args given.
|
|
263
|
+
- One `session_span()` per call/session. Do not nest multiple session spans.
|
|
264
|
+
- For shutdown callbacks in fresh async contexts, `session_span()` can be called again — it creates a short child-less span for the shutdown work, which is fine.
|
|
265
|
+
|
|
266
|
+
---
|
|
267
|
+
|
|
268
|
+
## Step 7 — Wrap LLM calls with llm_span
|
|
269
|
+
|
|
270
|
+
```python
|
|
271
|
+
import eigenh_observe
|
|
272
|
+
|
|
273
|
+
async def call_llm(model: str, messages: list) -> str:
|
|
274
|
+
with eigenh_observe.llm_span(model, system="google_vertex_ai", operation="chat") as span:
|
|
275
|
+
response = await your_llm_client.generate(messages)
|
|
276
|
+
span.set_usage(
|
|
277
|
+
input_tokens=response.usage.input_tokens,
|
|
278
|
+
output_tokens=response.usage.output_tokens,
|
|
279
|
+
)
|
|
280
|
+
span.set_finish_reason(response.finish_reason)
|
|
281
|
+
return response.text
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
For realtime / streaming models where token counts arrive in a metrics callback:
|
|
285
|
+
|
|
286
|
+
```python
|
|
287
|
+
def on_metrics(m):
|
|
288
|
+
with eigenh_observe.llm_span(m.model) as span:
|
|
289
|
+
span.set_usage(input_tokens=m.input_tokens, output_tokens=m.output_tokens)
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
**`llm_span()` parameters:**
|
|
293
|
+
|
|
294
|
+
| Parameter | Default | Description |
|
|
295
|
+
|-----------|---------|-------------|
|
|
296
|
+
| `model` | required | Model name, e.g. `"gemini-2.5-flash"` |
|
|
297
|
+
| `system` | `"google_vertex_ai"` | AI system — `gen_ai.system` attribute |
|
|
298
|
+
| `operation` | `"chat"` | Operation name — `gen_ai.operation.name` attribute |
|
|
299
|
+
|
|
300
|
+
`call_id` and `org_id` are injected automatically from the current call context.
|
|
301
|
+
|
|
302
|
+
---
|
|
303
|
+
|
|
304
|
+
## Step 8 — Wrap tool calls with tool_span
|
|
305
|
+
|
|
306
|
+
```python
|
|
307
|
+
import eigenh_observe
|
|
308
|
+
|
|
309
|
+
async def book_appointment(slot_id: str) -> dict:
|
|
310
|
+
with eigenh_observe.tool_span("book_appointment"):
|
|
311
|
+
result = await firestore_client.create_booking(slot_id)
|
|
312
|
+
return result
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
If the code inside raises, `tool_span` records the exception on the span and re-raises.
|
|
316
|
+
|
|
317
|
+
---
|
|
318
|
+
|
|
319
|
+
## Step 9 — Set env vars
|
|
320
|
+
|
|
321
|
+
### Direct PostHog mode (current recommended approach)
|
|
322
|
+
|
|
323
|
+
```env
|
|
324
|
+
POSTHOG_API_KEY=phc_xxxxxxxxxxxxxxxxxxxx
|
|
325
|
+
POSTHOG_HOST=https://us.i.posthog.com # or eu.i.posthog.com — optional, this is the default
|
|
326
|
+
APP_ENV=prod
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
### OTEL collector mode (future)
|
|
330
|
+
|
|
331
|
+
```env
|
|
332
|
+
OTEL_EXPORTER_OTLP_ENDPOINT=http://your-otel-collector:4318
|
|
333
|
+
APP_ENV=prod
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
When `OTEL_EXPORTER_OTLP_ENDPOINT` is set it takes precedence — the PostHog key is not needed in the app (the collector holds it).
|
|
337
|
+
|
|
338
|
+
For local dev, leave both unset — logs print to stdout, traces are a no-op.
|
|
339
|
+
|
|
340
|
+
---
|
|
341
|
+
|
|
342
|
+
## Step 10 — Verify
|
|
343
|
+
|
|
344
|
+
Run the app and trigger a session. Then check:
|
|
345
|
+
|
|
346
|
+
**PostHog → Logs:**
|
|
347
|
+
- Log lines appear with `call_id`, `org_id`, `caller` as filterable attributes
|
|
348
|
+
- `service.name` matches what you passed to `init()`
|
|
349
|
+
- Filter by `org_id` to confirm tenant separation
|
|
350
|
+
|
|
351
|
+
**PostHog → Traces:**
|
|
352
|
+
- Each session appears as one trace with a `session` root span
|
|
353
|
+
- `llm_span` and `tool_span` calls appear as children/grandchildren
|
|
354
|
+
- The waterfall shows the full call timeline
|
|
355
|
+
|
|
356
|
+
**PostHog → AI → Generations:**
|
|
357
|
+
- `llm_span` calls appear with token counts, model name, latency
|
|
358
|
+
|
|
359
|
+
**If nothing appears:**
|
|
360
|
+
1. Check `[eigenh-observe] init` log line on startup — confirms the pipeline started
|
|
361
|
+
2. Check `OTEL_EXPORTER_OTLP_ENDPOINT` is set and the collector is reachable
|
|
362
|
+
3. Check the OTEL collector's own logs — it shows if it received spans/logs and where it forwarded them
|
|
363
|
+
|
|
364
|
+
---
|
|
365
|
+
|
|
366
|
+
## Migration — replacing an old vendored eigenh_observe or observability.py
|
|
367
|
+
|
|
368
|
+
If the project has a vendored `eigenh_observe/` directory or a standalone `observability.py`:
|
|
369
|
+
|
|
370
|
+
1. Delete the vendored directory or old file
|
|
371
|
+
2. Install the package (Step 2)
|
|
372
|
+
3. Replace `init()` → `eigenh_observe.init(service_name=..., env=..., instrument_http=True)`
|
|
373
|
+
4. Replace `set_log_context(room, phone, org_id=...)` → `eigenh_observe.set_call_context(call_id=..., org_id=..., caller=...)`
|
|
374
|
+
5. Wrap the agent/session entry point in `with eigenh_observe.session_span():`
|
|
375
|
+
6. Replace `capture_metrics(...)` with `llm_span()` and `capture_tool_calls(...)` with `tool_span()`
|
|
376
|
+
7. Domain-specific event logic (`capture_call_started`, `capture_call_ended`, `capture_error`) stays in the app — not part of this package
|
|
377
|
+
|
|
378
|
+
---
|
|
379
|
+
|
|
380
|
+
## Public API reference
|
|
381
|
+
|
|
382
|
+
```python
|
|
383
|
+
import eigenh_observe
|
|
384
|
+
|
|
385
|
+
# Lifecycle
|
|
386
|
+
eigenh_observe.init(
|
|
387
|
+
*,
|
|
388
|
+
posthog_api_key=None, # str | None — direct PostHog (reads POSTHOG_API_KEY)
|
|
389
|
+
posthog_host=None, # str | None — defaults to https://us.i.posthog.com
|
|
390
|
+
otlp_endpoint=None, # str | None — collector URL (reads OTEL_EXPORTER_OTLP_ENDPOINT)
|
|
391
|
+
# takes precedence over posthog_api_key
|
|
392
|
+
service_name="service", # str
|
|
393
|
+
env="dev", # str
|
|
394
|
+
log_level=logging.INFO, # int
|
|
395
|
+
instrument_http=False, # bool — auto-instrument requests/httpx/aiohttp
|
|
396
|
+
)
|
|
397
|
+
eigenh_observe.shutdown()
|
|
398
|
+
|
|
399
|
+
# FastAPI distributed tracing (call after init)
|
|
400
|
+
eigenh_observe.instrument_fastapi(app) # extracts traceparent from inbound requests
|
|
401
|
+
|
|
402
|
+
# Call/session context
|
|
403
|
+
token = eigenh_observe.set_call_context(call_id="", org_id="", caller="")
|
|
404
|
+
eigenh_observe.reset_call_context(token)
|
|
405
|
+
ctx = eigenh_observe.get_call_context() # → {"call_id": ..., "org_id": ..., "caller": ...}
|
|
406
|
+
|
|
407
|
+
# Attach to an additional logging handler (advanced)
|
|
408
|
+
handler.addFilter(eigenh_observe.CallContextFilter())
|
|
409
|
+
|
|
410
|
+
# Spans — distributed trace tree
|
|
411
|
+
with eigenh_observe.session_span(call_id="", *, org_id="", caller="") as span:
|
|
412
|
+
# root span — all spans inside become children automatically
|
|
413
|
+
|
|
414
|
+
with eigenh_observe.llm_span(model, *, system="google_vertex_ai", operation="chat") as span:
|
|
415
|
+
span.set_usage(input_tokens=N, output_tokens=M)
|
|
416
|
+
span.set_finish_reason("stop")
|
|
417
|
+
span.record_error(exc)
|
|
418
|
+
span.raw # underlying opentelemetry.trace.Span
|
|
419
|
+
|
|
420
|
+
with eigenh_observe.tool_span(tool_name):
|
|
421
|
+
...
|
|
422
|
+
```
|
|
423
|
+
|
|
424
|
+
---
|
|
425
|
+
|
|
426
|
+
## Notes for Claude
|
|
427
|
+
|
|
428
|
+
- **`init()` before everything** — must be called before the first log line or span.
|
|
429
|
+
- **`session_span()` after `set_call_context()`** — context must be set first so session_span reads call_id/org_id/caller automatically from it.
|
|
430
|
+
- **One session_span per call** — do not nest multiple session spans; they create sibling root-level traces, not a deeper tree.
|
|
431
|
+
- **Filter on the handler** — `CallContextFilter` is already wired inside `init()`. Do not add it to the logger — that causes double-stamping.
|
|
432
|
+
- **Re-stamp on shutdown** — LiveKit and similar frameworks run shutdown callbacks in a fresh async context. Always re-call `set_call_context()` at the top of shutdown callbacks.
|
|
433
|
+
- **No PostHog SDK needed** — remove `posthog` from requirements if it was only there for observability.
|
|
434
|
+
- **Domain logic stays in the app** — `call_started`/`call_ended` events, pricing tables, outcome detection are not in this package.
|
|
435
|
+
- **Collector routes, not the app** — the app never knows if the backend is PostHog or Datadog. That decision lives entirely in the OTEL collector config.
|
|
436
|
+
- **PSTN telephony gap** — for voice agents over PSTN/SIP, no `traceparent` header can cross the telephony boundary. `session_span()` starts the root span at the moment the call enters the backend; room-name correlation is the workaround for the inbound leg.
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "eigenh-observe"
|
|
7
|
+
version = "0.4.0"
|
|
8
|
+
description = "EigenH observability — structured logs + AI events + distributed traces"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = { file = "LICENSE" }
|
|
11
|
+
requires-python = ">=3.11"
|
|
12
|
+
dependencies = [
|
|
13
|
+
"posthog>=3.0.0",
|
|
14
|
+
"opentelemetry-api>=1.20.0",
|
|
15
|
+
"opentelemetry-sdk>=1.20.0",
|
|
16
|
+
"opentelemetry-exporter-otlp-proto-http>=1.20.0",
|
|
17
|
+
]
|
|
18
|
+
|
|
19
|
+
[project.optional-dependencies]
|
|
20
|
+
http = [
|
|
21
|
+
"opentelemetry-instrumentation-requests>=0.40b0",
|
|
22
|
+
"opentelemetry-instrumentation-aiohttp-client>=0.40b0",
|
|
23
|
+
"opentelemetry-instrumentation-httpx>=0.40b0",
|
|
24
|
+
]
|
|
25
|
+
fastapi = [
|
|
26
|
+
"opentelemetry-instrumentation-fastapi>=0.40b0",
|
|
27
|
+
]
|
|
28
|
+
dev = [
|
|
29
|
+
"pytest>=7",
|
|
30
|
+
"pytest-asyncio>=0.21",
|
|
31
|
+
]
|
|
32
|
+
|
|
33
|
+
[tool.hatch.build.targets.wheel]
|
|
34
|
+
packages = ["src/eigenh_observe"]
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
from ._core import capture, capture_identify, init, instrument_fastapi, shutdown
|
|
4
|
+
from .context import CallContextFilter, get_call_context, reset_call_context, set_call_context
|
|
5
|
+
from .gen_ai import LlmSpan, close_session_span, llm_span, open_session_span, session_span, tool_span
|
|
6
|
+
|
|
7
|
+
__all__ = [
|
|
8
|
+
# Lifecycle
|
|
9
|
+
"init",
|
|
10
|
+
"shutdown",
|
|
11
|
+
"capture",
|
|
12
|
+
"capture_identify",
|
|
13
|
+
# Call context
|
|
14
|
+
"set_call_context",
|
|
15
|
+
"reset_call_context",
|
|
16
|
+
"get_call_context",
|
|
17
|
+
"CallContextFilter",
|
|
18
|
+
# Spans
|
|
19
|
+
"session_span",
|
|
20
|
+
"open_session_span",
|
|
21
|
+
"close_session_span",
|
|
22
|
+
"llm_span",
|
|
23
|
+
"tool_span",
|
|
24
|
+
"LlmSpan",
|
|
25
|
+
# Distributed tracing — framework wiring
|
|
26
|
+
"instrument_fastapi",
|
|
27
|
+
]
|