apowerb/th2pulse repository overview

⁠th2pulse

A lightweight OpenTelemetry collection and observability library for the apowerb stack.

Documentation⁠ • apowerb⁠ • thaink2⁠

A lightweight OpenTelemetry collection and observability library for th2 applications (apowerb, th2llm, th2etl).

⁠Why

Google ADK (>= 1.36) wires its own OpenTelemetry providers from environment variables and exports rich agent telemetry out of the box: hierarchical spans (invoke_agent → call_llm → generate_content, execute_tool), five native agent metrics, and GenAI event logs — every span tagged with gen_ai.conversation.id and user.id.

What ADK does not do (measured on a real service): bridge standard Python logging records — FastAPI, application code, integrations — to the collector. th2pulse closes that gap with one call, and keeps the whole wiring consistent across th2 services.

⁠Quickstart

export OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:4318"   # HTTP port!
export OTEL_SERVICE_NAME="my-service"

import th2pulse

th2pulse.init_observability("my-service")

That's it. Every logging record at INFO+ now reaches the collector, correlated with active traces (trace_id is injected automatically).

⁠In an ADK app

Call after the ADK app is built so the bridge reuses the provider ADK installed (ADK's own telemetry is already flowing at that point):

app = get_fast_api_app(...)
th2pulse.init_observability("apowerb")

⁠In a plain FastAPI service / worker / script

init_observability installs the logs provider itself. For short-lived scripts, flush before exiting:

th2pulse.init_observability("my-batch")
...
th2pulse.force_flush()

⁠Redacting sensitive content

th2pulse.init_observability(
    "my-service",
    redaction_patterns=[r"Bearer [A-Za-z0-9._-]+", r"api[_-]?key=\S+"],
)

Scrubbing applies to what leaves the process; console output is untouched. Prompt/response content is never captured by default (OTel GenAI redaction).

⁠Correlating non-ADK telemetry with a conversation

from th2pulse import conversation_context

with conversation_context(session_id, user_id=email):
    ...  # spans/logs emitted here join the conversation

Bridged log records emitted inside the context also carry gen_ai.conversation.id / user.id as OTLP log attributes (stamped from baggage by BaggageLogFilter, wired automatically). A log store can therefore filter application logs per conversation directly — no conversation↔trace mapping required. Stores that normalize attribute names (e.g. Loki structured metadata) expose them as gen_ai_conversation_id / user_id.

⁠Ingest service (collector → PostgreSQL → query API)

th2pulse.ingest is the storage/query half of the pipeline: an OTLP/HTTP receiver that persists log records and the conversation ↔ trace mapping in PostgreSQL, then serves them per conversation to the monitoring frontend.

agents / services ──OTLP──▶ collector ──otlphttp (encoding: json)──▶ th2pulse.ingest ──▶ PostgreSQL
                                                                         │
                                                     front ◀── GET /logs?conversation_id=...

Point the collector at it:

exporters:
  otlphttp/pulse:
    endpoint: http://127.0.0.1:4319
    encoding: json          # required — the ingest speaks OTLP/JSON only
service:
  pipelines:
    logs:   { receivers: [otlp], processors: [batch], exporters: [otlphttp/pulse] }
    traces: { receivers: [otlp], processors: [batch], exporters: [otlphttp/pulse] }

Run it:

pip install "th2pulse[ingest]"
export TH2PULSE_DB_DSN="postgresql://user:pass@host:5432/db?sslmode=require"
export TH2PULSE_DB_SCHEMA="my_schema"        # optional, created if absent
python -m th2pulse.ingest                     # 127.0.0.1:4319

Endpoints:

Writes are transactional per payload (a collector retry after a failure cannot duplicate committed rows) and span inserts are idempotent (ON CONFLICT DO NOTHING), so replaying an OTLP export is safe. user_id narrows every query to one user's conversations — callers doing authorization (e.g. a frontend proxy) should inject it server-side from a verified identity, never from client input. Set TH2PULSE_INGEST_TOKEN and the POST endpoints require a matching X-Th2Pulse-Token header; TH2PULSE_QUERY_TOKEN does the same for the read side. Payloads are capped (10 MB raw, 32 MB decompressed).

Both tokens are optional while the bind stays on loopback, where the socket is the boundary. On any other bind address they are not: the service refuses to start with TH2PULSE_INGEST_HOST set to something reachable and either token missing, rather than quietly serving conversation logs and recorded tool arguments to whoever reaches the port. Set TH2PULSE_ALLOW_UNAUTHENTICATED=1 to state that authorization is handled upstream (a reverse proxy, a private network).

⁠Docker

docker run -p 4319:4319 \
  -e TH2PULSE_DB_DSN="postgresql://user:pass@host:5432/db" \
  -e TH2PULSE_INGEST_TOKEN="..." -e TH2PULSE_QUERY_TOKEN="..." \
  apowerb/th2pulse:latest

The image binds 0.0.0.0:4319 — a container's loopback reaches nothing — which is why the tokens above are not optional here. It installs the published release matching its tag, so apowerb/th2pulse:0.1.3 contains th2pulse 0.1.3; it is not built from the working tree. To run a local change, run the service directly instead: uv run --extra ingest python -m th2pulse.ingest.

The conversation map is built from gen_ai.conversation.id / user.id attributes — on spans (where ADK puts them natively) and on log records (where conversation_context propagates them).

⁠Environment variables

⁠Guarantees

• Opt-in: without an endpoint, init_observability is a no-op.
• Never breaks the host app: every entry point is best-effort — on failure it warns and returns False.
• Idempotent: repeated calls attach a single handler.
• No secrets, no prompts: nothing sensitive is captured by default.

⁠Development

uv sync
uv run pytest

⁠Roadmap

• Traces/metrics bootstrap for non-ADK services (FastAPI instrumentation).
• Span storage + retention policies in the ingest service.
• Structured redaction presets shared across th2 services.

⁠License

th2pulse is distributed under the Apache License 2.0⁠. Copyright 2025-2026 thaink².

"apowerb" and "thaink²" are trademarks of thaink². The licence covers the code, not the marks — see TRADEMARK.md⁠.