npm package: @origins-digital/dd-trace
Description: Origins Digital Datadog Tracer
Author: Origins Digital
Latest version: 2.1.4

# @origins-digital/dd-trace

A NestJS package that provides Datadog tracing integration with automatic service discovery and plugin configuration.

## Installation

```bash
npm install @origins-digital/dd-trace
```

## Features

- Automatic Datadog tracer initialization
- Environment-aware configuration
- Automatic service discovery in ECS environments
- Built-in support for multiple plugins:
  - Winston logging
  - REST servers (Koa, Express)
  - GraphQL
  - HTTP/HTTP2
  - AWS SDK
  - Message queues (AMQP)
  - Databases (PostgreSQL, MongoDB)
  - Caching (Redis)
  - ElasticSearch
- Customizable service naming
- Log injection support
- Health check endpoint exclusion

## Usage

### Basic Setup

```typescript
// main.ts
import { initTracer } from '@origins-digital/dd-trace';
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  // Initialize tracer first, before any other operations
  await initTracer();

  const app = await NestFactory.create(AppModule);
  await app.listen(3000);
}
bootstrap();
```

### Advanced Configuration

```typescript
// main.ts
import { initTracer, LogOptions } from '@origins-digital/dd-trace';
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const options: LogOptions = {
    logInjection: true,
    serviceName: 'my-service',
    tags: {
      environment: 'production',
      team: 'backend',
    },
    plugins: true,
  };

  // Initialize tracer first, before any other operations
  await initTracer(options);

  const app = await NestFactory.create(AppModule);
  await app.listen(3000);
}
bootstrap();
```

## Environment Variables

The package uses the following environment variables:

- `APP_ENV`: The application environment (e.g., 'development', 'production')
- `ECS_CONTAINER_METADATA_URI_V4`: ECS container metadata URI (for service discovery)
- `SKIP_DD_TRACE_LOCAL`: Set to 'true' to skip tracing in local environments
- `npm_package_name`: Used for service naming if not provided in options

## Plugin Configuration

The package automatically configures the following plugins:

### Logging

- Winston integration with automatic trace ID injection

### REST Servers

- Koa and Express support
- Automatic health check endpoint exclusion
- Apollo server health check exclusion

### GraphQL

- Automatic GraphQL operation tracing
- Query and mutation tracking

### HTTP/Networking

- HTTP/HTTP2 request tracing
- DNS resolution tracking
- Network connection monitoring

### AWS

- AWS SDK operation tracing
- Analytics enabled by default

### Message Queues

- AMQP message tracing
- Queue operation monitoring

### Databases

- PostgreSQL query tracing
- MongoDB operation tracking
- Connection pool monitoring

### Caching

- Redis operation tracing
- Cache hit/miss tracking

### Search

- ElasticSearch operation tracing
- Query performance monitoring

## Service Naming

Service names are automatically formatted as:

- In production: `{env}-{serviceName}`
- In local: `{serviceName}`

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.