TypeScript SDK Configuration

This page covers all configuration options for the SideSeat TypeScript SDK.

Configuration Object

interface SideSeatOptions {
  framework: Framework | string; // required
  disabled?: boolean;
  endpoint?: string;
  apiKey?: string;
  projectId?: string;
  serviceName?: string;
  serviceVersion?: string;
  enableTraces?: boolean;
  logLevel?: LogLevel;
  debug?: boolean;
}

Only framework is required — omitting it throws SideSeatError. Every other property is optional; the SDK uses sensible defaults and environment variables.

Note

The type was previously named SideSeatConfig. That name has been removed, not merely deprecated — importing it fails. Use SideSeatOptions.

Configuration Priority

For each option, the SDK checks in order:

1. Config parameter (highest priority)
2. Environment variable
3. Auto-detection
4. Default value (lowest priority)

Options

disabled

Disable all telemetry.

Source	Value
Config	config.disabled
Environment	SIDESEAT_DISABLED
Default	false

await init({ framework: Frameworks.Strands, disabled: true });

endpoint

The SideSeat server URL.

Source	Value
Config	config.endpoint
Environment	SIDESEAT_ENDPOINT
Default	http://127.0.0.1:5388

// Via config
await init({ framework: Frameworks.Strands, endpoint: 'http://custom:5388' });

// Via environment
// SIDESEAT_ENDPOINT=http://custom:5388 node app.js

Note

How the full OTLP URL is built depends on whether your endpoint already has a path:

• No path — /otel/{projectId}/v1/{signal} is appended, so http://127.0.0.1:5388 becomes http://127.0.0.1:5388/otel/default/v1/traces.
• Has a path — only /v1/{signal} is appended and projectId is not inserted, so http://127.0.0.1:5388/otel/my-project becomes http://127.0.0.1:5388/otel/my-project/v1/traces.

The second form is what lets OTEL_EXPORTER_OTLP_ENDPOINT point straight at a project. Note that with it the project comes from the URL, and the projectId option is ignored for routing. The Python SDK builds endpoints identically.

projectId

The project ID for organizing traces.

Source	Value
Config	config.projectId
Environment	SIDESEAT_PROJECT_ID
Default	"default"

await init({ framework: Frameworks.Strands, projectId: 'my-project' });

apiKey

Optional API key for authenticated endpoints.

Source	Value
Config	config.apiKey
Environment	SIDESEAT_API_KEY
Default	(none)

await init({ framework: Frameworks.Strands, apiKey: 'sk-xxx' });

When set, adds an Authorization: Bearer {apiKey} header to OTLP requests.

serviceName

The service name for resource attributes.

Resolved in this order, first match winning:

1. the serviceName option
2. OTEL_SERVICE_NAME
3. a framework-specific default, for the frameworks that have one (strands → strands-agents, openai-agents → openai-agents, claude-agent-sdk → claude-agent-sdk) — these are the names the server matches on
4. npm_package_name, set by npm when running through a script
5. "unknown-service"

await init({ framework: Frameworks.Strands, serviceName: 'my-ai-agent' });

Tip

OTEL_SERVICE_NAME takes precedence over npm_package_name, so you can override the name without editing package.json.

serviceVersion

The service version for resource attributes.

Source	Value
Config	config.serviceVersion
Environment	npm_package_version
Default	"0.0.0"

await init({ framework: Frameworks.Strands, serviceVersion: '1.2.3' });

framework

Select the framework to instrument. This one is required.

Source	Value
Config	config.framework (required)
Environment	not read from the environment
Default	none — omitting it throws SideSeatError

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

await init({ framework: Frameworks.VercelAI });

Available constants: Frameworks.Strands, Frameworks.VercelAI, Frameworks.LangChain, Frameworks.CrewAI, Frameworks.AutoGen, Frameworks.OpenAIAgents, Frameworks.GoogleADK, Frameworks.PydanticAI, Frameworks.ClaudeAgentSDK.

You can also pass any string for custom frameworks.

enableTraces

Enable trace span export.

Source	Value
Config	config.enableTraces
Default	true

await init({ framework: Frameworks.Strands, enableTraces: false }); // Disable tracing

logLevel

Control SDK log verbosity.

Source	Value
Config	config.logLevel
Environment	SIDESEAT_LOG_LEVEL
Default	"debug" if debug=true, else "none"

Valid levels: "none", "error", "warn", "info", "debug", "verbose".

await init({ framework: Frameworks.Strands, logLevel: 'info' });

debug

Enable verbose logging (shortcut for logLevel: "debug").

Source	Value
Config	config.debug
Environment	SIDESEAT_DEBUG
Default	false

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

Environment Variables

Variable	Description	Default
SIDESEAT_DISABLED	Disable all telemetry	false
SIDESEAT_ENDPOINT	Server URL	http://127.0.0.1:5388
SIDESEAT_PROJECT_ID	Project ID	default
OTEL_EXPORTER_OTLP_ENDPOINT	Endpoint fallback, used when SIDESEAT_ENDPOINT is unset	—
SIDESEAT_API_KEY	API key (optional)	(none)
SIDESEAT_DEBUG	Enable debug logging	false
SIDESEAT_LOG_LEVEL	Log verbosity	(none)
npm_package_name	Service name (set by npm)	(from package.json)
npm_package_version	Service version (set by npm)	(from package.json)
OTEL_SERVICE_NAME	Service name, ahead of npm_package_name	(none)
OTEL_EXPORTER_OTLP_HEADERS	Extra OTLP headers, merged with the API-key header	(none)
OTEL_EXPORTER_OTLP_TIMEOUT	Export timeout in milliseconds	30000

HTTP Headers

The SDK sends these headers with OTLP requests:

Header	Value
User-Agent	sideseat-sdk-node/{version}
Authorization	Bearer {apiKey} (if apiKey set)
Content-Type	application/x-protobuf

Complete Examples

Development

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

await init({
  framework: Frameworks.VercelAI,
  debug: true  // See what's happening
});

Production

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

await init({
  framework: Frameworks.VercelAI,
  endpoint: process.env.SIDESEAT_ENDPOINT,
  projectId: process.env.SIDESEAT_PROJECT_ID,
  apiKey: process.env.SIDESEAT_API_KEY,
  serviceName: 'my-production-agent'
});

Multi-Environment

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

const isProduction = process.env.NODE_ENV === 'production';

await init({
  framework: Frameworks.VercelAI,
  endpoint: isProduction
    ? 'http://sideseat.internal:5388'
    : 'http://localhost:5388',
  projectId: isProduction ? 'production' : 'development',
  debug: !isProduction
});

Next Steps

• init() — API reference
• Integrations — framework-specific guides