Skip to content
SideSeat

TypeScript SDK

The SideSeat TypeScript 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 TypeScript SDK
  • Use environment variables for configuration
  • Enable debug mode and custom endpoints

Prerequisites

Section titled “Prerequisites”
  • SideSeat running locally (sideseat)
  • Node.js 18+

Installation

Section titled “Installation”
Terminal window
npm install @sideseat/sdk

Or with your package manager:

Terminal window
npm install @sideseat/sdk

Quick Start

Section titled “Quick Start”

Add two lines at the top of your entry point:

import { init, Frameworks } from '@sideseat/sdk';
import { generateText, registerTelemetry } from 'ai';
import { LegacyOpenTelemetry } from '@ai-sdk/otel';
import { bedrock } from '@ai-sdk/amazon-bedrock';


init({ framework: Frameworks.VercelAI });


// AI SDK 7 hands telemetry to registered integrations rather than emitting spans itself, so
// this is required as well as the per-call flag. Register after init(): the integration
// captures a tracer in its constructor. Needs `npm install @ai-sdk/otel`.
registerTelemetry(new LegacyOpenTelemetry());


const { text } = await generateText({
  model: bedrock('us.anthropic.claude-sonnet-4-5-20250929-v1:0'),
  prompt: 'Hello!',
  experimental_telemetry: { isEnabled: true },
});

Runs flow to SideSeat at http://localhost:5388.

Features

Section titled “Features”

Framework Selection

Section titled “Framework Selection”

framework is required and tells SideSeat which framework you are using for accurate trace detection:

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


init({ framework: Frameworks.VercelAI });

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

Idempotent Initialization

Section titled “Idempotent Initialization”

Safe to call multiple times:

init({ framework: Frameworks.VercelAI });  // Initializes
init({ framework: Frameworks.VercelAI });  // No-op (already initialized)

Environment Variable Support

Section titled “Environment Variable Support”

Configure via environment variables without code changes:

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

Debug Mode

Section titled “Debug Mode”

Enable verbose logging:

init({ framework: Frameworks.VercelAI, debug: true });

Logging goes through the OpenTelemetry diagnostic logger. Output:

@opentelemetry/api: Registered a global for diag v1.9.1.
@opentelemetry/api: Registered a global for trace v1.9.1.
@opentelemetry/api: Registered a global for context v1.9.1.
@opentelemetry/api: Registered a global for propagation v1.9.1.
[sideseat] TracerProvider registered
[sideseat] Initialized - sending traces to http://127.0.0.1:5388/otel/default/v1/traces

The @opentelemetry/api: lines come from the OTel API registering its globals; SideSeat’s own messages are prefixed [sideseat].

Use logLevel for finer control — debug: true implies logLevel: 'debug'.

Resource Attributes

Section titled “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

Section titled “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   # endpoint has no path
{endpoint}/v1/traces                    # endpoint already has a path

In the second case projectId is not inserted — the project is taken from the path you supplied. See Configuration → endpoint.

Example

Section titled “Example”
import { init, Frameworks } from '@sideseat/sdk';


// Initialize with all options
const client = init({
  framework: Frameworks.VercelAI,
  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 { bedrock } from '@ai-sdk/amazon-bedrock';


const { text } = await generateText({
  model: bedrock('us.anthropic.claude-sonnet-4-5-20250929-v1:0'),
  prompt: 'Hello!',
  experimental_telemetry: { isEnabled: true },
});
console.log(text);

TypeScript Support

Section titled “TypeScript Support”

The SDK is written in TypeScript and includes type definitions:

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


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


init(config);

Next Steps

Section titled “Next Steps”