datadog-logger-client

Shared DataDog HTTP API client. Provides structured log ingestion via DataDog's HTTP Logs v2 API — no agent required.

Background

This package sends logs to DataDog's HTTP ingestion API directly from application code. All HTTP calls are fire-and-forget and non-blocking. If DataDog is unreachable, the client retries up to 2 times then swallows the failure silently — your app is never impacted by observability failures. If the API key is missing, all calls are silently skipped.

Installation

Add to the consuming app's package.json:

{
  "dependencies": {
    "datadog-logger-client": "^1.0.0"
  }
}

Build the package before installing it in consuming apps:

cd datadog-logger-client
yarn install
yarn build

Configuration

Pass the Datadog API Key directly (or as a lazy resolver function) when constructing the factory.

Usage

Recommended: DatadogClientFactory (module-level singleton)

Use DatadogClientFactory rather than instantiating DatadogClient directly. The factory caches the client instance and re-creates it only if the resolved API key changes.

Declare the factory once at the module level:

// datadogFactory.ts
import { DatadogClientFactory } from 'datadog-logger-client'

export const datadogFactory = new DatadogClientFactory(
  'my-service-name',       // service name as it appears in DataDog
  () => settings.apiKey,   // API key — string or lazy () => string
  'nodejs',                // log source
  'my-host',               // hostname
  () => env,               // environment
  ['team:my-team'],        // optional extra tags
  'https://http-intake.logs.datadoghq.eu/api/v2/logs', // optional custom endpoint
)

Then call getClient() wherever you need to log:

import { datadogFactory } from '../datadogFactory'

const dd = datadogFactory.getClient()

dd.error('Operation failed', ['operation:myOp'])

Logging

All log methods accept a string message and an optional tags array.

dd.info('Operation completed', ['operation:myOp'])

dd.warn('Cache miss on lookup', ['operation:fetchData', 'key:abc'])

dd.error('Operation failed', ['operation:myOp'])

dd.debug('Fetched data', ['itemId:456'])

API Reference

new DatadogClientFactory(service, apiKey, source, host, env, tags?, endpoint?)

| Argument | Type | Required | Description | |-----------|-------------------------|----------|-------------| | service | string | Yes | Service name as it appears in DataDog | | apiKey | string \| (() => string) | Yes | DataDog API key, or a function that returns it (evaluated on each getClient() call). Cache is invalidated when the resolved value changes. | | source | string | Yes | Log source (e.g. nodejs) | | host | string | Yes | Hostname attached to every log entry | | env | string \| (() => string) | Yes | Environment tag (e.g. production, staging) | | tags | string[] | No | Additional tags applied to every log entry | | endpoint | string \| (() => string) | No | DataDog Logs v2 endpoint, or a function that returns it. Defaults to the US5 endpoint. Override for other regions (e.g. EU: https://http-intake.logs.datadoghq.eu/api/v2/logs). Cache is invalidated when the resolved value changes |

factory.getClient(): DatadogClient

Returns the cached DatadogClient. Re-creates the client only if the resolved API key, endpoint or environment has changed since the last call.

Methods

| Method | Description | |-------------------------------------------|--------------------------| | info(message: string, tags?: string[]) | Send an info-level log | | warn(message: string, tags?: string[]) | Send a warn-level log | | error(message: string, tags?: string[]) | Send an error-level log | | debug(message: string, tags?: string[]) | Send a debug-level log |

Public Exports

export { DatadogClient } from './DatadogClient'
export { DatadogClientFactory } from './DatadogClientFactory'
export { LogLevel } from './types'
export type { DatadogClientConfig } from './types'

Package Structure

src/
├── index.ts                  — public exports
├── types.ts                  — interfaces and types
├── constants.ts              — DataDog endpoint, retry and timeout config
├── DatadogClient.ts          — main client class
├── DatadogClientFactory.ts   — lazy init and module-level caching
└── LogsClient.ts             — DataDog Logs v2 HTTP API wrapper

Behaviour Notes

• DatadogClientFactory caches the DatadogClient instance and only re-creates it if the API key OR endpoint changes.
• If apiKey is empty, all log calls are silently skipped.
• HTTP calls are made asynchronously and do not block request handlers.
• Failed HTTP calls are retried up to 2 times with a 500ms delay between attempts.
• After retries are exhausted, the failure is swallowed and logged to console.log.
• Logs are sent to the US5 DataDog region by default (https://http-intake.logs.us5.datadoghq.com/api/v2/logs). You can override via the endpoint parameter
• Each log entry is tagged with env, plus any tags passed to the factory/client