JavaScript SDK

The SideSeat JavaScript SDK (@sideseat/sdk) provides OpenTelemetry instrumentation for Node.js applications with automatic configuration and OTLP export. Stream runs into the local AI development workbench while you iterate locally.

What you’ll learn:

• Install and configure the JavaScript SDK
• Use environment variables for configuration
• Enable debug mode and custom endpoints

Prerequisites

• SideSeat running locally (sideseat)
• Node.js 18+

Installation

npm install @sideseat/sdk

Or with your package manager:

npm

npm install @sideseat/sdk

yarn

yarn add @sideseat/sdk

pnpm

pnpm add @sideseat/sdk

Quick Start

Add one line at the top of your entry point:

import { init } from '@sideseat/sdk';
init();

// Your existing code
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

const { text } = await generateText({
  model: openai('gpt-5-mini'),
  prompt: 'Hello!',
  experimental_telemetry: { isEnabled: true },
});

That’s it. Runs flow to SideSeat at http://localhost:5388.

Features

Zero Configuration

The SDK works out of the box with sensible defaults:

• Sends to http://127.0.0.1:5388
• Uses default project
• Auto-detects service name from package.json

Idempotent Initialization

Safe to call multiple times:

init();  // Initializes
init();  // No-op (already initialized)

Framework Selection

Explicitly select a framework for instrumentation:

import { init, Frameworks } from '@sideseat/sdk';

init({ framework: Frameworks.VercelAI });

Available frameworks: Strands, VercelAI, LangChain, CrewAI, AutoGen, OpenAIAgents, GoogleADK, PydanticAI.

Environment Variable Support

Configure via environment variables without code changes:

SIDESEAT_ENDPOINT=http://custom:5388 \
SIDESEAT_PROJECT_ID=my-project \
SIDESEAT_API_KEY=sk-xxx \
node app.js

Debug Mode

Enable verbose logging:

init({ debug: true });

Output:

[SideSeat] Initializing with endpoint: http://127.0.0.1:5388
[SideSeat] Project ID: default
[SideSeat] Service name: my-app

Resource Attributes

The SDK automatically sets these OpenTelemetry resource attributes:

Attribute	Value
service.name	From config, package.json, or "unknown-service"
service.version	From config, package.json, or "0.0.0"
telemetry.sdk.name	"sideseat"
telemetry.sdk.version	SDK version
telemetry.sdk.language	"node"

OTLP Export

The SDK uses HTTP/1.1 OTLP export with:

• Batching: Spans are batched for efficient export
• Retry: Automatic retry on transient failures
• Compression: Optional gzip compression

The endpoint URL is constructed as:

{endpoint}/otel/{projectId}/v1/traces

Example

import { init } from '@sideseat/sdk';

// Initialize with all options
const client = init({
  endpoint: 'http://localhost:5388',
  projectId: 'my-project',
  apiKey: 'sk-xxx',
  serviceName: 'my-ai-agent',
  debug: true
});

// Your AI application code
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

const { text } = await generateText({
  model: openai('gpt-5-mini'),
  prompt: 'Hello!',
  experimental_telemetry: { isEnabled: true },
});
console.log(text);

TypeScript Support

The SDK is written in TypeScript and includes type definitions:

import { init } from '@sideseat/sdk';
import type { SideSeatOptions } from '@sideseat/sdk';

const config: SideSeatOptions = {
  endpoint: 'http://localhost:5388',
  projectId: 'my-project',
  debug: true
};

init(config);

Next Steps

• Configuration — detailed configuration options
• init() / createClient() — API reference