Description

DDLogger Connection.js is a Node.js library that simplifies interactions with the Datadog API for sending logs, traces, and metrics. It provides an abstraction layer to streamline observability and monitoring in your applications.

Features

• Logs: Send structured logs to Datadog with customizable metadata.
• Traces: Enable distributed tracing for your services.
• Metrics: Push custom metrics for monitoring and observability.
• Retries: Built-in retry mechanism for failed requests.
• Extensible: Modular design for easy customization.

Installation

Install the package via npm:

npm install ddlogger-connectionjs

Configuration

The library uses environment variables to configure the Datadog API. Create a .env file in your project root with the following content:

DD_API_KEY=your-datadog-api-key
DD_API_LOGS=https://http-intake.logs.datadoghq.com/api/v2/logs
DD_API_TRACES=https://trace.agent.datadoghq.com/api/v0.2/traces
DD_API_METRICS=https://api.datadoghq.com/api/v1/series
DD_SERVICE_NAME=your-service-name

• DD_API_KEY: Your Datadog API key.
• DD_API_LOGS: Endpoint for sending logs.
• DD_API_TRACES: Endpoint for sending traces.
• DD_API_METRICS: Endpoint for sending metrics.
• DD_SERVICE_NAME: The name of the service associated with logs, traces, and metrics.

Usage

1. Import the Library

Import the clients for logs, traces, and metrics:

const { logClient, traceClient, metricClient } = require('ddlogger-connectionjs');

2. Sending Logs

Send logs to Datadog using the logClient:

logClient.sendLog({
    status: 'info',
    message: 'User login successful',
    source: 'auth-service',
    hostname: 'auth-host',
    tags: { environment: 'production' },
    httpContext: { headers: { 'cf-connecting-ip': '192.168.1.1' } },
    req: { jwt: 'your-jwt-token' }
});

3. Sending Traces

Send traces for distributed tracing using the traceClient:

traceClient.sendTrace({
    traceId: '1234567890abcdef',
    spanId: 'abcdef1234567890',
    name: 'auth.trace',
    resource: '/login',
    type: 'web',
    start: Date.now() * 1e6,
    duration: 5000000,
    meta: { environment: 'production' },
    httpContext: { headers: { 'cf-connecting-ip': '192.168.1.1' } },
    req: { jwt: 'your-jwt-token' }
});

4. Sending Metrics

Send custom metrics using the metricClient:

metricClient.sendMetric({
    metricName: 'auth.login.count',
    points: 1,
    tags: { environment: 'production' }
});

API Reference

LogClient

• sendLog(params): Sends a log to Datadog.
  • params:
    • status (string): Log level (info, error, etc.).
    • message (string): Log message.
    • source (string): Log source.
    • hostname (string): Hostname.
    • tags (object): Additional tags.
    • httpContext (object): HTTP context (e.g., headers).
    • req (object): Request object containing the JWT.

TraceClient

• sendTrace(params): Sends a trace to Datadog.
  • params:
    • traceId (string): Trace ID.
    • spanId (string): Span ID.
    • name (string): Trace name.
    • resource (string): Resource associated with the trace.
    • type (string): Trace type (web, api, etc.).
    • start (number): Start timestamp (in nanoseconds).
    • duration (number): Duration (in nanoseconds).
    • meta (object): Additional metadata.
    • httpContext (object): HTTP context (e.g., headers).
    • req (object): Request object containing the JWT.

MetricClient

• sendMetric(params): Sends a metric to Datadog.
  • params:
    • metricName (string): Metric name.
    • points (number | array): Metric value(s).
    • tags (object): Additional tags.

Environment Variables

| Variable | Description | Required | |-------------------|--------------------------------------|----------| | DD_API_KEY | Datadog API key | Yes | | DD_API_LOGS | Endpoint for logs | Yes | | DD_API_TRACES | Endpoint for traces | Yes | | DD_API_METRICS | Endpoint for metrics | Yes | | DD_SERVICE_NAME | Name of the service | Yes |

Available Scripts

Start the Project

Run the following command to start the project:

npm start

Project Structure

privacy-ddlogger.js/
├── src/
│   ├── service/
│   │   ├── logClient.js
│   │   ├── traceClient.js
│   │   ├── metricClient.js
│   │   └── baseClient.js
│   ├── utils/
│   │   ├── validationUtils.js
│   │   └── logger.js
│   └── config.js
├── tests/
│   ├── service/
│   │   ├── logClient.test.js
│   │   ├── traceClient.test.js
│   │   ├── metricClient.test.js
│   ├── utils/
│   │   └── validationUtils.test.js
│   └── index.test.js
├── .env
├── package.json
└── index.js

Testing

The project includes unit tests to ensure the functionality of the library. The tests cover the following components:

• LogClient: Tests for sending logs to Datadog.
• TraceClient: Tests for sending traces for distributed tracing.
• MetricClient: Tests for sending custom metrics.
• BaseClient: Tests for the core functionality, including retries and error handling.
• ValidationUtils: Tests for parameter validation.

Running Tests

To run all tests, use the following command:

npm test

Running Specific Tests

To run tests for a specific component, use the -t flag with Jest. For example:

• Run tests for LogClient:

  npm test -- -t 'LogClient'

• Run tests for TraceClient:

  npm test -- -t 'TraceClient'

• Run tests for MetricClient:

  npm test -- -t 'MetricClient'

• Run tests for BaseClient:

  npm test -- -t 'BaseClient'

• Run tests for ValidationUtils:

  npm test -- -t 'ValidationUtils'

Test Coverage

To check the test coverage, run:

npm test -- --coverage

This will generate a detailed report showing the percentage of code covered by the tests.

Test Structure

The tests are organized in the tests directory, mirroring the structure of the src directory:

tests/
├── service/
│   ├── logClient.test.js       # Tests for LogClient
│   ├── traceClient.test.js     # Tests for TraceClient
│   ├── metricClient.test.js    # Tests for MetricClient
│   ├── baseClient.test.js      # Tests for BaseClient
├── utils/
│   ├── validationUtils.test.js # Tests for ValidationUtils
└── index.test.js               # Tests for the main entry point

Mocking HTTP Requests

The project uses jest-fetch-mock to mock HTTP requests during testing. This ensures that no actual requests are sent to Datadog during the tests.

To reset mocks between tests, the beforeEach hook is used:

beforeEach(() => {
    fetchMock.resetMocks();
});

Example Test

Here’s an example of a test for the LogClient:

test('should send a log successfully', async () => {
    fetchMock.mockResponseOnce(JSON.stringify({ success: true }));

    const response = await logClient.sendLog({
        status: 'info',
        message: 'Test log message',
        source: 'test-source',
        hostname: 'test-hostname',
        tags: { environment: 'test' },
        httpContext: { headers: { 'cf-connecting-ip': '192.168.1.1' } },
        req: { jwt: 'fake-jwt-token' }
    });

    expect(fetchMock).toHaveBeenCalledTimes(1);
    expect(fetchMock.mock.calls[0][0]).toBe('https://fake-log-url');
    expect(response).toEqual({ success: true });
});

This section provides clear instructions for running and understanding the tests in your project. Let me know if you need further adjustments!