feat(agent): export cloud run telemetry to PostHog Logs and APM over OTLP

Adds OtelRunTelemetry, a SessionLogWriter sink that ships an allowlisted
metadata subset of the session log (run/turn/tool lifecycle, usage, errors;
never message content or tool arguments) to PostHog Logs, and, when a traces
URL is configured, builds one APM trace per run (task_run root span, a turn
span per prompt, a tool_call:<kind> span per tool call) with trace/span ids
stamped on log records so Logs and APM cross-link.

Resource attributes carry run_id/task_id/team_id/user_id/distinct_id so cloud
runs are filterable per user in the Logs UI. Configured via
POSTHOG_AGENT_OTEL_LOGS_URL/_TOKEN (+ optional POSTHOG_AGENT_OTEL_TRACES_URL),
deliberately not standard OTEL_* names so OTel SDKs in user code running in
the sandbox never auto-export into the telemetry project. Telemetry stays off
unless the logs pair is set, flushes on session cleanup/terminal errors, and
can never break session log persistence (sink failures are isolated).

Replaces the unwired otel-log-writer whose default endpoint
(/i/v1/agent-logs) does not exist in the ingest service, and removes the dead
AgentConfig.otelTransport field.

Generated-By: PostHog Code
Task-Id: 0c511836-2180-455a-9b58-45df2a0661ec

Author: tatoalo

packages/agent/README.md

@@ -166,6 +166,14 @@ Required environment variables (validated by zod in `src/server/bin.ts`):
 - `POSTHOG_PERSONAL_API_KEY` — API key for PostHog requests
 - `POSTHOG_PROJECT_ID` — numeric project ID
 
+Optional run telemetry (the logs pair must both be set, otherwise telemetry stays off):
+
+- `POSTHOG_AGENT_OTEL_LOGS_URL` — full OTLP logs URL for run metadata, e.g. `https://us.i.posthog.com/i/v1/logs`
+- `POSTHOG_AGENT_OTEL_LOGS_TOKEN` — project API key of the telemetry project
+- `POSTHOG_AGENT_OTEL_TRACES_URL` — full OTLP traces URL, e.g. `https://us.i.posthog.com/i/v1/traces`; additionally enables one APM trace per run
+
+When set, `AgentServer` ships an allowlisted metadata subset of the session log (run/turn/tool lifecycle, usage, errors — never message content or tool arguments; see `src/otel-telemetry.ts`) to PostHog Logs, tagged with `service.name=posthog-code-agent` and `run_id`/`task_id`/`team_id`/`user_id`/`distinct_id` resource attributes so cloud runs are filterable per user. With the traces URL set, each run also produces an APM trace (`task_run` root span, a `turn` span per prompt, a `tool_call:<kind>` span per tool call; see `src/otel-trace-builder.ts`), and log records carry the matching trace/span ids so Logs and APM cross-link.
+
 ## Agent SDK
 
 The `Agent` class (`src/agent.ts`) is the entrypoint for local/programmatic usage. It handles LLM gateway configuration, log writer setup, and model filtering — then delegates to `createAcpConnection()`.

packages/agent/package.json

@@ -117,9 +117,9 @@
     "node": ">=20.0.0"
   },
   "devDependencies": {
-    "@posthog/shared": "workspace:*",
-    "@posthog/git": "workspace:*",
     "@posthog/enricher": "workspace:*",
+    "@posthog/git": "workspace:*",
+    "@posthog/shared": "workspace:*",
     "@types/bun": "latest",
     "@types/tar": "^6.1.13",
     "msw": "^2.12.7",
@@ -133,19 +133,22 @@
     "@anthropic-ai/claude-agent-sdk": "0.3.197",
     "@anthropic-ai/sdk": "0.109.0",
     "@hono/node-server": "^1.19.9",
+    "@modelcontextprotocol/sdk": "1.29.0",
     "@openai/codex": "0.140.0",
+    "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/api-logs": "^0.208.0",
     "@opentelemetry/exporter-logs-otlp-http": "^0.208.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.208.0",
     "@opentelemetry/resources": "^2.0.0",
     "@opentelemetry/sdk-logs": "^0.208.0",
+    "@opentelemetry/sdk-trace-base": "^2.8.0",
     "@opentelemetry/semantic-conventions": "^1.28.0",
     "@types/jsonwebtoken": "^9.0.10",
     "commander": "^14.0.2",
     "fflate": "^0.8.2",
     "hono": "^4.11.7",
     "jsonwebtoken": "^9.0.2",
     "minimatch": "^10.0.3",
-    "@modelcontextprotocol/sdk": "1.29.0",
     "tar": "^7.5.0",
     "uuid": "13.0.0",
     "yoga-wasm-web": "^0.3.3",

packages/agent/src/otel-attributes.ts

@@ -0,0 +1,61 @@
+const MAX_BODY_CHARS = 2000;
+// PostHog Logs only facets attribute key/value pairs shorter than 256 chars,
+// so free-text attribute values are capped well below that.
+const MAX_ATTR_CHARS = 200;
+
+export type AttributeValue = string | number | boolean;
+export type Attributes = Record<string, AttributeValue>;
+
+export { MAX_ATTR_CHARS, MAX_BODY_CHARS };
+
+export function truncate(value: string, max: number): string {
+  return value.length <= max ? value : `${value.slice(0, max)}…`;
+}
+
+export function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+export function strAttr(
+  attrs: Attributes,
+  key: string,
+  value: unknown,
+  max = MAX_ATTR_CHARS,
+): string | undefined {
+  if (typeof value !== "string" || value.length === 0) return undefined;
+  const truncated = truncate(value, max);
+  attrs[key] = truncated;
+  return truncated;
+}
+
+export function numAttr(attrs: Attributes, key: string, value: unknown): void {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    attrs[key] = value;
+  }
+}
+
+export function usageAttributes(params: Record<string, unknown>): Attributes {
+  const attrs: Attributes = {};
+  const used = asRecord(params.used);
+  if (used) {
+    numAttr(attrs, "tokens_input", used.inputTokens);
+    numAttr(attrs, "tokens_output", used.outputTokens);
+    numAttr(attrs, "tokens_cached_read", used.cachedReadTokens);
+    numAttr(attrs, "tokens_cached_write", used.cachedWriteTokens);
+  }
+  // Claude sends a plain number; other shapes carry { amount }.
+  const cost =
+    typeof params.cost === "number"
+      ? params.cost
+      : asRecord(params.cost)?.amount;
+  numAttr(attrs, "cost_usd", cost);
+  return attrs;
+}
+
+/** Timestamp of a stored entry as a Date, falling back to now when invalid. */
+export function entryTime(timestamp: string): Date {
+  const parsed = new Date(timestamp);
+  return Number.isNaN(parsed.getTime()) ? new Date() : parsed;
+}