Universal Observability Instrumentation (Beta)

Elite Standard 2026: High-performance, resilient, and zero-dependency lock-in observability for modern JavaScript applications.

This library provides a "battery-included" but strictly modular instrumentation for specialized environments (Node.js, Serverless, Edge). It adheres to strict Semantic Conventions and ensures production-grade resiliency.

🌟 Key Features

• Universal Core: unified logic for Tracing, Metrics, and Logs.
• Zero-Code Mode: Auto-instrumentation without touching your application code.
• Strict Typing: Built with strict: true and noImplicitAny for TypeScript safety.
• Resilient: Built-in Circuit Breakers and Fallback mechanisms for exporters.
• Performance: Uses AsyncLocalStorage for zero-overhead context propagation.
• Vendor Neutral: Fully OTLP compatible (gRPC/HTTP).

🚀 Installation

npm install instrumentation-js-beta

🛠 Usage

1. Zero-Code (Recommended)

Run your application with the preloader. This automatically detects your environment and sets up instrumentation.

Environment Variables:

export OTEL_SERVICE_NAME="my-payment-service"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"
export OTEL_ZERO_CODE="true"

Run:

node --require instrumentation-js-beta/preload.js app.js

2. Manual Initialization

For more control, initialize the library at the very top of your entry file.

import { initObservability } from 'instrumentation-js-beta';

await initObservability({
  service: {
    serviceName: 'my-payment-service',
    serviceVersion: '1.0.0',
    deploymentEnvironment: 'production',
  },
  exporters: {
    protocol: 'grpc', // or 'http/protobuf'
    url: 'http://localhost:4317',
    compression: 'gzip',
  },
  sampling: {
    ratio: 1.0, // 100% sampling
    rules: [
        // Always sample specific routes
        { attributeKey: 'http.route', attributeValue: '/checkout', decision: 1 } 
    ]
  }
});

🧩 Architecture

The library is designed with a Clean Architecture approach:

• core/: Pure logic for Context, Resources, Sampling, and Attributes. No runtime dependencies.
• runtime/: Adapters for specific environments (Node, Lambda, Cloudflare Workers).
• instrumentations/: Auto-wiring for popular frameworks (Express, Fastify, GraphQL).
• api/: Public-facing Facades for Tracing and Metrics to simplify usage.

Default Instrumentations

• HTTP / HTTPS
• Express
• Fastify
• GraphQL
• Fetch (Node & Browser)

⚙️ Configuration Reference

| Option | Type | Default | Description | |--------|------|---------|-------------| | service.serviceName | string | unknown_service | Name of your service. | | service.serviceVersion | string | unknown | Version of your service. | | exporters.protocol | 'grpc' \| 'http/protobuf' | 'grpc' | OTLP transport protocol. | | exporters.compression | 'gzip' \| 'none' | 'none' | Compression for OTLP export. | | sampling.ratio | number | 1.0 | Probabilistic sampling ratio (0.0 - 1.0). |

🤝 Contributing

We enforce strict quality standards:

1. No any: All code must be strictly typed.
2. Lint: npm run lint must pass.
3. Format: Code must be formatted with Prettier.

Build & Test

npm install
npm run build
npm run lint

📄 License

MIT