npm package: @onlineapps/conn-base-monitoring
Description: Monitoring connector for service-wrapper integration
Latest version: 1.0.10

# @onlineapps/conn-base-monitoring

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

## Installation
```bash
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
```javascript
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
```javascript
// 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
```bash
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
OTEL_SERVICE_NAME=my-service
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=otlp
```

### Options
```javascript
{
  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:

```javascript
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
```javascript
// 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

```bash
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](/docs/modules/monitoring.md) - Architecture overview
- [Monitoring Core](/api/shared/monitoring-core/README.md) - Factory implementation
- [Service Wrapper](/shared/connector/service-wrapper/README.md) - Integration guide

---
*Version: 1.0.0 | License: MIT*