@autonomize/otlp v0.4.1

Autonomize OTLP (@autonomize/otlp)

A lightweight, easy-to-use OpenTelemetry SDK for Node.js and Nest.js applications. This SDK provides unified instrumentation for traces, metrics, and logs with automatic context propagation and built-in support for popular frameworks.

Features

Metrics Collection

• Track custom metrics with counters, histograms, and up/down counters
• Configurable metric export intervals
• Pre-configured metric attributes

Distributed Tracing

• Automatic trace context propagation
• Built-in span creation and management
• Custom attribute support
• Support for error recording

Structured Logging

• Automatic trace correlation
• Multiple severity levels (INFO, ERROR, WARN, DEBUG)
• Custom attributes support
• Error stack trace handling

Auto-Instrumentation

• HTTP client and server
• Express.js framework
• NestJS core components
• Custom request hooks
• Health check endpoint filtering

Installation

# Using npm
npm install @autonomize/otlp

# Using yarn
yarn add @autonomize/otlp

# Using pnpm
pnpm add @autonomize/otlp

Quick Start

import { Telemetry } from '@autonomize/otlp';

// Initialize telemetry
const telemetry = new Telemetry({
    serviceName: 'your-service-name',
    environment: 'production',
    version: '1.0.0',
    otlpEndpoint: 'http://localhost:4318'
});

// Start telemetry services
await telemetry.start();

// Create metrics
const requestCounter = telemetry.createCounter({
    name: 'http_requests_total',
    description: 'Total number of HTTP requests',
    unit: 'requests'
});

const responseTime = telemetry.createHistogram({
    name: 'http_response_time',
    description: 'HTTP response time',
    unit: 'ms'
});

// Create spans for tracing
await telemetry.createSpan('operation-name', async () => {
    // Your operation code here
    telemetry.addAttributes({
        'custom.attribute': 'value'
    });
});

// Add logs with trace context
telemetry.info('Operation started', { operationType: 'process' });

// Error handling with trace correlation
try {
    // Your code
} catch (error) {
    telemetry.error('Operation failed', error, {
        operationType: 'process'
    });
    telemetry.recordError(error);
}

// Shutdown gracefully
await telemetry.shutdown();

Configuration

TelemetryConfig Options

interface TelemetryConfig {
    serviceName: string;          // Required: Service identifier
    environment: string;          // Required: Deployment environment
    version?: string;            // Optional: Service version
    otlpEndpoint?: string;       // Optional: OpenTelemetry collector endpoint
    metricIntervalMs?: number;   // Optional: Metric export interval
}

API Reference

Metrics

// Create a counter (only increases)
const counter = telemetry.createCounter({
    name: 'metric_name',
    description: 'metric description',
    unit: 'unit'
});

// Create a histogram (distribution of values)
const histogram = telemetry.createHistogram({
    name: 'metric_name',
    description: 'metric description',
    unit: 'unit'
});

// Create an up/down counter (can increase/decrease)
const upDownCounter = telemetry.createUpDownCounter({
    name: 'metric_name',
    description: 'metric description',
    unit: 'unit'
});

Tracing

// Create and manage spans
await telemetry.createSpan('operation-name', async () => {
    // Operation code
}, {
    'custom.attribute': 'value'
});

// Add attributes to current span
telemetry.addAttributes({
    'attribute.key': 'value'
});

// Record errors in current span
telemetry.recordError(error);

Logging

// Log levels with optional attributes
telemetry.info('message', attributes);
telemetry.error('message', error, attributes);
telemetry.warn('message', attributes);
telemetry.debug('message', attributes);

NestJS Integration

// main.ts
import { Telemetry } from '@autonomize/otlp';

async function bootstrap() {
    const telemetry = new Telemetry({
        serviceName: 'nest-service',
        environment: process.env.NODE_ENV
    });

    await telemetry.start();

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

    // Graceful shutdown
    process.on('SIGTERM', async () => {
        await telemetry.shutdown();
        await app.close();
    });
}

Requirements

Dependencies

See package.json for the complete list of dependencies.

Support

For issues and feature requests, please file an issue.

Additional Resources

• OpenTelemetry Documentation
• OpenTelemetry Collector
• OpenTelemetry Specification

License

MIT License - see LICENSE for details.