Unified Observability JS

A unified wrapper for Logs Interceptor and OpenTelemetry Instrumentation, designed for Zero Code integration.

Features

• Zero Code Initialization: Configure entirely via Environment Variables.
• Unified Identity: Consistent Service Name/Version across Logs and Traces.
• Deep Customization: Over 30 configuration options (LOGS_*).
• Toggles: Enable/Disable Logging, Metrics, or Tracing individually.

Installation

npm install unified-observability-js

Quick Start (Zero Code)

1. Configure Environment Variables:

   # Service Identity
   export OTEL_SERVICE_NAME="my-service"
   export NODE_ENV="production"
   
   # Logging Configuration (Logs Interceptor)
   export LOGS_URL="https://loki.example.com"
   export LOGS_TENANT_ID="my-tenant"
   
   # Optional Toggles
   export ENABLE_LOGGING="true"
   export ENABLE_TRACING="true"

2. Run Application:

3. Development (ts-node-dev / nodemon):

   If using ts-node-dev, enable the register script via --require or NODE_OPTIONS:

   # Option A: Command Line Flag (Recommended)
   ts-node-dev --require unified-observability-js/register --respawn server.ts
   
   # Option B: Environment Variable
   export NODE_OPTIONS="--require unified-observability-js/register"
   ts-node-dev --respawn server.ts

4. Production (PM2):

   For PM2, add node_args (best practice) or NODE_OPTIONS in your ecosystem.config.js:

   module.exports = {
     apps: [{
       name: "my-app",
       script: "./dist/index.js",
       // Option A: Specific Node Arguments (Recommended for PM2)
       node_args: "-r unified-observability-js/register",
          
       // Option B: Environment Variable
       env: {
         NODE_ENV: "production",
         NODE_OPTIONS: "--require unified-observability-js/register"
       }
     }]
   }

Configuration Reference

Core

| Variable | Description | |----------|-------------| | OTEL_SERVICE_NAME | Service Name | | OTEL_SERVICE_VERSION | Service Version | | ENABLE_LOGGING | Master switch for logging | | ENABLE_METRICS | Master switch for metrics | | ENABLE_TRACING | Master switch for tracing |

Logging (Prefix: LOGS_)

Note: LOKI_ prefix is also supported for backward compatibility.

| Variable | Description | Default | |----------|-------------|---------| | LOGS_URL | Loki Push API URL | ... | | LOGS_TENANT | Tenant ID | elven | | LOGS_TOKEN | Auth Token | - | | LOGS_COMPRESSION | gzip, brotli | brotli | | LOGS_USE_WORKERS | Use worker threads | true | | LOGS_CONNECTION_POOLING| HTTP keep-alive | true |

Buffer & Performance

| Variable | Description | |----------|-------------| | LOGS_BUFFER_MAX_SIZE | Max logs before flush | | LOGS_BUFFER_FLUSH_INTERVAL| ms between flushes | | LOGS_MAX_CONCURRENT_FLUSHES| Concurrent requests |

Filtering & Resilience

| Variable | Description | |----------|-------------| | LOGS_FILTER_LEVELS | debug,info,warn,error | | LOGS_CIRCUIT_BREAKER_ENABLED| Enable circuit breaker | | LOGS_DLQ_ENABLED | Enable Dead Letter Queue | | LOGS_INTERCEPT_CONSOLE | Capture console logs |