@agentlair/telemetry

Drop-in behavioral telemetry for AI agents. 3-line integration, local SQLite storage, framework-agnostic.

Not governance. Not blocking. Pure observability. This is the sensor layer that feeds AgentLair's trust scoring.

Quick Start

import { telemetry } from '@agentlair/telemetry';

await telemetry.start({ agent: 'my-agent' });
// That's it — HTTP calls are auto-instrumented, events stored in local SQLite

What It Captures

| Category | Examples | |----------|----------| | tool_call | Tool invocations with input/output/duration | | llm_request / llm_response | Model calls, token usage, latency | | http_request | All fetch() calls (auto-instrumented) | | file_write / file_read | File system operations | | error | Failures with stack context | | agent_start / agent_stop | Session lifecycle |

Installation

npm install @agentlair/telemetry
# or
bun add @agentlair/telemetry

SQLite storage works out of the box with Bun. For Node.js, install better-sqlite3:

npm install better-sqlite3

Manual Instrumentation

import { telemetry } from '@agentlair/telemetry';

await telemetry.start({ agent: 'researcher' });

// Instrument any async operation
const results = await telemetry.instrument('tool_call', 'web_search', async () => {
  return await searchWeb(query);
}, { input: query });

// Record custom events
await telemetry.record({
  category: 'custom',
  action: 'decision',
  success: true,
  metadata: { reason: 'switching strategy' },
});

// Query and analyze
const stats = await telemetry.stats();
console.log(`Error rate: ${(stats.errorRate * 100).toFixed(1)}%`);
console.log('Top tools:', stats.topActions);

// Cleanup
await telemetry.stop();

Framework Adapters

Anthropic SDK

import Anthropic from '@anthropic-ai/sdk';
import { instrumentAnthropicClient } from '@agentlair/telemetry/anthropic';

const client = instrumentAnthropicClient(new Anthropic(), { agent: 'researcher' });

// Use normally — telemetry is automatic
const msg = await client.messages.create({
  model: 'claude-opus-4-5',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello' }],
});

// Access telemetry data
const stats = await client.telemetry.stats();

Mastra

import { Agent } from '@mastra/core';
import { withTelemetry } from '@agentlair/telemetry/mastra';

const agent = withTelemetry(
  new Agent({ name: 'researcher', tools: { ... } }),
  { agent: 'researcher' },
);

// Or use middleware
import { telemetryMiddleware } from '@agentlair/telemetry/mastra';

const agent = new Agent({
  middleware: [telemetryMiddleware({ agent: 'researcher' })],
});

Generic (Any Framework)

import { TelemetryCollector } from '@agentlair/telemetry';

const collector = new TelemetryCollector({ agent: 'my-agent' });
await collector.start();

// Wrap your agent's tool execution
async function executeTool(name: string, input: unknown) {
  return collector.instrument('tool_call', name, async () => {
    return await tools[name].execute(input);
  }, { input });
}

Querying Telemetry

import { queryTelemetry, queryStats } from '@agentlair/telemetry/query';

// Find slow tool calls
const slow = await queryTelemetry({
  category: 'tool_call',
  minDurationMs: 5000,
});

// Get error stats for the last hour
const stats = await queryStats({
  after: new Date(Date.now() - 3600_000).toISOString(),
});

Storage Backends

SQLite (default)

import { SQLiteStorage } from '@agentlair/telemetry';

await telemetry.start({
  agent: 'my-agent',
  storage: new SQLiteStorage({ path: './my-telemetry.db', maxEvents: 50_000 }),
});

In-Memory

import { MemoryStorage } from '@agentlair/telemetry';

await telemetry.start({
  agent: 'my-agent',
  storage: new MemoryStorage(),
});

AgentLair Cloud Sync

Local-first with async cloud upload:

import { SQLiteStorage, AgentLairSync } from '@agentlair/telemetry';

await telemetry.start({
  agent: 'my-agent',
  storage: new AgentLairSync({
    local: new SQLiteStorage(),
    apiKey: process.env.AGENTLAIR_API_KEY!,
  }),
});

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | agent | string | required | Agent name/identifier | | sessionId | string | auto-generated | Session identifier | | storage | StorageBackend | SQLite (or Memory) | Storage backend | | apiKey | string | - | AgentLair API key for cloud sync | | bufferSize | number | 100 | Events buffered before flush | | flushIntervalMs | number | 5000 | Auto-flush interval | | console | boolean | false | Print events to console | | instrumentFetch | boolean | true | Auto-instrument global fetch | | maxSummaryLength | number | 200 | Max chars for input/output |

Privacy

• Input/output values are truncated to maxSummaryLength (default 200 chars)
• No raw prompts or completions stored by default
• Local SQLite storage — your data stays on your machine
• Cloud sync is opt-in and uses your AgentLair API key

License

MIT