SDK Configuration Reference

All three SDKs (Node.js, Python, Go) share the same configuration model and defaults. This reference covers the settings available at initialization time.

Never commit API keys to source control. Use environment variables or a secrets manager. API keys that are exposed should be rotated immediately from your workspace settings.

Required settings

Setting	Env var	Description
`apiKey` / `api_key` / `APIKey`	`INCIDENTARY_API_KEY`	Workspace API key from Settings → API Keys. Must start with `sk_`.
`serviceName` / `service_name` / `ServiceName`	`INCIDENTARY_SERVICE_NAME`	How this service appears in the artifact and Slack notifications. Use a stable, human-readable name.

Optional settings

Setting	Env var	Default	Description
`environment`	`INCIDENTARY_ENVIRONMENT`	`production`	Environment label attached to every event. Useful for filtering traces by environment in the dashboard.
`apiUrl` / `api_url`	`INCIDENTARY_API_URL`	`https://api.incidentary.com`	Ingest endpoint. Override for local development or self-hosted deployments.

Auto-instrumentation

By default, the SDK automatically detects and instruments supported libraries at initialization. This is the recommended mode — it requires no code changes beyond initializing the client.

Setting	Default	Description
`autoInstrument` / `auto_instrument`	`true`	Enable automatic detection and patching of supported libraries (HTTP clients, queues, databases, gRPC).
`integrations`	—	Override the default integration list. Pass an array of integration instances to control exactly which libraries are patched. Replaces defaults when set.

Supported integrations (auto-detected)

Node.js: http/https/fetch, BullMQ, amqplib, kafkajs, pg, ioredis, @grpc/grpc-js

Python: urllib, requests, httpx, aiohttp, Celery, kombu, psycopg2, asyncpg, grpcio

Go: Explicit wiring via WrapTransport, WrapConnector, WrapQueueConsumer, and gRPC helpers (Go cannot auto-detect at runtime).

Disabling auto-instrumentation

// Node.js — disable all auto-patching
const client = new IncidentaryClient({
  apiKey: process.env.INCIDENTARY_API_KEY!,
  serviceName: 'my-service',
  autoInstrument: false,
});

# Python — disable all auto-patching
client = IncidentaryClient(
    api_key=os.environ["INCIDENTARY_API_KEY"],
    service_name="my-service",
    auto_instrument=False,
)

Selecting specific integrations

// Node.js — only instrument HTTP and pg
import { HTTPIntegration, PgIntegration } from '@incidentary/sdk-node';

const client = new IncidentaryClient({
  apiKey: process.env.INCIDENTARY_API_KEY!,
  serviceName: 'my-service',
  integrations: [new HTTPIntegration(), new PgIntegration()],
});

OpenTelemetry coexistence

If OpenTelemetry has already instrumented a library, the SDK detects the existing patching and skips its own. Both systems can run side by side without conflicts.

Queue and flush behavior

These defaults are set to be safe for production traffic and generally do not need adjustment.

Behavior	Default	Description
Queue size cap	5,000 events	When full, the oldest event is dropped first. The queue never blocks the caller.
Batch size	100 events	Events are flushed in chunks of 100.
Retry attempts	3	Failed batches are retried.
Retry backoff	1s, 4s, 16s	Exponential backoff between retry attempts.
Drop behavior	Fail-open	After 3 failed retries, the batch is dropped and a warning is logged. No exception is raised.

Why the queue drops the oldest events: When under load, recent events are more valuable for incident investigation than older ones. Dropping old events preserves the most current causal chain.

The SDK continuously monitors your service for anomalies and can enter an elevated capture mode before an external alert fires. This is silent — it does not page anyone, does not create incidents, and does not affect your application's behavior. It only increases the detail level of captured events locally.

The SDK monitors four signals:

5xx rate: when error rate climbs above threshold
Slow success: when successful requests become significantly slower than normal
In-flight pileup: when concurrent in-flight work grows faster than completion
Retry onset: when outbound retry behavior starts increasing

Pre-arm activates when any one signal reaches a severe threshold, or when two distinct signals reach a mild threshold within 10 seconds.

If the elevated period ends without an incident binding, the SDK returns to normal capture mode automatically.

Pre-arm thresholds (Node.js config keys)

These rarely need tuning. Adjust only if you have persistent false positives that waste capture bandwidth.

Config key	Default	Description
`preArmThresholdHigh`	`10`	5xx count threshold for severe activation
`preArmThresholdLow`	`2`	5xx count threshold for mild activation
`preArmMinDurationMs`	`60000`	Minimum pre-arm duration (1 minute)
`preArmTtlMs`	`300000`	Maximum pre-arm duration before expiry (5 minutes)
`preArmCooldownMs`	`30000`	Cooldown after pre-arm before it can reactivate (30 seconds)

Disabling individual triggers

If a specific trigger produces too many false positives for your traffic pattern:

// Node.js
const client = new IncidentaryClient({
  apiKey: process.env.INCIDENTARY_API_KEY!,
  serviceName: 'my-service',
  preArmEnableSlowSuccess: false, // disable slow-success trigger
  preArmEnableInFlight: false, // disable in-flight pileup trigger
  preArmEnableRetry: true, // keep retry trigger active
});

# Python
client = IncidentaryClient(
    api_key=os.environ["INCIDENTARY_API_KEY"],
    service_name="my-service",
    pre_arm_enable_slow_success=False,
)

Cost of false positives: A false pre-arm only increases local capture depth temporarily. It does not page anyone or create incidents. The cost is slightly higher event volume during the false pre-arm window.

Detail capture

When in elevated (pre-arm or incident) mode, the SDK captures additional metadata beyond the base event:

HTTP method and route template
Selected safe request/response headers (Content-Type, Content-Length, X-Request-Id)
Request/response byte size estimates
Retry information (attempt number, group ID)
Timeout and cancellation classification

Payload snippets (request/response body excerpts) are disabled by default. Enable with:

preArmDetailCapturePayloadEnabled: true,
preArmDetailMaxPayloadBytes: 4096,

When enabled, payloads are truncated at preArmDetailMaxPayloadBytes and are only captured in elevated mode. Sensitive data should be filtered using preArmDetailRequestHeaderAllowlist and preArmDetailResponseHeaderAllowlist.

SDK Configuration