Observability

PAI can record spans for runs, model steps, tool execution, and failures. Use it when you need to see what an agent did, not only what it said.

Logging a request failure does not require OpenTelemetry. Use logger / onRuntimeError / onHttpError — see Errors.

Configure telemetry

pnpm add @pai/observability

server/telemetry.ts

import { createPaiOpenTelemetry } from "@pai/observability";

export const telemetry = createPaiOpenTelemetry({
  serviceName: "assistant-api",
  contentCapture: {
    recordRunInputs: false,
    recordRunOutputs: false,
    recordModelOutputs: false,
    recordToolInputs: false,
    recordToolOutputs: false,
    recordToolData: false,
    recordErrorDetails: false,
  },
});

const pai = createPai({
  agents: { main: assistantAgent },
  telemetry,
  scopeKey: (identity) => identity.workspaceId,
  userKey: (identity) => identity.userId,
  telemetryAttributes: ({ identity, userKey }) => ({
    "app.user.id": userKey,
    "app.workspace.id": identity.workspaceId,
  }),
});

Every content-capture flag defaults to false. Enable a field only after you are sure that sink may retain user content.

contentCapture: true turns all of them on, including raw error details. Prefer the object form.

Provider-reported token usage is recorded independently of content capture. Model spans include gen_ai.usage.input_tokens and gen_ai.usage.output_tokens, plus cache-read, cache-creation, and reasoning counts when the provider supplies them. Input totals include cached tokens; output totals include reasoning.

Langfuse

pnpm add @pai/langfuse

import { createLangfuseSpanProcessor } from "@pai/langfuse";
import { createPaiOpenTelemetry } from "@pai/observability";

const langfuse = createLangfuseSpanProcessor("env");

export const telemetry = createPaiOpenTelemetry({
  serviceName: "assistant-api",
  contentCapture: {
    recordRunInputs: true,
    recordRunOutputs: true,
    recordModelOutputs: true,
  },
  spanProcessors: langfuse ? [langfuse] : [],
});

For "env", set PAI_LANGFUSE_PUBLIC_KEY and PAI_LANGFUSE_SECRET_KEY. PAI_LANGFUSE_BASE_URL defaults to http://localhost:7320.

Observability

Configure telemetry

Langfuse

Next

On this page