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.
@@ -0,0 +1,8 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.pyc
4
+ *.pyo
5
+ .pytest_cache/
6
+ dist/
7
+ *.egg-info/
8
+ .env
@@ -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
+ ]