API Reference

import { collector } from '@orka-js/collector';
const { tracer, server, stop } = await collector({
  port: 3001,
  host: 'localhost',
  open: true,
  cors: true,
  maxTraces: 1000,
  retentionMs: 24 * 60 * 60 * 1000, // 24 hours
});
// Later, stop the server
await stop();

import { collector } from '@orka-js/collector';
// Start collector with custom configuration
const { tracer, server, stop } = await collector({
  port: 3001,              // Custom port (default: 3001)
  host: 'localhost',       // Custom host (default: 'localhost')
  open: true,              // Auto-open browser (default: false)
  cors: true,              // Enable CORS (default: true)
  maxTraces: 1000,         // Max traces to keep in memory (default: 1000)
  retentionMs: 86400000,   // Trace retention time in ms (default: 24h)
});
console.log(`DevTools running at http://${host}:${port}`);
// Stop the server when done
await stop();

import { collector } from '@orka-js/collector';
// Production: Send traces to remote collector
const { tracer, stop } = await collector({
  source: 'remote',
  mode: 'agent',
  remote: {
    endpoint: 'https://traces.mycompany.com',
    apiKey: process.env.COLLECTOR_API_KEY,
    projectId: 'my-ai-app',
    environment: 'production',
    sampling: 0.1  // Sample 10% of traces
  }
});
// Your app runs normally - traces are sent automatically

import { collector } from '@orka-js/collector';
// Viewer: Watch production traces locally
const { tracer, server, stop } = await collector({
  source: 'remote',
  mode: 'viewer',
  remote: {
    endpoint: 'https://traces.mycompany.com',
    apiKey: process.env.COLLECTOR_API_KEY,
    projectId: 'my-ai-app',
    filters: {
      environment: 'production',
      timeRange: 'last-1h'
    }
  },
  port: 3001,
  open: true
});
// Dashboard at localhost:3001 shows live production traces!

import { trace } from '@orka-js/collector';
const runId = trace.start('llm', 'generate-response', {
  prompt: 'Hello, world!'
}, {
  model: 'gpt-4',
  temperature: 0.7
});
// ... do work ...
trace.end(runId, { content: 'Response text' });

import { trace } from '@orka-js/collector';
const runId = trace.start('llm', 'generate', { prompt: 'Hello' });
// ... perform operation ...
const result = await llm.generate('Hello');
// End the trace with output
trace.end(runId, { content: result.content }, {
  promptTokens: result.usage.promptTokens,
  completionTokens: result.usage.completionTokens,
  model: 'gpt-4'
});

import { trace } from '@orka-js/collector';
const runId = trace.start('tool', 'web-search', { query: 'AI news' });
try {
  const results = await searchTool.execute({ query: 'AI news' });
  trace.end(runId, results);
} catch (error) {
  // Record the error
  trace.error(runId, error, {
    toolName: 'web-search',
    retryCount: 3
  });
}

import { trace } from '@orka-js/collector';
const result = await trace.wrap('agent', 'research', async () => {
  const agent = new ReActAgent({ llm, tools });
  return agent.run("Analyze market trends");
}, {
  model: 'gpt-4',
  userId: 'user-123'
});

import { trace } from '@orka-js/collector';
// Start a session for a user request
const sessionId = trace.session('User Request #123', {
  userId: 'user-456',
  requestType: 'research'
});
// All traces within this session are grouped
await trace.wrap('agent', 'step1', async () => {
  return agent.analyze(input);
});
await trace.wrap('agent', 'step2', async () => {
  return agent.synthesize(results);
});
// End the session
trace.endSession(sessionId);

import { Trace } from '@orka-js/collector';
class MyAgent {
  @Trace({ type: 'agent', name: 'process' })
  async process(input: string) {
    // Automatically traced
    return this.llm.generate(input);
  }
  @Trace({ type: 'llm' }) // name defaults to method name
  async generateResponse(prompt: string) {
    return this.llm.generate(prompt);
  }
}

import { withTrace } from '@orka-js/collector';
// Wrap a function with tracing
const tracedGenerate = withTrace(
  async (prompt: string) => {
    return llm.generate(prompt);
  },
  { type: 'llm', name: 'generate' }
);
// Use the traced function
const result = await tracedGenerate('Hello, world!');
// Works with any async function
const tracedSearch = withTrace(searchTool.execute, {
  type: 'tool',
  name: 'web-search'
});

import { Tracer } from '@orka-js/observability';
import { createDevToolsHook, collector } from '@orka-js/collector';
// Start collector first
await collector();
// Create tracer with DevTools hook
const tracer = new Tracer({
  hooks: [createDevToolsHook()]
});
// All tracer events now appear in DevTools
const trace = tracer.startTrace('my-operation');
tracer.addEvent(trace.id, { type: 'llm', name: 'generate' });
tracer.endTrace(trace.id);

import { getCollector } from '@orka-js/collector';
const tracer = getCollector();
// Get all sessions
const sessions = tracer.getSessions();
console.log(`Total sessions: ${sessions.length}`);
// Get metrics summary
const metrics = tracer.getMetrics();
console.log(`Total runs: ${metrics.totalRuns}`);
console.log(`Avg latency: ${metrics.avgLatencyMs}ms`);
console.log(`Error rate: ${metrics.errorRate * 100}%`);
// Find a specific session
const session = sessions.find(s => s.name === 'User Request #123');
// Export traces as JSON
const exportData = tracer.export();
fs.writeFileSync('traces.json', JSON.stringify(exportData, null, 2));
// Import traces
tracer.import(JSON.parse(fs.readFileSync('traces.json', 'utf-8')));
// Clear all traces
tracer.clear();