Cognition Quickstart

Install @skytells/cognition, connect it to your Skytells project, and verify your first events in the Console.

This guide takes you from a fresh install to your first verified event in the Console.

Before You Begin

You need three things:

A Skytells project

Create a project in Skytells Projects ↗. Your project ID is displayed next to the project name on that page. It must contain only letters, digits, hyphens (-), underscores (_), and dots (.) — between 1 and 128 characters. See Projects for more.

An API key

Inside your project, go to Settings → API Key and copy your key. Or find it in the Console under Settings → API Keys. Store it as an environment variable — never hardcode it.

Set both as environment variables in your application:

SKYTELLS_API_KEY=sk-...
SKYTELLS_PROJECT_ID=my-api-service

Installation

# npm
npm install @skytells/cognition

# pnpm
pnpm add @skytells/cognition

# yarn
yarn add @skytells/cognition

The package has zero production dependencies — everything uses Node.js built-in modules.

Initialize the SDK

Call Cognition.init() once, as early as possible in your application startup — before any route handlers, middleware, or async operations.

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

const cognition = Cognition.init({
  apiKey: process.env.SKYTELLS_API_KEY!,
  projectId: process.env.SKYTELLS_PROJECT_ID!,
});

With these two lines, the SDK immediately:

Installs handlers for uncaughtException and unhandledRejection
Starts collecting runtime snapshots every 10 seconds
Enables security threat detection
Begins buffering and flushing events to https://dsn.skytells.ai every 5 seconds

Capture Your First Error

Automatic capture is already active. To manually capture an error:

try {
  await riskyOperation();
} catch (err) {
  cognition.captureError(err as Error, {
    level: 'error',
    context: { operation: 'data-fetch', service: 'users' },
  });
}

To send a simple message:

cognition.captureMessage('Application started successfully', 'info');

Attach Context

Tags and user context are attached to all subsequent events:

// Tags — indexed, searchable
cognition.setTag('service', 'payment-api');
cognition.setTag('region', 'us-east-1');

// User context — attached to error events
cognition.setUser({ id: 'user-123', username: 'jane_doe' });

// Extra data — arbitrary key-value pairs
cognition.setExtra('requestId', 'req-abc-123');

Add Breadcrumbs

Breadcrumbs create a trail of events leading up to errors. Console calls are automatically captured as breadcrumbs. Add custom ones:

cognition.addBreadcrumb('http', 'GET /api/orders → 200', { durationMs: 45 });
cognition.addBreadcrumb('database', 'Fetched user record', { userId: 'u-123' });
cognition.addBreadcrumb('checkout', 'Cart validated', { items: 3, total: 89.99 });

When an error occurs, the most recent breadcrumbs are included in the error event automatically.

Graceful Shutdown

Always call cognition.close() before your process exits to flush all buffered events:

process.on('SIGTERM', async () => {
  await cognition.close(); // Flushes with a 5s default timeout
  process.exit(0);
});

process.on('SIGINT', async () => {
  await cognition.close();
  process.exit(0);
});

Without this, buffered events may be lost when the process exits.

Verify in the Console

Open the Cognition Console ↗.
Select your project if prompted.
Under Cognition, check the Overview tab — you should see activity from your first events within a few seconds.
Open Errors to inspect captured error events, or Runtime Health to see the first snapshot.

You can also verify from the CLI:

skytells cognition overview --project your-project-id --hours 1

See CLI reference for authentication and setup.

Singleton vs. Multiple Instances

Singleton (recommended)

Initialize once at startup and use the default export anywhere:

// startup.ts
import cognition from '@skytells/cognition';

cognition.init({
  apiKey: process.env.SKYTELLS_API_KEY!,
  projectId: process.env.SKYTELLS_PROJECT_ID!,
});

// anywhere else in your app
import cognition from '@skytells/cognition';
cognition.captureError(err);

Multiple Instances (microservices, testing)

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

const paymentObserver = Cognition.init({
  apiKey: process.env.SKYTELLS_API_KEY!,
  projectId: 'payment-service',
});

const authObserver = Cognition.init({
  apiKey: process.env.SKYTELLS_API_KEY!,
  projectId: 'auth-service',
  captureErrors: false, // Only one instance should own global error handlers
});

When using multiple instances, only one should have captureErrors: true. Global process handlers (uncaughtException, unhandledRejection) can only be owned by one instance meaningfully.

ESM and CommonJS

The SDK ships both formats:

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

// CommonJS
const { Cognition } = require('@skytells/cognition');

Next Steps

Error Capture — Deep dive into automatic and manual error handling
Runtime Observer — Understand what process metrics are collected
Security Scanner — Protect your HTTP endpoints from injection attacks
Configuration — Fine-tune every aspect of the SDK
Analytics — View your data in the Console and CLI

How is this guide?

A Skytells project

An API key

On this page