@onlineapps/conn-base-monitoring

Overview

Monitoring connector providing OpenTelemetry-based observability for all services. Thin wrapper around monitoring-core factory.

Installation

npm install @onlineapps/conn-base-monitoring

Features

• OpenTelemetry tracing integration
• Workflow tracking with correlation IDs
• Automatic context propagation
• Performance metrics collection
• Configurable exporters

Usage

Basic Setup

const { MonitoringConnector } = require('@onlineapps/conn-base-monitoring');

const monitoring = new MonitoringConnector({
  serviceName: 'hello-service',
  enableTracing: true,
  enableMetrics: true
});

// Initialize monitoring
await monitoring.initialize();

// Create spans
const span = monitoring.startSpan('process_request');
try {
  // Your business logic
  await processRequest();
} finally {
  monitoring.endSpan(span);
}

Workflow Tracking

// Extract context from message headers
const context = monitoring.extractContext(message.headers);

// Create child span with workflow context
const span = monitoring.startSpan('step_execution', {
  workflowId: context.workflowId,
  parentSpanId: context.spanId
});

// Track workflow step
monitoring.trackWorkflowStep({
  workflowId: context.workflowId,
  step: 'validation',
  status: 'completed',
  duration: 45
});

Configuration

Environment Variables

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
OTEL_SERVICE_NAME=my-service
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=otlp

Options

{
  serviceName: 'service-name',      // Required
  enableTracing: true,              // Default: true
  enableMetrics: true,              // Default: true
  enableLogging: true,              // Default: true
  exporterUrl: 'http://...',        // Optional, overrides env
  samplingRate: 1.0,                // Default: 1.0 (100%)
}

API Reference

MonitoringConnector

initialize()

Initializes the monitoring system with configured exporters.

startSpan(name, attributes?)

Creates a new span with optional attributes.

endSpan(span)

Ends the specified span.

extractContext(headers)

Extracts tracing context from message headers.

injectContext(headers, context)

Injects tracing context into message headers.

trackWorkflowStep(data)

Records workflow step execution metrics.

getActiveWorkflows()

Returns list of currently active workflows.

shutdown()

Gracefully shuts down the monitoring system.

Integration with Service Wrapper

The monitoring connector is automatically integrated when using service-wrapper:

const { ServiceWrapper } = require('@onlineapps/service-wrapper');

const wrapper = new ServiceWrapper({
  monitoring: {
    enabled: true,
    serviceName: 'my-service'
  }
});

// Monitoring is automatically configured

Metrics Collected

Automatic Metrics

• Request duration (histogram)
• Request count (counter)
• Active requests (gauge)
• Error rate (counter)
• Queue depth (gauge)

Custom Metrics

// Increment counter
monitoring.incrementCounter('custom_metric', { tag: 'value' });

// Record histogram
monitoring.recordHistogram('processing_time', 123, { type: 'invoice' });

// Update gauge
monitoring.setGauge('queue_depth', 45);

Testing

npm test                 # Run all tests
npm run test:unit        # Unit tests only
npm run test:component   # Component tests

Dependencies

• @onlineapps/monitoring-core - Core monitoring factory
• @opentelemetry/api - OpenTelemetry API
• @opentelemetry/sdk-node - OpenTelemetry SDK

Related Documentation

• Monitoring Module - Architecture overview
• Monitoring Core - Factory implementation
• Service Wrapper - Integration guide

Version: 1.0.0 | License: MIT