platform-analytics

Provider-agnostic analytics and error tracking module supporting multiple backends. Ships with Sentry, Azure Application Insights, and Datadog clients out of the box, plus a no-op fallback for environments where analytics is disabled.

Package: @breadstone/archipel-platform-analytics

npm install @breadstone/archipel-platform-analytics

Quick Start

import { Module } from '@nestjs/common';
import { AnalyticsModule } 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 {}

---

Module Configuration

IAnalyticsModuleOptions

Property	Type	Required	Default	Description
analyticsClient	Type<AnalyticsClientPort>	Yes	—	Concrete analytics client implementation
configEntries	ReadonlyArray<IConfigRegistryEntry>	No	[]	Provider-specific configuration entries
isGlobal	boolean	No	false	Register as a global module

---

AnalyticsClientPort API

The abstract port that all analytics clients implement. Inject it anywhere:

import { AnalyticsClientPort } from '@breadstone/archipel-platform-analytics';

@Injectable()
export class PaymentService {
  constructor(private readonly _analytics: AnalyticsClientPort) {}

  public async processPayment(): Promise<void> {
    try {
      // ... payment logic
    } catch (error) {
      this._analytics.captureException(error as Error, { feature: 'payments' });
    }
  }
}

Methods

Method	Signature	Description
captureException	(error: Error, context?: Record<string, unknown>) => void	Capture an error with optional context
captureMessage	(message: string, level: AnalyticsLevel, context?: Record<string, unknown>) => void	Capture a message at a severity level
setUser	(user: IAnalyticsUser) => void	Set the current user context
clearUser	() => void	Clear the current user context
addBreadcrumb	(breadcrumb: IAnalyticsBreadcrumb) => void	Add a breadcrumb to the analytics trail

---

Built-in Providers

SentryAnalyticsClient

Error tracking and performance monitoring via Sentry.

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

AnalyticsModule.register({
  analyticsClient: SentryAnalyticsClient,
  configEntries: SENTRY_CONFIG_ENTRIES,
});

Environment variables: SENTRY_DSN, SENTRY_ENVIRONMENT

AppInsightsAnalyticsClient

Azure Application Insights integration.

import {
  AppInsightsAnalyticsClient,
  APPINSIGHTS_CONFIG_ENTRIES,
} from '@breadstone/archipel-platform-analytics/appinsights';

AnalyticsModule.register({
  analyticsClient: AppInsightsAnalyticsClient,
  configEntries: APPINSIGHTS_CONFIG_ENTRIES,
});

Environment variables: APPLICATIONINSIGHTS_CONNECTION_STRING

DatadogAnalyticsClient

Datadog APM and error tracking.

import { DatadogAnalyticsClient, DATADOG_CONFIG_ENTRIES } from '@breadstone/archipel-platform-analytics/datadog';

AnalyticsModule.register({
  analyticsClient: DatadogAnalyticsClient,
  configEntries: DATADOG_CONFIG_ENTRIES,
});

Environment variables: DD_SERVICE, DD_ENV

NoopAnalyticsClient

Silent no-op client for environments where analytics is disabled:

import { NoopAnalyticsClient } from '@breadstone/archipel-platform-analytics';

AnalyticsModule.register({
  analyticsClient: NoopAnalyticsClient,
});

---

Sub-path Imports

Each provider is tree-shakeable via sub-path imports:

Import Path	Contents
@breadstone/archipel-platform-analytics	Core module, port, models, NoopAnalyticsClient
@breadstone/archipel-platform-analytics/sentry	SentryAnalyticsClient, SENTRY_CONFIG_ENTRIES
@breadstone/archipel-platform-analytics/appinsights	AppInsightsAnalyticsClient, APPINSIGHTS_CONFIG_ENTRIES
@breadstone/archipel-platform-analytics/datadog	DatadogAnalyticsClient, DATADOG_CONFIG_ENTRIES

---

Lifecycle & Shutdown

All built-in clients implement OnModuleInit and OnModuleDestroy:

Phase	Behavior
Init	SDK initialization is deferred to onModuleInit() — no constructor I/O
Destroy	Pending events are flushed and the SDK is closed with a 5-second timeout

This ensures no events are lost during application shutdown and prevents hanging processes if the analytics backend is unreachable.

---

Health Check

The AnalyticsHealthIndicator verifies that an AnalyticsClientPort is injected. If no analytics client is registered, it reports disabled: true. Import it from the /health subpath:

import { AnalyticsHealthIndicator } from '@breadstone/archipel-platform-analytics/health';
import { HealthModule } from '@breadstone/archipel-platform-health';

@Module({
  imports: [
    AnalyticsModule.register({ /* ... */ }),
    HealthModule.withIndicators([AnalyticsHealthIndicator]),
  ],
})
export class AppModule {}

Key	Check	Dependencies
analytics	up if AnalyticsClientPort injected, else disabled	@Optional() AnalyticsClientPort

---

Exports Summary

Export	Type	Description
AnalyticsModule	NestJS Module	Main module with register()
AnalyticsClientPort	Port	Abstract analytics contract
NoopAnalyticsClient	Client	No-op fallback implementation
SentryAnalyticsClient	Client	Sentry provider (sub-path)
AppInsightsAnalyticsClient	Client	Azure Application Insights provider (sub-path)
DatadogAnalyticsClient	Client	Datadog provider (sub-path)
AnalyticsLevel	Type	Severity level union
IAnalyticsBreadcrumb	Interface	Breadcrumb entry model
IAnalyticsUser	Interface	User context model
AnalyticsHealthIndicator	Health	Analytics readiness check (/health subpath)