English · Français

@ddd-ts-kit/sentry

The kernel ErrorReporter on Sentry or on GlitchTip, which speaks the same protocol: one adapter, only the DSN differs. Unexpected failures only, each one leading to its trace, scrubbed before it leaves the process. Nothing in domain/ or application/ imports this package, or reports anything: handlers throw, and what stands around them reports.

npm i @ddd-ts-kit/sentry @sentry/node @opentelemetry/api

Written against @sentry/node 11: the options it relies on (enableOpenTelemetrySetup, dataCollection) do not exist in earlier majors.

The code of a use case never sees the reporter. It throws; what stands around it decides whether the failure is an incident, describes it with the identifiers of the work in progress and hands it to the kernel ErrorReporter, the one port this package implements.

Composition root

// platform/observability/errors.ts: imported second, right after platform/observability/tracing.ts
import { reportProcessFailures } from '@ddd-ts-kit/kernel';
import { initSentry } from '@ddd-ts-kit/sentry';
import { loadConfig } from '@/platform/config/load-config';

// { dsn?, environment, release?, scrubMessages } of the validated configuration.
// Without a DSN nothing starts and nothing is reported.
export const errors = initSentry(loadConfig(process.env).errorReporting);

reportProcessFailures(errors); // uncaughtException and unhandledRejection: reported, then exit 1

// main.ts
import { tracing } from '@/platform/observability/tracing'; // first
import { errors } from '@/platform/observability/errors'; // second
import { DeadLetterReports, ExecutionScope } from '@ddd-ts-kit/kernel';
import { kernelModule } from '@ddd-ts-kit/di';
import { createApplication } from '@ddd-ts-kit/di/tsyringe';
import { reportHttpErrors } from '@ddd-ts-kit/http';
import { RabbitMqEventBus } from '@ddd-ts-kit/rabbitmq';

const deadLetters = new DeadLetterReports(errors);
const bus = new RabbitMqEventBus({ url, onFailure: (failure) => deadLetters.onFailure(failure) });

const app = createApplication({
  modules: [
    kernelModule({
      errorReporter: errors, // buses and jobs report through it, app.stop() flushes it
      eventBus: bus,
      eventSubscribers: { forContext: (name) => deadLetters.observing(bus.forConsumer(name)) },
    }),
    ...contexts,
  ],
});

const http = { onError: reportHttpErrors(errors), executionScope: app.resolve(ExecutionScope) };

process.on('SIGTERM', () => void app.stop().then(() => tracing.shutdown()));

Three lines carry it: initSentry, errorReporter: errors, onError: reportHttpErrors(errors). The process handlers and the dead letters are one line each, for who wants them.

init --errors sentry writes exactly these pieces, each in its file: platform/observability/errors.ts as above, with SENTRY_DSN, SENTRY_ENVIRONMENT (default: NODE_ENV), SENTRY_RELEASE and SENTRY_SCRUB_MESSAGES read by platform/config/load-config.ts; errors handed by main.ts to composeApplication, which gives it to kernelModule({ errorReporter }); reportHttpErrors in platform/auth/authentication/http-boundary.ts; DeadLetterReports in platform/events/create-event-provider.ts (the broker) and in platform/events/start-outbox-relay.ts (a publication declared dead).

Load order. platform/observability/tracing.ts stays the first import: OpenTelemetry patches http and the drivers when they are loaded, so it must run before them. initSentry patches nothing, so its place changes nothing for tracing, whichever of the two starts first (both orders are tested). It goes second so that a failure while the rest of the application loads is already reported by reportProcessFailures.

What is reported

Only what nobody planned. A DomainError is a business refusal, an answer and not an incident.

One failure, one report. The first capture point that sees an error object reports it and marks it; the boundaries it crosses afterwards recognise it, also as the cause of an error that wraps it. A command that fails inside a request is therefore reported once, by the bus, under the name of the command, and the route that answers 500 stays silent. The report still says where it came from: origin is the origin of the execution context (http, schedule), and the correlation id and the trace lead to the request.

Events. A consumer is retried: its first failures are expected, and reporting them would bury the real incidents. The bus middleware therefore says nothing while an event is consumed, and DeadLetterReports reports the event once its provider gives it up. The hooks of the providers say codes only, so observing(subscriber) remembers what each handler threw: the report carries the real error and its stack. Without it, or for a poison message, the report is a DeadLetterError naming the code. An event buried by a DomainError is reported as a warning: it is lost to its consumer all the same.

The same steps, played by hand against the doubles of the kernel, as a test of the wiring would:

import {
  DeadLetterReports,
  InMemoryErrorReporter,
  type IntegrationEvent,
  type IntegrationEventCallback,
  type IntegrationEventSubscriber,
} from '@ddd-ts-kit/kernel';

// A provider reduced to what matters here: it keeps the handler it is given.
const handlers = new Map<string, IntegrationEventCallback>();
const provider: IntegrationEventSubscriber = {
  subscribe: (type, handler) => {
    handlers.set(type, handler);

    return { unsubscribe: () => handlers.delete(type) };
  },
};

const reporter = new InMemoryErrorReporter();
const deadLetters = new DeadLetterReports(reporter);

deadLetters.observing(provider).subscribe('ordering.order.placed', async () => {
  throw new Error('ledger unavailable');
});

const event: IntegrationEvent = {
  id: 'evt-1',
  type: 'ordering.order.placed',
  version: 1,
  occurredAt: '2026-03-01T10:00:00.000Z',
  payload: {},
};
const deliver = handlers.get('ordering.order.placed');

// What the provider says of each failed delivery: codes and identifiers only.
const failure = { kind: 'handler', code: 'Error', eventId: 'evt-1', eventType: 'ordering.order.placed', consumer: 'billing' };

await deliver?.(event).catch(() => undefined); // attempt 1 fails: observing remembers the error
deadLetters.onFailure({ ...failure, attempt: 1 }); // retried: no report

await deliver?.(event).catch(() => undefined); // attempt 2, the last one, fails
deadLetters.onFailure({ ...failure, attempt: 2, dead: true }); // given up: one report

// One report: the Error('ledger unavailable') itself, origin 'event', operation 'ordering.order.placed billing'.
export const reports = reporter.reports;

In a handler. Nothing to write: a handler throws, and the capture point around it reports.

import { DomainRefusal, type ErrorReporter } from '@ddd-ts-kit/kernel';

interface PaymentGateway {
  capture(paymentId: string): Promise<'captured' | 'declined'>;
}

interface CapturePaymentCommand {
  readonly paymentId: string;
}

// payments.codes.ts
export const PaymentsCodes = {
  PaymentDeclined: 'PAYMENT_DECLINED',
} as const;

// domain/errors/payment-declined.error.ts
export class PaymentDeclined extends DomainRefusal {
  readonly code = PaymentsCodes.PaymentDeclined;

  static forPayment(paymentId: string) {
    return PaymentDeclined.refusal(`Payment ${paymentId} was declined.`, { paymentId });
  }
}

// Instead of: a handler that reports by itself, and hides the failure from its caller.
export class CapturePaymentReportingItself {
  constructor(
    private readonly gateway: PaymentGateway,
    private readonly errors: ErrorReporter,
  ) {}

  async execute(command: CapturePaymentCommand): Promise<void> {
    try {
      await this.gateway.capture(command.paymentId);
    } catch (error) {
      this.errors.report(error, { origin: 'command', operation: 'CapturePayment', severity: 'error' });
    }
  }
}

// Write: a handler that throws. A refusal is a DomainError, answered and never reported;
// anything else goes up to the bus, which reports it once, with the actor, the tenant and the trace.
export class CapturePaymentHandler {
  constructor(private readonly gateway: PaymentGateway) {}

  async execute(command: CapturePaymentCommand): Promise<void> {
    if ((await this.gateway.capture(command.paymentId)) === 'declined') {
      throw PaymentDeclined.forPayment(command.paymentId);
    }
  }
}

With OpenTelemetry

@ddd-ts-kit/tracing owns the tracer provider, the context manager, the propagator and the auto-instrumentations. initSentry leaves all of them alone:

• enableOpenTelemetrySetup: false: the SDK registers no tracer provider and no propagator;
• none of the SDK's default integrations, and enableRuntimeChannelInjection: false: no second instrumentation of http or of a driver;
• no tracesSampleRate unless given: no performance data goes to the tracker.

What links the two is one read: when a failure is reported, the reporter takes the trace id and the span id of the active OpenTelemetry span and puts them in contexts.trace of the event. From an issue in Sentry or GlitchTip, the trace id opens the trace in the tracing backend. The spans themselves are exported once, by the exporter of the kit.

Privacy

Messages. The message is the first thing read in an error tracker, and the first place where personal data leaks: a driver quotes the row it refused. The default keeps it, because an issue titled [message removed] costs every investigation, and because the tracker is an internal tool whose access and retention the project controls. With scrubMessages: true only the messages the project wrote itself survive, those of its DomainErrors; type, code, stack and trace remain for the others. Turn it on when the tracker is hosted by a third party or when the data is sensitive enough that no operator should read it there. The loggers of the kit (StdoutLogger, @ddd-ts-kit/pino, @ddd-ts-kit/winston) take the option under the same name, with the same rule and the same marker, SCRUBBED_MESSAGE of the kernel.

Values of a failed statement. Whatever scrubMessages says, scrubEvent replaces by [redacted] each value a driver quotes, and keeps the statement, which is the signal: the parameters Drizzle writes after params: in a DrizzleQueryError; the key of a violated unique or foreign key constraint (Key (email)=([redacted]) already exists., in a message or a detail); the row a not-null or a check constraint refused (Failing row contains ([redacted]).); a value PostgreSQL could not read (invalid input syntax for type integer: "[redacted]"); the arguments Prisma renders of a call it refused; a field named parameters, params or bindings that an integration copied of the error. Knex on PostgreSQL quotes $1, and TypeORM the message of the server, whose forms are the ones above.

beforeSend runs last, on the scrubbed event, and may drop it by answering null.

The DSN stays inside the SDK client. A SentryErrorReporter that is logged, spread or serialised shows SentryErrorReporter [client concealed]; the client of the SDK, if you log it yourself, shows its options.

Grouping and tags

The fingerprint never contains the message, so identifiers in a message do not turn one problem into thousands of issues: a DomainError is its class and its code; any other error is its class, its code when it has one, and the function and file of its first frame, without line numbers.

Tags: origin, operation, correlation_id, bounded_context, error_code, and tenant_id on request. The fields a project adds to ErrorReportExtensions are sent as the report context.

Options

flush(timeoutMs) answers true when nothing is left to send. app.stop() calls it with two seconds; reportProcessFailures does before exiting.

GlitchTip for development

GlitchTip 6 runs as one service next to its PostgreSQL (14 or later) and, recommended by its documentation, Valkey. The development image bootstraps a user, an organization and a project and prints the DSN:

services:
  glitchtip:
    image: glitchtip/glitchtip:6.2.6
    profiles: [errors]
    depends_on:
      glitchtip-postgres: { condition: service_healthy }
      glitchtip-valkey: { condition: service_started }
    ports: ['127.0.0.1:8000:8000']
    environment:
      SERVER_ROLE: all_in_one # web and worker in one process
      DATABASE_URL: postgres://postgres:postgres@glitchtip-postgres:5432/glitchtip
      VALKEY_URL: redis://glitchtip-valkey:6379
      SECRET_KEY: local-development-only-not-a-secret # never in production: openssl rand -hex 32
      GLITCHTIP_DOMAIN: http://localhost:8000
      EMAIL_URL: consolemail://
      DEFAULT_FROM_EMAIL: glitchtip@localhost
      DEBUG: 'true' # development only: required by the bootstrap below
      GLITCHTIP_BOOTSTRAP_DEV: 'true' # user [email protected] / admin_pass, organization, project, DSN
    healthcheck:
      test: [CMD, python, healthcheck.py]
      interval: 10s
      timeout: 6s
      retries: 6
      start_period: 180s # the first start migrates the database
  glitchtip-postgres:
    image: postgres:18-alpine
    profiles: [errors]
    environment: { POSTGRES_DB: glitchtip, POSTGRES_PASSWORD: postgres }
    volumes: ['glitchtip-postgres:/var/lib/postgresql']
    healthcheck:
      test: [CMD-SHELL, pg_isready -U postgres -d glitchtip]
      interval: 5s
      retries: 12
  glitchtip-valkey:
    image: valkey/valkey:9-alpine
    profiles: [errors]

volumes:
  glitchtip-postgres:

docker compose --profile errors up -d --wait
docker compose logs glitchtip | grep 'DSN:'

Put the DSN in SENTRY_DSN; from another container of the stack, replace localhost with glitchtip. Sign in at http://localhost:8000 with the user above.

In a test

Nothing of this package: the test application binds InMemoryErrorReporter, and app.errors.reports lists what the buses and the jobs reported, as data: each entry is { error, report }, the error as it was thrown and the ErrorReport that describes it.