Error Reporting

nodyn includes opt-in error reporting via Sentry. When configured, crashes, unhandled errors, and user-submitted bug reports are captured with structured context — without sending user prompts or response content.

Setup

1. Create a Sentry project

1. Sign up at sentry.io (free tier: 5K events/month)
2. Create a new Node.js project
3. Select EU region (Frankfurt) for DSGVO/GDPR compliance
4. Copy the DSN (format: https://[email protected]/id)

2. Configure nodyn

# Environment variable (recommended for deployments)
NODYN_SENTRY_DSN=https://[email protected]/id

# Or in ~/.nodyn/config.json
{ "sentry_dsn": "https://[email protected]/id" }

# Or in project-level .nodyn/config.json (sentry_dsn is a PROJECT_SAFE_KEY)
{ "sentry_dsn": "https://[email protected]/id" }

Without a DSN, Sentry is completely inactive — zero overhead, no imports loaded.

3. Docker

docker run -d \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -e NODYN_SENTRY_DSN=https://[email protected]/id \
  -v ~/.nodyn:/home/nodyn/.nodyn \
  nodyn

What Gets Captured

Automatic (no user action needed)

Data	Details
Crashes	uncaughtException, unhandledRejection — full stack trace
NodynError hierarchy	Error code, type, safe context keys (tool name, run ID, session ID)
Tool breadcrumbs	Tool name, success/failure, duration — NO input data
LLM breadcrumbs	Model name, input/output token counts — NO prompt content
WorkerLoop failures	Background task ID, type, error message
Release tracking	[email protected] — see which version caused which errors

User-initiated (via /bug command)

Telegram users can report issues with /bug Something went wrong:

/bug The summary was completely wrong
/bug Tool keeps timing out on large files

The report is sent to Sentry as user feedback, linked to the latest error event.

What Is NOT Captured (PII Protection)

Data	Protection
User prompts	Never sent — stripped by beforeBreadcrumb and beforeSend
AI responses	Never sent
File contents	Never sent
API keys / secrets	Never sent
HTTP request bodies	Stripped by beforeSend
NodynError context	Allowlisted keys only (toolName, runId, sessionId, etc.)
Performance traces	Disabled (tracesSampleRate: 0)

The beforeBreadcrumb hook strips prompt, response, content, and message fields from all breadcrumbs. The beforeSend hook strips request.data from all events.

Architecture

Engine.init()
    │
    ├─ initSentry(dsn)          // Dynamic import, cached module ref
    ├─ installGlobalHandlers()  // uncaughtException, unhandledRejection
    └─ subscribe(toolEnd)       // Automatic tool breadcrumbs via diagnostics_channel
        │
Session.run()
    ├─ streamHandler            // LLM breadcrumbs (model + tokens)
    └─ catch                    // captureNodynError() or captureError()
        │
WorkerLoop.executeTask()
    └─ catch                    // captureError() with task tags
        │
Engine.shutdown()
    └─ shutdownSentry()         // flush(5s) + close()

All Sentry calls are fire-and-forget — errors in Sentry itself never affect nodyn operation.

Alerts

Sentry has built-in alerting. Configure in your Sentry project under Alerts:

• Email (default) — immediate notifications for new issues
• Slack/Teams — via Sentry integrations
• Weekly digest — summary of error trends

No custom Telegram or webhook integration is needed — Sentry handles notification routing.

SDK Usage

When using nodyn as a library, you can initialize Sentry yourself or let the Engine handle it:

import { Engine } from '@nodyn-ai/core';

// Option 1: Via config (Engine handles init)
const engine = new Engine({ });
// Set NODYN_SENTRY_DSN env var or sentry_dsn in config
await engine.init();

// Option 2: Direct API
import { initSentry, captureError, addToolBreadcrumb } from '@nodyn-ai/core';

await initSentry('https://[email protected]/id');
// Now all errors in Session.run() are automatically captured

// Manual breadcrumbs (optional)
addToolBreadcrumb('my-tool', true, 250);

Self-Hosted Sentry

nodyn works with self-hosted Sentry instances. Point the DSN to your server:

NODYN_SENTRY_DSN=https://[email protected]/id

No code changes needed — the DSN determines the destination.

Dependency

@sentry/node is a regular dependency (BSD-3-Clause, compatible with ELv2). It is only imported when a DSN is configured — no overhead for users who don’t enable Sentry.