@epicdm/flowstate-obs-middleware

Express middleware for Epic FlowState observability integration.

Installation

yarn add @epicdm/flowstate-obs-middleware

Quick Start

import express from 'express';
import { createObsMiddleware } from '@epicdm/flowstate-obs-middleware';

const app = express();

// Create middleware suite
const obs = createObsMiddleware({
  projectId: 'my-service',
  serviceName: 'My Service',
  version: '1.0.0',
});

// Attach middleware (order matters!)
app.use(obs.asyncContext);    // First: sets up request context
app.use(obs.requestLogger);   // Second: logs requests

// Your routes here
app.get('/api/data', (req, res) => {
  obs.logger.info('Fetching data', { userId: req.user?.id });
  res.json({ data: [] });
});

// Health check endpoint
app.get('/health', obs.healthCheck());

// Error handler must be last
app.use(obs.errorHandler);

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

Configuration

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | OBS_SERVER_URL | http://obs-server:8080 | Observability server URL | | OBS_API_KEY | - | API key for authentication | | OBS_LOG_LEVEL | info (dev) / error (prod) | Minimum log level | | OBS_ENABLED | true | Enable/disable observability | | OBS_BATCH_SIZE | 10 | Logs to batch before sending | | OBS_FLUSH_INTERVAL | 5000 | Max ms before flush | | NODE_ENV | development | Controls default log level |

Options

createObsMiddleware({
  projectId: 'my-service',      // Required: unique service identifier
  serviceName: 'My Service',    // Optional: human-readable name
  version: '1.0.0',             // Optional: service version
});

Features

Async Context

Request context is automatically propagated through async operations:

app.get('/api/users/:id', async (req, res) => {
  // Logger automatically includes requestId, traceId, etc.
  obs.logger.info('Fetching user');

  const user = await fetchUser(req.params.id);

  // Even in nested async calls
  obs.logger.info('User fetched', { userId: user.id });

  res.json(user);
});

Request Logging

All HTTP requests are automatically logged with:

• Method, path, status code
• Response time
• Request ID for correlation

Health check endpoints (/health, /healthz, etc.) are excluded.

Error Handling

Unhandled errors are:

• Logged to console with full context
• Sent to obs-server (if configured)
• Returned as 500 response with requestId

Health Checks

app.get('/health', obs.healthCheck({
  customChecks: [
    {
      name: 'database',
      check: async () => ({
        healthy: await db.ping(),
        details: { connections: db.poolSize },
      }),
    },
  ],
}));

License

Apache-2.0