@recoverysky/server-utils

RecoverySky Server

Common Node.js/TypeScript/ESM modules for RecoverySky server projects

A production-ready observability toolkit providing modular, composable utilities for logging, tracing, and metrics in Node.js applications.

Features

=

OpenTelemetry Integration

• Modular SDK factory - Clean, testable OTEL setup without singletons
• Multiple exporters - Console, OTLP, Jaeger, Prometheus
• Auto-instrumentation - HTTP, Express, GraphQL, databases
• Manual instrumentation - Simple withSpan utility
• Graceful shutdown - Automatic signal handlers with flush

=� Structured Logging

• Pino-based - High-performance JSON logging
• Pluggable transports - Console, File, OpenTelemetry
• Trace context - Automatic span/trace correlation
• Morgan integration - HTTP request logging stream

>� Production-Tested

• 319 tests passing - Unit, integration, and end-to-end
• Full type safety - TypeScript-first design
• Battle-hardened - Running in production RecoverySky infrastructure

Installation

npm install recoverysky-server
# or
pnpm add recoverysky-server
# or
yarn add recoverysky-server

Quick Start

OpenTelemetry Setup

import { createTelemetry } from 'recoverysky-server/otel'

// Initialize telemetry FIRST in your application
const sdk = createTelemetry({
  serviceName: 'my-api',
  serviceVersion: '1.0.0',
  environment: 'production',

  tracing: {
    exporter: 'otlp', // console | otlp | jaeger
  },

  metrics: {
    exporters: ['prometheus', 'otlp'],
    port: 9090, // Prometheus /metrics endpoint
  },
})

// That's it! Auto-instrumentation is active

Structured Logging

import { createLogger, createConsoleTransport } from 'recoverysky-server/logger'

const logger = createLogger({
  name: 'my-api',
  level: 'info',
  transports: [
    createConsoleTransport({ pretty: true })
  ]
})

logger.info({ userId: 123, action: 'login' }, 'User logged in')
// Output: {"level":30,"time":1234567890,"service":"my-api","userId":123,"action":"login","msg":"User logged in"}

Observability Pipeline

import { createTelemetry, withSpan } from 'recoverysky-server/otel'
import { createLogger, createOtelTransport, withTraceContext } from 'recoverysky-server/logger'

// 1. Initialize telemetry
createTelemetry({
  serviceName: 'payment-service',
  tracing: { exporter: 'otlp' },
  metrics: { exporters: ['prometheus'] },
})

// 2. Create logger with OTEL transport
const baseLogger = createLogger({
  name: 'payment-service',
  transports: [
    createOtelTransport({
      serviceName: 'payment-service',
      endpoint: 'http://localhost:4318/v1/logs'
    })
  ]
})

// 3. Add trace context plugin
const logger = withTraceContext(baseLogger)

// 4. Use in application
async function processPayment(orderId: string) {
  return withSpan('process-payment', async () => {
    // Logs automatically include trace_id and span_id!
    logger.info({ orderId }, 'Processing payment')

    const result = await chargeCard(orderId)

    logger.info({ orderId, result }, 'Payment complete')
    return result
  })
}

Package Structure

recoverysky-server/
�� src/
   �� utils/
      �� otel/              # OpenTelemetry utilities
         �� exporters/     # Trace & metrics exporters
         �� instrumentations/  # Auto-instrumentation
         �� utils/         # withSpan, resource, shutdown
         �� index.ts       # Main OTEL factory
      �� logger/            # Pino logging utilities
          �� transports/    # Console, File, OTEL transports
          �� plugins/       # Trace context, Morgan
          �� index.ts       # Main logger factory
   �� index.ts               # Package entry point
�� tests/
   �� unit/                  # 237 unit tests
   �� integration/           # 63 integration tests
   �� e2e/                   # 19 end-to-end tests
�� dist/                      # Compiled JavaScript + types

Documentation

• OpenTelemetry Guide - Detailed OTEL usage
• Logger Guide - Pino logging setup
• E2E Testing - Production observability validation
• Integration Tests - Logger behavior tests

API Reference

OpenTelemetry

import { createTelemetry, withSpan, TelemetryOptions, TelemetrySDK } from 'recoverysky-server/otel'

// Create SDK
const sdk: TelemetrySDK = createTelemetry(options: TelemetryOptions)

// SDK methods
await sdk.forceFlush()   // Flush pending telemetry (testing)
await sdk.shutdown()     // Graceful shutdown
sdk.start()              // Start SDK (called automatically)

// Manual instrumentation
const result = await withSpan('operation-name', async () => {
  // Your code here - automatically traced
  return someValue
})

Logger

import {
  createLogger,
  createConsoleTransport,
  createFileTransport,
  createOtelTransport,
  withTraceContext,
  createMorganStream,
  LoggerOptions
} from 'recoverysky-server/logger'

// Create logger
const logger = createLogger(options: LoggerOptions)

// Standard logging methods
logger.info({ key: 'value' }, 'Message')
logger.error({ err }, 'Error occurred')
logger.debug('Debug info')
logger.warn('Warning')

// Child logger with context
const childLogger = logger.child({ requestId: '123' })

// Trace-aware logger
const tracedLogger = withTraceContext(logger)

Configuration

Environment Variables

OpenTelemetry

# OTLP Exporter
OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io
OTEL_EXPORTER_OTLP_HEADERS='{"x-honeycomb-team":"YOUR_API_KEY"}'

# OTLP Metrics
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://metrics.example.com/v1/metrics

# Jaeger Exporter
JAEGER_ENDPOINT=http://localhost:14268/api/traces

# General
NODE_ENV=production

Logger

# Log level
LOG_LEVEL=info  # trace | debug | info | warn | error | fatal

# OTEL Transport
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/logs

Testing

# Run all tests (319 tests)
pnpm test

# Run by category
pnpm test:unit              # 237 unit tests
pnpm test:integration       # 63 integration tests
pnpm test:e2e               # 19 end-to-end tests

# Coverage reports
pnpm test:coverage
pnpm test:unit:coverage
pnpm test:integration:coverage

# Watch mode
pnpm test:watch

# UI mode
pnpm test:ui

Test Coverage

Category	Tests	Coverage
Unit	237 passing	Full mocking
Integration	63 passing	Real behavior
E2E	19 passing	Production stack
Total	319 passing	

Building

# Compile TypeScript
pnpm build

# Output in dist/
dist/
�� index.js
�� index.d.ts
�� utils/
    �� otel/
    �� logger/

Examples

Express Application

import express from 'express'
import { createTelemetry, withSpan } from 'recoverysky-server/otel'
import { createLogger, createOtelTransport, withTraceContext, createMorganStream } from 'recoverysky-server/logger'

// Initialize OTEL first
createTelemetry({
  serviceName: 'express-api',
  tracing: { exporter: 'otlp' },
  metrics: { port: 9090 }
})

// Create trace-aware logger
const baseLogger = createLogger({
  name: 'express-api',
  transports: [createOtelTransport({ serviceName: 'express-api' })]
})
const logger = withTraceContext(baseLogger)

const app = express()

// HTTP request logging
app.use(require('morgan')('combined', { stream: createMorganStream(logger) }))

// Traced endpoints
app.get('/users/:id', async (req, res) => {
  const user = await withSpan('fetch-user', async () => {
    logger.info({ userId: req.params.id }, 'Fetching user')
    return db.users.findById(req.params.id)
  })

  res.json(user)
})

app.listen(3000)

Background Worker

import { createTelemetry, withSpan } from 'recoverysky-server/otel'
import { createLogger } from 'recoverysky-server/logger'

createTelemetry({
  serviceName: 'order-processor',
  tracing: { exporter: 'jaeger' }
})

const logger = createLogger({ name: 'order-processor' })

async function processQueue() {
  while (true) {
    const job = await queue.pop()

    await withSpan(`process-job-${job.id}`, async () => {
      logger.info({ jobId: job.id }, 'Processing job')
      await job.execute()
      logger.info({ jobId: job.id }, 'Job complete')
    })
  }
}

Production Deployments

RecoverySky Server is running in production with:

• Grafana Loki - Log aggregation
• Grafana Tempo - Distributed tracing
• Prometheus - Metrics collection
• OpenTelemetry Collector - Telemetry pipeline

See tests/e2e/DEBUG.md for production observability stack details.

Requirements

• Node.js >= 18.0.0
• TypeScript >= 5.0.0 (for development)
• ESM - Package uses ES modules

License

ISC

Contributing

This package is internal to RecoverySky projects. For issues or feature requests, please contact the infrastructure team.

Built with d for the Recovery Sky