kindred-tracer-node

Kindred Tracer SDK for Node.js - Auto-instrumentation for AI agents.

This package automatically intercepts HTTP/HTTPS requests from your AI agent, categorizes them as LLM calls or tool executions, and exports logs to the Kindred log-search system.

Installation

npm install kindred-tracer-node
# or
pnpm add kindred-tracer-node

Usage

Basic Usage

Just call kindredTracer() once at startup, and all HTTP requests will be automatically intercepted and logged:

import { kindredTracer } from 'kindred-tracer-node';

// At startup - initialize the tracer
kindredTracer();

// Your agent code here - no wrapping needed!
// All HTTP requests will be automatically logged
const response = await fetch('https://api.openai.com/v1/chat/completions', {
  method: 'POST',
  body: JSON.stringify({ /* ... */ })
});

Configuration

Set the following environment variables:

• KINDRED_API_KEY (required) - Your Kindred API key for authentication
• KINDRED_API_URL (optional) - Base URL for Kindred API, defaults to https://api.usekindred.dev
• KINDRED_SESSION_ID (optional) - Session identifier. If not set, a UUID will be auto-generated
• KINDRED_AGENT_ID (optional) - Agent identifier
• KINDRED_RUN_ID (optional) - Run identifier

You can also pass these values directly to kindredTracer():

import { kindredTracer } from 'kindred-tracer-node';

// Initialize with explicit values
kindredTracer('session-123', 'agent-456', 'run-789');

How It Works

1. Simple Initialization: Call kindredTracer() once at startup to set up global context and enable interception.

2. Auto-instrumentation: The tracer automatically patches Node.js's https.request and http.request when initialized.

3. Global Context: Uses a global context that applies to all HTTP requests after initialization.

4. Request Detection:

   • LLM Calls: Detected by hostname (e.g., api.openai.com, api.anthropic.com) → logged as role: "agent"
   • Tool Calls: Any other hostname → logged as role: "tool"

5. Streaming Support: Handles streaming responses correctly - chunks are passed through immediately (zero latency) while being buffered for logging.

6. Non-blocking Export: Logs are batched and exported asynchronously to avoid slowing down your agent.

Log Format

Logs are automatically formatted and sent to ${KINDRED_API_URL}/api/logs/ingest with the following structure:

{
  session_id: string;
  timestamp: string; // ISO 8601
  role: "user" | "agent" | "tool" | "system";
  content: string;
  agent_id?: string;
  run_id?: string;
  meta?: {
    type: "llm_generation" | "tool_execution";
    request_id: string;
    host: string;
    method: string;
    path: string;
    request_headers: Record<string, unknown>;
    request_body: string | null;
    response_status: number;
    response_headers: Record<string, unknown>;
    response_body: string | null;
    duration_ms: number;
    tool_calls?: Array<{...}>; // Extracted from OpenAI responses
  };
}

Flushing Logs

Before shutting down your application, you can flush any pending logs:

import { flushLogs } from 'kindred-tracer-node';

// On shutdown
await flushLogs();

Security

The tracer automatically sanitizes sensitive headers before logging:

• Authorization
• x-api-key
• api-key
• x-auth-token
• cookie

Supported LLM Providers

The tracer automatically detects requests to:

• OpenAI (api.openai.com)
• Anthropic (api.anthropic.com)
• Google Gemini (generativelanguage.googleapis.com)
• Cohere (api.cohere.com)
• Mistral (api.mistral.ai)

Example

Here's a complete example:

import { kindredTracer, flushLogs } from 'kindred-tracer-node';

// Set your API key
process.env.KINDRED_API_KEY = 'your-api-key-here';

// Initialize the tracer (reads sessionId from KINDRED_SESSION_ID env var, or auto-generates)
kindredTracer();

// Your agent code - all HTTP requests are automatically logged
const response = await fetch('https://api.openai.com/v1/chat/completions', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    model: 'gpt-4',
    messages: [{ role: 'user', content: 'Hello!' }]
  })
});

// Before shutdown, flush any pending logs
await flushLogs();

License

MIT