Skip to main content

Telemetry

node-auth's telemetry system persists every identity event to any store you provide. When ITelemetryStore is omitted, events still flow through AuthEventBus (and fire webhooks/SSE), they just aren't stored.

Event persistence flow​

Setup​

1. Implement ITelemetryStore​

import { ITelemetryStore, TelemetryEvent, TelemetryFilter } from '@nik2208/node-auth';

export class MyTelemetryStore implements ITelemetryStore {
  async save(event: TelemetryEvent): Promise<void> {
    await db('telemetry').insert(event);
  }

  async query(filter: TelemetryFilter): Promise<TelemetryEvent[]> {
    let q = db('telemetry');
    if (filter.event)     q = q.where('event', filter.event);
    if (filter.userId)    q = q.where('userId', filter.userId);
    if (filter.tenantId)  q = q.where('tenantId', filter.tenantId);
    if (filter.from)      q = q.where('timestamp', '>=', filter.from.toISOString());
    if (filter.to)        q = q.where('timestamp', '<=', filter.to.toISOString());
    return q.limit(filter.limit ?? 100).offset(filter.offset ?? 0);
  }
}

2. Pass the store to AuthTools​

const tools = new AuthTools(bus, { telemetryStore: myTelemetryStore });

3. Track events​

Events are tracked automatically when the auth router uses the same bus. You can also track custom events manually:

await tools.track('identity.user.password.changed', { method: 'reset-link' }, {
  userId: 'user-123',
  tenantId: 'tenant-abc',
  ip: req.ip,
});

Query endpoint​

When ITelemetryStore.query is implemented and telemetryStore is passed to createToolsRouter, the GET /tools/telemetry endpoint is automatically enabled:

GET /tools/telemetry?event=identity.auth.login.success&userId=user-123&limit=50

TelemetryEvent structure​

interface TelemetryEvent {
  id: string;           // auto-generated UUID
  event: string;        // e.g. 'identity.auth.login.success'
  timestamp: string;    // ISO 8601
  data?: unknown;
  userId?: string;
  tenantId?: string;
  sessionId?: string;
  correlationId?: string;
  ip?: string;
  userAgent?: string;
}

TelemetryFilter options​

interface TelemetryFilter {
  event?: string;
  userId?: string;
  tenantId?: string;
  sessionId?: string;
  from?: Date;
  to?: Date;
  limit?: number;    // default: 100
  offset?: number;   // default: 0
}

ITelemetryStore interface​

MethodRequiredDescription
save(event)✓Persist a telemetry event
query(filter)optionalEnable GET /tools/telemetry query endpoint