@breadstone/archipel-platform-analytics

Provider-agnostic analytics and error tracking infrastructure for NestJS.

Features

• Multi-provider — Sentry, Application Insights, Datadog, and No-op out of the box
• Port/adapter pattern — Swap providers without changing consumer code via AnalyticsClientPort
• Graceful lifecycle — SDK init deferred to OnModuleInit; pending events flushed on OnModuleDestroy
• NestJS integration — AnalyticsModule.register() with typed config entries
• Health checks — AnalyticsHealthIndicator for readiness probes (separate /health subpath)

⚠️ Environment Variables

Sentry

| Variable | Required | Default | Description | | -------------------- | -------- | ------- | ----------------------- | | SENTRY_DSN | yes | - | Sentry Data Source Name | | SENTRY_ENVIRONMENT | no | - | Sentry environment tag |

Application Insights

| Variable | Required | Default | Description | | --------------------------------------- | -------- | ------- | -------------------------------------- | | APPLICATIONINSIGHTS_CONNECTION_STRING | yes | - | Application Insights connection string |

Datadog

| Variable | Required | Default | Description | | ------------ | -------- | ------- | -------------------- | | DD_SERVICE | yes | - | Datadog service name | | DD_ENV | no | - | Datadog environment |

Quick Start

import { AnalyticsModule, AnalyticsClientPort } from '@breadstone/archipel-platform-analytics';
import { SentryAnalyticsClient, SENTRY_CONFIG_ENTRIES } from '@breadstone/archipel-platform-analytics/sentry';

@Module({
  imports: [
    AnalyticsModule.register({
      analyticsClient: SentryAnalyticsClient,
      configEntries: SENTRY_CONFIG_ENTRIES,
      isGlobal: true,
    }),
  ],
})
export class AppModule {}

Supported Providers

| Provider | Client | Package | | -------------------- | ---------------------------- | --------------------- | | Sentry | SentryAnalyticsClient | @sentry/node | | Application Insights | AppInsightsAnalyticsClient | applicationinsights | | Datadog | DatadogAnalyticsClient | dd-trace | | No-op (dev/test) | NoopAnalyticsClient | - |

Import Options

// Main import (port, module, no-op client)
import { AnalyticsModule, AnalyticsClientPort, NoopAnalyticsClient } from '@breadstone/archipel-platform-analytics';

// Provider-specific (tree-shakable sub-exports)
import { SentryAnalyticsClient, SENTRY_CONFIG_ENTRIES } from '@breadstone/archipel-platform-analytics/sentry';
import {
  AppInsightsAnalyticsClient,
  APP_INSIGHTS_CONFIG_ENTRIES,
} from '@breadstone/archipel-platform-analytics/app-insights';
import { DatadogAnalyticsClient, DATADOG_CONFIG_ENTRIES } from '@breadstone/archipel-platform-analytics/datadog';

// Health indicator (optional)
import { AnalyticsHealthIndicator } from '@breadstone/archipel-platform-analytics/health';

Ports

| Port | Description | | --------------------- | -------------------------------------------- | | AnalyticsClientPort | Analytics and error tracking client contract |

Lifecycle

• Startup (OnModuleInit): SDK initialization is deferred — no side effects in constructors.
• Shutdown (OnModuleDestroy): Each client flushes pending events and gracefully closes the SDK connection with a 5-second timeout guard.

Peer Dependencies

| Package | Required | Notes | | -------------------------------------- | -------- | ----------------------------- | | @nestjs/common | Yes | NestJS core | | @sentry/node | No | Required for Sentry provider | | applicationinsights | No | Required for App Insights | | dd-trace | No | Required for Datadog provider | | @breadstone/archipel-platform-health | No | Required for health indicator | | @nestjs/terminus | No | Required for health indicator |

Documentation

📖 Package Docs: .docs/packages/platform-analytics/index.md

Development

# Build
yarn nx build platform-analytics

# Test
yarn nx test platform-analytics

# Lint
yarn nx lint platform-analytics