@amaster.ai/pi-telemetry

Runtime telemetry contracts and exporters for pi.

Uses the official Langfuse JS v5 and OpenTelemetry SDKs. Langfuse export runs through @langfuse/tracing and @langfuse/otel; generic OTLP export uses OTLPTraceExporter. Requests time out after 15 seconds and lifecycle flushes are capped at 30 seconds.

Entry Points

• @amaster.ai/pi-telemetry: stable contracts, NoopRuntimeEventExporter, and CompositeRuntimeEventExporter.
• @amaster.ai/pi-telemetry/config: TelemetryConfig type, resolveConfig, and loadConfigFromFile.
• @amaster.ai/pi-telemetry/langfuse: Langfuse JS v5 exporter using @langfuse/tracing and @langfuse/otel.
• @amaster.ai/pi-telemetry/otel: generic OTLP/HTTP traces exporter.

Events

The extension hooks into the following Pi lifecycle events:

| Event | Telemetry action | |-------|-----------------| | session_start | Initialize exporters from config | | input | Start a new trace (traceId boundary = user input) | | turn_start | Begin the root or subagent span on the first turn | | before_provider_request | Begin an LLM generation span and record model input | | after_provider_response | Mark failed provider responses | | message_update | Record provider stream events beneath the active LLM generation | | agent_end | Complete the root or subagent span once per user prompt | | tool_execution_start | Begin tool span | | tool_execution_end | End tool span with result | | message_end | Complete an LLM generation span with output and usage | | model_select | Record model switch events | | session_compact | Record context compaction events | | session_shutdown | Flush and shutdown exporters |

Trace lifecycle

Traces are scoped to user input boundaries (not individual turns). A single user message may trigger multiple LLM turns and tool calls — all grouped under one trace and completed once on agent_end.

Langfuse traces carry the configured serviceName as resource/metadata attributes and langfuse.session.id on every span so shared projects can filter traces by runtime and session. The extension also adds taskRunId correlation metadata when PI_TELEMETRY_TASK_RUN_ID is present.

Configuration

Configuration is read from the "pi-telemetry" section of, in increasing priority, ~/.pi/agent/settings.json, the configured agent directory's settings.json (for example $PI_CODING_AGENT_DIR/settings.json), and a trusted project's .pi/settings.json. Project settings are ignored when project trust is declined. Environment variables are expanded only in user and agent-directory settings.

{
  "pi-telemetry": {
    "serviceName": "my-service",
    "serviceVersion": "1.0.0",
    "includePayloads": true,
    "langfuse": {
      "enabled": true,
      "publicKey": "pk-lf-...",
      "secretKey": "sk-lf-...",
      "baseUrl": "https://cloud.langfuse.com",
      "flushAt": 20,
      "flushIntervalMs": 5000
    },
    "otel": {
      "enabled": true,
      "endpoint": "https://otel-collector.example.com",
      "headers": { "Authorization": "Bearer ..." },
      "flushAt": 20,
      "flushIntervalMs": 5000
    }
  }
}

Config Fields

| Field | Type | Default | Description | |-------|------|---------|-------------| | serviceName | string | "pi-server" | Service name for traces | | serviceVersion | string | — | Service version for traces | | includePayloads | boolean | false | Include chat payloads, tool args, LLM I/O |

Langfuse Config

| Field | Type | Default | Description | |-------|------|---------|-------------| | enabled | boolean | false | Enable Langfuse exporter | | publicKey | string | — | Langfuse public API key | | secretKey | string | — | Langfuse secret API key | | baseUrl | string | "https://cloud.langfuse.com" | Langfuse server URL | | flushAt | number | 20 | Batch size before flush | | flushIntervalMs | number | 5000 | Flush interval in ms |

OTEL Config

| Field | Type | Default | Description | |-------|------|---------|-------------| | enabled | boolean | false | Enable OTEL exporter | | endpoint | string | — | OTLP traces endpoint | | headers | Record<string, string> | — | Request headers | | flushAt | number | 20 | Batch size before flush | | flushIntervalMs | number | 5000 | Flush interval in ms |

When the endpoint does not end with /v1/traces, the exporter appends /v1/traces.

Programmatic Usage

import { loadConfigFromFile, resolveConfig } from "@amaster.ai/pi-telemetry/config";
import { createTelemetryExporter } from "@amaster.ai/pi-telemetry/otel";

const config = resolveConfig(loadConfigFromFile());
const telemetry = createTelemetryExporter(config); // one provider for both destinations

Privacy

Runtime events omit user prompts, assistant responses, tool arguments, tool outputs, and model inputs/outputs by default. Set includePayloads: true to include them. For finer control, construct an exporter directly and pass redactEvent.