@snapstack/monitoring

Monitoring and observability utilities for Snapcaster microservices based on LGTM stack (Loki, Grafana, Tempo, Mimir).

Features

• Structured Logging - Winston-based logging with Loki integration
• Distributed Tracing - OpenTelemetry-based tracing with Tempo
• Metrics Collection - Prometheus-compatible metrics with Mimir
• Express Middleware - Request/response logging, correlation IDs, and error handling

Installation

pnpm add @snapstack/monitoring

Usage

Basic Setup

import { initObservability } from '@snapstack/monitoring';

const { logger, tracer, metrics } = initObservability({
	serviceName: 'your-service-name',
	environment: process.env.NODE_ENV,
});

logger.info('Service initialized successfully');

Express Integration

import express from 'express';
import {
	initObservability,
	correlationIdMiddleware,
	requestLoggingMiddleware,
	errorHandlingMiddleware,
} from '@snapstack/monitoring';

const app = express();
const { logger } = initObservability({ serviceName: 'api-service' });

// Add middleware - order matters!
app.use(express.json());
app.use(correlationIdMiddleware());
app.use(requestLoggingMiddleware(logger));

// Your routes here
app.get('/health', (req, res) => {
	res.json({ status: 'ok' });
});

// Add error handling middleware last
app.use(errorHandlingMiddleware(logger));

app.listen(3000, () => {
	logger.info('Server started on port 3000');
});

Configuration Options

Observability Options

interface ObservabilityOptions {
	serviceName: string; // Required: Name of your service
	environment?: string; // Optional: Environment (default: process.env.NODE_ENV || 'development')
	lokiUrl?: string; // Optional: Loki URL (default: 'http://loki:3100')
	tempoUrl?: string; // Optional: Tempo URL (default: 'http://tempo:4318/v1/traces')
	metricsPort?: number; // Optional: Metrics port (default: 9464)
}

Local Development

To use this package with the LGTM stack locally:

1. Start the monitoring stack using docker-compose:

docker-compose -f docker-compose-monitoring.yml up -d

2. Configure your service to use local URLs:

const { logger, tracer, metrics } = initObservability({
	serviceName: 'your-service',
	lokiUrl: 'http://localhost:3100',
	tempoUrl: 'http://localhost:4318/v1/traces',
});

3. Access Grafana at http://localhost:3000

Advanced Usage

Individual Components

If you only need specific components:

import { createLogger, initTracing, initMetrics } from '@snapstack/monitoring';

// Just logging
const logger = createLogger({
	serviceName: 'logger-only-service',
});

// Just tracing
const tracer = initTracing({
	serviceName: 'tracer-only-service',
});

// Just metrics
const metrics = initMetrics({
	serviceName: 'metrics-only-service',
	port: 9090,
});

License

MIT