veloscope

Lightweight AI agent observability — traces, quality scores, and cost tracking in 2 lines.

const veloscope = require('veloscope');
veloscope.init({ apiKey: 'vs_...' });

Installation

npm install veloscope

Quick Start

const { init, trace, span } = require('veloscope');

init({ apiKey: 'vs_your_key_here' }); // or set VELOSCOPE_API_KEY env var

const runAgent = trace('my-agent', async (query) => {
  const docs = await retrieveDocs(query);
  return generateAnswer(docs);
});

const retrieveDocs = span('retrieve-docs', async (query) => {
  // ...
}, 'tool');

API

init({ apiKey?, apiUrl? })

Initialize the SDK. Call once at startup. If no key is provided (and VELOSCOPE_API_KEY is not set), the SDK silently no-ops.

trace(name, fn)

Wraps an async function as the root of a trace. Each call creates a new trace ID.

span(name, fn, spanType?)

Wraps an async function as a span within the current trace. Must be called inside a trace-wrapped function. Orphan spans (no active trace) run normally without instrumentation.

spanType values: "llm", "tool", "retrieval", "custom" (default)

flush()

Manually flush all buffered spans. Called automatically every 5 seconds and on process exit.

License

MIT