JS Configuration

Configure the Risicare JavaScript SDK.

Complete configuration reference for the JavaScript/TypeScript SDK.

RisicareConfig Interface

interface RisicareConfig {
  // Required
  apiKey?: string;          // Each key is scoped to one project
 
  // Deprecated
  projectId?: string;       // DEPRECATED — emits console.warn. Will be removed in v1.0.
 
  // Optional
  endpoint?: string;        // Where spans go
  apiEndpoint?: string;     // Where scores go
  environment?: string;     // Within-project organization
  serviceName?: string;     // Within-project organization
  serviceVersion?: string;
  enabled?: boolean;
  traceContent?: boolean;
  compress?: boolean;
  sampleRate?: number;
  batchSize?: number;
  batchTimeoutMs?: number;
  maxQueueSize?: number;
  debug?: boolean;
  fixRuntime?: boolean;
  metadata?: Record<string, unknown>;
  mask?: (key: string, value: unknown) => unknown;
}

Configuration Options

Option	Type	Default	Description
`apiKey`	string	env	API key (or `RISICARE_API_KEY`). Each key is scoped to one project.
`projectId`	string	env	Deprecated — emits `console.warn`. Project is derived from the API key; will be removed in v1.0.
`endpoint`	string	`"https://ingest.risicare.ai"`	Ingest gateway URL. The SDK sends spans to this host.
`apiEndpoint`	string	`"https://api.risicare.ai"`	API URL. The SDK sends scores to this host. If you pass `endpoint` (not the default ingest host) and no `apiEndpoint`, scores go to `endpoint`, also when `RISICARE_API_ENDPOINT` is set.
`environment`	string	`"development"`	Environment name (within-project org)
`serviceName`	string	undefined	Service name (within-project org)
`serviceVersion`	string	undefined	Service version for traces
`enabled`	boolean	true	Enable tracing (true if apiKey provided)
`traceContent`	boolean	false	Capture prompts/completions. Off by default — pass `traceContent: true` to capture them
`compress`	boolean	false	Enable gzip compression for exports
`sampleRate`	number	1.0	Trace sampling rate (0-1)
`batchSize`	number	500	Spans per batch
`batchTimeoutMs`	number	1000	Milliseconds between flushes
`maxQueueSize`	number	10000	Max queued spans
`debug`	boolean	false	Enable debug logging
`fixRuntime`	boolean	false	Start the fix runtime. It is off by default since 0.7.0. The route that the fix runtime reads is not reachable with an API key during the beta, so keep it off.
`metadata`	object		Global metadata for all traces
`mask`	function	undefined	Function `mask(key, value)` that returns the value to export. It runs on content-bearing fields before export. If it throws, the field becomes `"<risicare:mask-error>"` and the span is still exported. It has no environment variable.

With no API key the SDK sends nothing

With no key (also a key of only whitespace; the SDK trims the key), tracing is off: no span is created, nothing is sent to Risicare, isEnabled() and flush() return false, and nothing is counted as exported or dropped. init() writes one WARNING that says so (none when you turned tracing off on purpose). RISICARE_TRACING=true, enabled: true and enable() cannot turn tracing on without a key, and debug: true prints no span. An apiKey option that is empty counts as not given, so RISICARE_API_KEY applies. In 0.8.0 and earlier, with RISICARE_TRACING=true and no key, the SDK created spans and dropped them after four export rounds.

Environment Variable Mapping

Config	Environment Variable
`apiKey`	`RISICARE_API_KEY`
`projectId` (deprecated)	`RISICARE_PROJECT_ID`
`endpoint`	`RISICARE_ENDPOINT`
`apiEndpoint`	`RISICARE_API_ENDPOINT`
`environment`	`RISICARE_ENVIRONMENT`
`enabled`	`RISICARE_TRACING`
`traceContent`	`RISICARE_TRACE_CONTENT`
`sampleRate`	`RISICARE_SAMPLE_RATE`
`compress`	`RISICARE_COMPRESS`
`batchSize`	`RISICARE_BATCH_SIZE`
`batchTimeoutMs`	`RISICARE_BATCH_TIMEOUT_MS`
`maxQueueSize`	`RISICARE_MAX_QUEUE_SIZE`
`serviceName`	`RISICARE_SERVICE_NAME`
`serviceVersion`	`RISICARE_SERVICE_VERSION`
`debug`	`RISICARE_DEBUG`
`fixRuntime`	`RISICARE_FIX_RUNTIME`

The JavaScript SDK reads these sixteen variables. metadata and mask have no environment variable.

Boolean variables accept true, 1 and yes, in upper or lower case. Any other value means false. This includes on, which the Python SDK accepts and the JavaScript SDK does not. RISICARE_TRACING has its own rule, the same as in the Python SDK: the value is trimmed and case is ignored; true, 1, yes and on turn tracing on; false, 0, no and off turn it off; an empty value is the same as no value; any other value turns tracing off and logs one WARNING.

Runtime Control

Enable/Disable

import { enable, disable, isEnabled } from 'risicare';
 
// Check status: false before init(), with tracing off, with no API key,
// and after the SDK's own SIGTERM or SIGINT drain
if (isEnabled()) {
  console.log('Tracing is active');
}
 
// Disable temporarily
disable();
 
// Re-enable
enable();

Flush and Shutdown

import { flush, shutdown } from 'risicare';
 
// Send the spans queued so far. Resolves true only when every span and score
// that the SDK accepted was acknowledged; false for a loss (once), before init(),
// with tracing off, and with no API key. Also exact in a SIGTERM listener.
const delivered = await flush();
 
// Graceful shutdown
await shutdown();

Configuration Precedence

Configuration is resolved in order (highest priority first):

Explicit init() parameters
Environment variables
Default values

Advanced Configuration

Custom Endpoint

Override the default gateway endpoint (https://ingest.risicare.ai) — for example, to send spans through an outbound proxy your network requires:

init({
  apiKey: 'rsk-...',
  endpoint: 'https://llm-egress-proxy.internal.example.com',
});

endpoint sets where the SDK sends spans. If you do not also pass apiEndpoint, the SDK sends scores to the same host as endpoint, unless endpoint is the default ingest host. To send scores to a different host, pass apiEndpoint: when endpoint is passed as an option, RISICARE_API_ENDPOINT does not override it.

Do not set endpoint to the dashboard address

https://app.risicare.ai is the dashboard. It is not the ingest gateway. Leave endpoint and apiEndpoint unset to use the defaults.

Risicare is a hosted service

Risicare runs as a managed service. There is no self-hosted or on-premise Risicare instance to point this at — endpoint and apiEndpoint retarget where the SDK sends its requests (a proxy or a non-default host), not where Risicare itself runs.

Sampling

Control trace sampling rate:

init({
  apiKey: 'rsk-...',
  sampleRate: 0.1, // Sample 10% of traces
});

Next Steps

JS Decorators

Higher-order functions for tracing

Learn more

JS Context

Trace context propagation

Learn more

Edit this page on GitHub

PreviousJavaScript NextJS Decorators