JavaScript / TypeScript SDK

@trefur/observe — observability and safety telemetry for AI agents, with auto-instrumentation for popular AI SDKs.

Install

npm install @trefur/observe

Init

import OpenAI from 'openai';
import { TrefurObserve, patchOpenAI } from '@trefur/observe';

TrefurObserve.init({
  apiKey: process.env.TREFUR_API_KEY!,
  agent: { name: process.env.TREFUR_AGENT_NAME ?? 'my-agent' },
});

const openai = new OpenAI();
patchOpenAI(OpenAI, TrefurObserve.getInstance());

TrefurObserve.init(config) is the canonical entry point. Direct construction via new TrefurObserve(...) is not supported.

Configuration options

Option	Type	Default	Notes
`apiKey`	`string`	required	`trf_obs_*`
`endpoint`	`string`	`https://observe.trefur.com`	Ingest endpoint override
`debug`	`boolean`	`false`	Verbose console logging
`batchSize`	`number`	`10`	Buffer size before auto-flush
`flushIntervalMs`	`number`	`5000`	Periodic flush interval
`autoInstrument`	`boolean`	`true`	Auto-patch known SDKs at init
`sql`	`boolean`	`false`	Opt-in auto-patch of SQL drivers (`pg`, `mysql2`, `sqlite3`, `postgres`, `better-sqlite3`)
`captureSubprocess`	`boolean`	`true`	Patch `child_process` for CLI captures
`subprocessFilter`	`string[]`	all	Limit captures to specific binary names
`agent`	`{ id?, name?, framework? }`	detected	Explicit agent identity
`onError`	`(err, ctx) => void`	none	Recommended for production — invoked on every ingest failure

Framework adapters

With autoInstrument: true (default), supported SDKs are patched on first import. You can also call the named patch helpers explicitly:

import {
  patchAnthropic,
  patchOpenAI,
  patchGemini,
  patchLangChain,
  patchVercelAI,
  patchCrewAI,
  patchLlamaIndex,
  patchLangGraph,
  patchMistral,
  patchBedrock,
  patchClaudeAgentSDK,
  patchOpenAIAgents,
  patchBedrockAgents,
  patchPlaywright,
  patchPuppeteer,
} from '@trefur/observe';

// Server-side MCP instrumentation (for agents that ARE MCP servers):
import { instrumentTool, wrapMcpServer } from '@trefur/observe';

// [COMING SOON] Mastra dedicated adapter — for now, use patchVercelAI or
// the generic in-process instrumentors below.

Every adapter is observe-only. The SDK captures telemetry without intercepting or modifying calls. The full exported surface lives in packages/observe-js/src/index.ts.

Generic in-process instrumentors

For HTTP, fetch, axios, fs, and subprocess calls that don't go through an AI SDK:

const observe = TrefurObserve.init({ apiKey: process.env.TREFUR_API_KEY! });

observe.observe({
  http: true,          // http.request / http.get + https
  fetch: true,         // global fetch (Node 18+) + undici
  axios: true,         // request + response + error interceptors
  fs: true,            // fs.promises read/write/unlink/...
  child_process: true, // exec / execFile / spawn / sync variants
});

Environment variables

The SDK reads a small set of TREFUR_* variables. See the env-vars reference for the canonical list (this is shared across all SDKs).

Troubleshooting

Symptom	Fix
SDK appears to do nothing.	Check `TREFUR_DISABLED` isn't set. Wire `onError` to surface failures. Make sure `TrefurObserve.init` is awaited / runs before your first agent call.
Streaming responses missing tokens.	Make sure you imported the patch helper before constructing the LLM client. Auto-instrument patches the constructor.
Bundler complains about `@google/genai`.	If your bundler froze the namespace, call `patchGeminiClient(client, observe)` per constructed client.
I see redacted brackets where I expect data.	The redactor strips sensitive query params (`api_key`, `token`, …) by default. Adjust prompt-capture mode in the dashboard if you need raw content.

Source + tests live in trefur-ai/trefur-sdks under packages/observe-js. License: Apache 2.0.