@ciphercross/nestjs-datadog

NestJS module for Datadog logging, tracing, and monitoring.
Provides structured logging, distributed tracing, health checks, and metrics collection out of the box.

✨ Features

• 🚀 Structured JSON logging (Winston)
• 🔍 Distributed tracing (Datadog APM)
• 📊 Health checks & Kubernetes probes
• 📈 Metrics collection
• 🎯 Easy-to-use decorators for tracing & logging
• 📝 Optional Swagger support for monitoring endpoints

📦 Installation

npm install @ciphercross/nestjs-datadog

🚀 Quick Start

1. Import the Module

import { Module } from "@nestjs/common";
import { DatadogModule } from "@ciphercross/nestjs-datadog";

@Module({
  imports: [DatadogModule.register({ serviceName: "my-app" })],
})
export class AppModule {}

2. Use the Services

import { Injectable } from "@nestjs/common";
import {
  DatadogLoggerService,
  DatadogTracingService,
} from "@ciphercross/nestjs-datadog";

@Injectable()
export class UserService {
  constructor(
    private readonly logger: DatadogLoggerService,
    private readonly tracing: DatadogTracingService
  ) {}

  async createUser(user: any) {
    this.logger.log("User created", "USER_SERVICE");
    return this.tracing.trace("user.create", async () => user);
  }
}

3. (Optional) Monitoring Endpoints

If you need /monitoring/health and /monitoring/metrics, import:

import { DatadogMonitoringController } from "@ciphercross/nestjs-datadog/monitoring";

⚙️ Configuration (env variables)

| Variable | Description | Default | Required? | | ---------------------------- | ------------------------------------------ | ---------------- | --------- | | DD_API_KEY | Datadog API key | — | Yes* | | DD_SERVICE | Service name | nestjs-app | No | | DD_VERSION | Service version | 1.0.0 | No | | DD_ENV | Environment | development | No | | DD_TRACE_ENABLED | Enable APM tracing | false | No | | DD_PROFILING_ENABLED | Enable profiling | false | No | | DD_LOGS_ENABLED | Enable library logging outputs | false | No | | DD_LOG_LEVEL | Library logger level | info | No | | DD_METRICS_ENABLED | Enable metrics (if you wire a collector) | false | No | | DD_SITE | Datadog site realm | datadoghq.com | No | | DD_APP_KEY | Datadog App key (for REST API calls) | — (fallback API) | No | | DD_LOG_INJECTION | Inject trace/span IDs into logs | true | No | | DD_RUNTIME_METRICS_ENABLED | Collect runtime metrics from tracer | true | No | | DD_ENABLE_DISK_MONITORING | Enable disk health checks (monitoring svc) | false | No | | DD_DISK_PATH | Disk path to monitor | / | No | | DD_DISK_THRESHOLD | Disk usage threshold (%) | 90 | No |

📚 Advanced Usage

See docs/advanced.md for:

• Logging examples
• Tracing examples
• Health & metrics
• Decorators (@Trace, @Log)
• Interceptors

🐳 Docker

Example Datadog Agent setup in docs/docker.md.