Cognition: Configuration Reference

Pass a single CognitionConfig object to Cognition.init(). The SDK validates it at startup, fills in defaults for anything you leave out, and throws immediately if a required field is missing or invalid — configuration mistakes surface at startup, not in production.

import { Cognition } from '@skytells/cognition';

const cognition = Cognition.init({
  // your config here
});

Required Fields

apiKey

• Type: string
• Max length: 512 characters

Your Skytells API key — used as the x-api-key header on every request to the ingestion service. Obtain it from Settings → API Keys in the Console.

{ apiKey: process.env.SKYTELLS_API_KEY! }

Validation: The SDK throws at init() if apiKey exceeds 512 characters or is empty.

projectId

• Type: string
• Format: [a-zA-Z0-9._-], 1–128 characters

Your Skytells project ID. All events sent with this ID appear under that project in the Console. Find your project ID on the Projects page — it is displayed next to each project name.

Allowed characters: letters, digits, hyphens (-), underscores (_), dots (.). No spaces or other special characters.

{ projectId: process.env.SKYTELLS_PROJECT_ID! }

Validation: The SDK throws at init() if projectId contains characters outside [a-zA-Z0-9._-] or exceeds 128 characters.

Optional Fields

endpoint

• Type: string
• Default: 'https://dsn.skytells.ai'

The Skytells event ingestion base URL. Trailing slashes are automatically stripped. Use this to point to a custom ingest endpoint for on-premises or self-hosted deployments.

{ endpoint: 'https://custom-ingest.example.com' }

environment

• Type: string
• Default: 'production'

Environment name attached to error events for filtering in the Console. Set this to 'staging', 'development', 'canary', or any identifier that distinguishes your deployment environments.

{ environment: process.env.NODE_ENV ?? 'development' }

release

• Type: string
• Default: '0.0.0'

Application release or version string — used to correlate errors with specific deployments.

{ release: process.env.npm_package_version }

serverName

• Type: string
• Default: os.hostname() (auto-detected)

Server, pod, or container name. Auto-detected from os.hostname() if not provided. Useful for multi-instance or Kubernetes deployments.

{ serverName: process.env.HOSTNAME || 'api-pod' }

captureErrors

• Type: boolean
• Default: true

When true, installs global handlers for uncaughtException and unhandledRejection, and monkey-patches console.* methods to capture automatic breadcrumbs.

{ captureErrors: false } // Disable automatic error capture

captureSecurityThreats

• Type: boolean
• Default: true

When true, initializes the Security Scanner, enabling scanForThreats() and the Express middleware.

{ captureSecurityThreats: false } // Disable security scanning

debug

• Type: boolean
• Default: false

Enable debug logging. When true, the SDK logs internal events, transport errors, and lifecycle events to console.debug, console.warn, and console.error.

{ debug: process.env.NODE_ENV === 'development' }

beforeSend

• Type: (event: CognitionEvent) => CognitionEvent | null
• Default: null

Hook called synchronously before every event enters the ring buffer. This is your primary control point for:

• PII scrubbing — redact emails, IPs, tokens, passwords before they leave the process
• Event filtering — return null to drop an event entirely and silently
• Enrichment — add custom fields or transform event data

{
  beforeSend: (event) => {
    // Drop debug-level messages
    if (event.type === 'message' && (event as any).level === 'debug') {
      return null;
    }

    // Scrub emails from error messages
    if (event.type === 'error') {
      const e = event as any;
      if (e.error?.message) {
        e.error.message = e.error.message.replace(/[\w.-]+@[\w.-]+/g, '[REDACTED]');
      }
      // Scrub user PII
      if (e.user?.email) e.user.email = '[REDACTED]';
    }

    // Drop runtime snapshots in development
    if (event.type === 'runtime_snapshot' && process.env.NODE_ENV === 'development') {
      return null;
    }

    return event;
  },
}

Runtime Configuration

Nested under the runtime key.

runtime.enabled

• Type: boolean
• Default: true

Enable or disable the Runtime Observer entirely.

{ runtime: { enabled: false } }

runtime.snapshotIntervalMs

• Type: number (milliseconds)
• Default: 10000 (10 seconds)

How often the Runtime Observer collects a snapshot. Each snapshot captures all six monitors: event loop, memory, CPU, GC, handles, and HTTP metrics.

{ runtime: { snapshotIntervalMs: 30_000 } } // Every 30 seconds

runtime.thresholds

Anomaly threshold configuration. When a threshold is exceeded, the observer emits an anomaly event alongside the regular runtime_snapshot.

runtime.thresholds.heapUsedMb

• Type: number (megabytes)
• Default: undefined (no threshold)

Emit an anomaly when heap usage exceeds this value.

{ runtime: { thresholds: { heapUsedMb: 512 } } }

runtime.thresholds.eventLoopLagMs

• Type: number (milliseconds)
• Default: undefined (no threshold)

Emit an anomaly when event loop p99 lag exceeds this value.

{ runtime: { thresholds: { eventLoopLagMs: 100 } } }

runtime.thresholds.eluPercent

• Type: number (0–1 ratio)
• Default: undefined (no threshold)

Emit an anomaly when event loop utilization exceeds this ratio. 0.8 = 80% utilization.

{ runtime: { thresholds: { eluPercent: 0.8 } } }

Transport Configuration

Nested under the transport key. Controls how events are buffered, batched, and delivered.

transport.batchSize

• Type: number
• Default: 50

Maximum events per batch when flushing. The transport drains the buffer in chunks of this size.

{ transport: { batchSize: 100 } }

transport.flushIntervalMs

• Type: number (milliseconds)
• Default: 5000 (5 seconds)

Interval between automatic buffer flushes.

{ transport: { flushIntervalMs: 10_000 } }

transport.maxRetries

• Type: number
• Default: 3

Maximum retry attempts for failed HTTP requests. Uses exponential backoff: 1s, 2s, 4s, ..., capped at 30s.

{ transport: { maxRetries: 5 } }

transport.timeoutMs

• Type: number (milliseconds)
• Default: 10000 (10 seconds)

Per-request HTTP timeout via AbortController. Timed-out requests are retried as network errors.

{ transport: { timeoutMs: 5000 } }

transport.maxBufferSize

• Type: number
• Default: 1000

Maximum events the in-memory ring buffer can hold. When full, the oldest event is dropped. The number of dropped events is tracked in cognition.droppedCount.

{ transport: { maxBufferSize: 5000 } }

transport.compression

• Type: boolean
• Default: true

Enable gzip compression for HTTP payloads larger than 1KB. Uses node:zlib gzipSync.

{ transport: { compression: false } } // Disable compression

Tracing Configuration

Nested under the tracing key. Requires @opentelemetry/api and @opentelemetry/sdk-trace-base as peer dependencies.

tracing.enabled

• Type: boolean
• Default: false

Enable OpenTelemetry trace integration. When true, registers a BasicTracerProvider globally.

{ tracing: { enabled: true } }

tracing.sampleRate

• Type: number (0.0–1.0)
• Default: 1.0

Fraction of traces to capture. 0.1 = 10% sampling.

{ tracing: { enabled: true, sampleRate: 0.1 } }

Full Example

import { Cognition } from '@skytells/cognition';

const cognition = Cognition.init({
  // Required
  apiKey: process.env.SKYTELLS_API_KEY!,
  projectId: process.env.SKYTELLS_PROJECT_ID!,

  // Environment
  environment: process.env.NODE_ENV ?? 'development',
  release: process.env.npm_package_version ?? '0.0.0',
  serverName: process.env.HOSTNAME,

  // Error capture
  captureErrors: true,
  captureSecurityThreats: true,

  // Runtime observer
  runtime: {
    enabled: true,
    snapshotIntervalMs: 15_000,
    thresholds: {
      heapUsedMb: 768,
      eventLoopLagMs: 200,
      eluPercent: 0.9,
    },
  },

  // Transport
  transport: {
    batchSize: 100,
    flushIntervalMs: 10_000,
    maxRetries: 5,
    timeoutMs: 15_000,
    maxBufferSize: 5000,
    compression: true,
  },

  // OTel tracing
  tracing: {
    enabled: false,
  },

  // PII scrubbing + event filtering
  beforeSend: (event) => {
    if (event.type === 'error') {
      const e = event as any;
      if (e.user?.email) e.user.email = '[REDACTED]';
    }
    return event;
  },

  // Debug logging (development only)
  debug: process.env.NODE_ENV === 'development',
});

Defaults Summary

TypeScript Types

All types are exported from the main entry point:

import type {
  CognitionConfig,
  ErrorEvent,
  RuntimeSnapshot,
  SecurityEvent,
  AnomalyEvent,
  SeverityLevel,
  Breadcrumb,
} from '@skytells/cognition';

Related

• Quickstart — Minimal working configuration
• Error Capture — captureErrors, beforeSend
• Runtime Observer — runtime.* options
• Security Scanner — captureSecurityThreats
• Transport — transport.* options and buffer behavior
• OpenTelemetry — tracing.* options