Introduction

@dudousxd/nestjs-diagnostics is a tiny, standard convention for @dudousxd/nestjs-* libraries to emit observability events over Node's built-in diagnostics_channel. A library calls emit('authz', 'decision', payload) and is done — whoever wants to observe it subscribes. It costs essentially nothing when nobody is listening, and never throws.

The point: producers stay decoupled from consumers

The key idea is that the channel is neutral. A library that emits a diagnostic event doesn't know — and doesn't care — who reads it. Telescope is one consumer (the batteries-included one), but the same event can just as easily feed an OpenTelemetry span, an APM tool, a custom logger, or an assertion in a test. See Consumers.

This is why it's a separate package from Telescope: if emitting required Telescope, every producing library would be coupled to it. Instead, producers depend only on this thin layer, and observability is opt-in on the consumer side.

The convention

Every event flows over a channel named aviary:<lib>:<event> and carries a standard envelope:

interface DiagnosticEvent<TPayload = unknown> {
  ts: number;         // Date.now() at publish time
  lib: string;        // the <lib>, e.g. "authz"
  event: string;      // the <event>, e.g. "decision"
  traceId?: string;   // auto-filled from nestjs-context when present
  payload: TPayload;  // your library-defined data
  durationMs?: number; // wall-clock duration of a timed operation, when known
}

durationMs is optional and only present when the emitter measured how long the operation took (see Getting Started). Events that don't describe a timed operation omit it entirely, so the common envelope stays free of an undefined-valued key.

Quickstart

pnpm add @dudousxd/nestjs-diagnostics

import { Injectable } from '@nestjs/common';
import { emit } from '@dudousxd/nestjs-diagnostics';

@Injectable()
export class BillingService {
  async markInvoicePaid(invoiceId: string, amount: number) {
    // … your domain logic …
    emit('billing', 'invoice-paid', { invoiceId, amount });
  }
}

Where to go next