@manifest-cyber/observability-ts 0.2.0 → 0.2.2

package/TRACING_GUIDE.md

@@ -1,791 +0,0 @@
-# Distributed Tracing with @manifest-cyber/observability-ts
-
-Complete guide to implementing distributed tracing across Manifest Cyber services.
-
-## Table of Contents
-
-- [Quick Start](#quick-start)
-- [Core Concepts](#core-concepts)
-- [HTTP Tracing](#http-tracing)
-- [Message Queue Tracing](#message-queue-tracing)
-- [Database Tracing](#database-tracing)
-- [Integration with logger-ts](#integration-with-logger-ts)
-- [Best Practices](#best-practices)
-- [Examples](#examples)
-
----
-
-## Quick Start
-
-### 1. Installation
-
-```bash
-npm install @manifest-cyber/observability-ts
-npm install @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-grpc
-```
-
-### 2. Initialize Tracing
-
-```typescript
-import { initTracing } from '@manifest-cyber/observability-ts';
-
-await initTracing({
-  serviceName: process.env.SERVICE_NAME || 'my-service',
-  environment: process.env.ENV || 'development',
-  exporter: {
-    type: 'otlp-grpc',
-    endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4317',
-  },
-  sampling: {
-    rate: process.env.ENV === 'production' ? 0.1 : 1.0,
-  },
-});
-```
-
-### 3. Create Spans
-
-```typescript
-import { withSpan } from '@manifest-cyber/observability-ts';
-
-const result = await withSpan(
-  'operation.name',
-  async () => {
-    return await doWork();
-  },
-  {
-    'custom.attribute': 'value',
-  },
-);
-```
-
----
-
-## Core Concepts
-
-### Traces, Spans, and Context
-
-- **Trace**: End-to-end journey of a request through your system
-- **Span**: A single operation within a trace (HTTP call, DB query, function execution)
-- **Context**: Carries trace information across service boundaries
-
-### W3C Trace Context Format
-
-```
-traceparent: 00-{trace-id}-{span-id}-{flags}
-Example: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
-```
-
-- `00`: Version
-- `trace-id`: 32-character hex (128 bits)
-- `span-id`: 16-character hex (64 bits)
-- `flags`: Sampling decision
-
----
-
-## HTTP Tracing
-
-### Client (Outgoing Requests)
-
-```typescript
-import {
-  injectTraceContext,
-  withSpan,
-  SpanStatusCode,
-} from '@manifest-cyber/observability-ts';
-
-await withSpan(
-  'http.client.request',
-  async () => {
-    const headers = {};
-    injectTraceContext(headers);
-
-    const response = await fetch('https://api.example.com/users', {
-      headers: {
-        ...headers, // Contains traceparent
-        'Content-Type': 'application/json',
-      },
-    });
-
-    return response.json();
-  },
-  {
-    'http.method': 'GET',
-    'http.url': 'https://api.example.com/users',
-    'http.status_code': 200,
-  },
-);
-```
-
-### Server (Incoming Requests)
-
-#### Express Middleware
-
-```typescript
-import {
-  extractTraceContext,
-  getTracer,
-  SpanStatusCode,
-} from '@manifest-cyber/observability-ts';
-import { context, trace } from '@opentelemetry/api';
-
-app.use((req, res, next) => {
-  const ctx = extractTraceContext(req.headers);
-  const tracer = getTracer();
-
-  context.with(ctx, () => {
-    const span = tracer.startSpan('http.server.request', {
-      attributes: {
-        'http.method': req.method,
-        'http.url': req.url,
-        'http.target': req.path,
-        'http.user_agent': req.headers['user-agent'],
-      },
-    });
-
-    // Store span for later use
-    req.span = span;
-
-    res.on('finish', () => {
-      span.setAttribute('http.status_code', res.statusCode);
-      span.setStatus({
-        code: res.statusCode >= 500 ? SpanStatusCode.ERROR : SpanStatusCode.OK,
-      });
-      span.end();
-    });
-
-    next();
-  });
-});
-```
-
----
-
-## Message Queue Tracing
-
-### Producer (Send Message)
-
-#### SQS
-
-```typescript
-import { createMessageTraceContext, withSpan } from '@manifest-cyber/observability-ts';
-
-await withSpan(
-  'messaging.send',
-  async () => {
-    const traceContext = createMessageTraceContext();
-
-    await sqs.sendMessage({
-      QueueUrl: queueUrl,
-      MessageBody: JSON.stringify(payload),
-      MessageAttributes: {
-        traceparent: {
-          DataType: 'String',
-          StringValue: traceContext.traceparent,
-        },
-      },
-    });
-  },
-  {
-    'messaging.system': 'sqs',
-    'messaging.destination': queueName,
-    'messaging.operation': 'send',
-  },
-);
-```
-
-#### RabbitMQ
-
-```typescript
-import { createMessageTraceContext, withSpan } from '@manifest-cyber/observability-ts';
-
-await withSpan(
-  'messaging.send',
-  async () => {
-    const traceContext = createMessageTraceContext();
-
-    channel.sendToQueue(queueName, Buffer.from(JSON.stringify(payload)), {
-      headers: {
-        traceparent: traceContext.traceparent,
-      },
-      persistent: true,
-    });
-  },
-  {
-    'messaging.system': 'rabbitmq',
-    'messaging.destination': queueName,
-  },
-);
-```
-
-### Consumer (Receive Message)
-
-#### SQS Consumer
-
-```typescript
-import { extractMessageTraceContext, withSpan } from '@manifest-cyber/observability-ts';
-import { context } from '@opentelemetry/api';
-
-consumer.on('message', async (message) => {
-  const ctx = extractMessageTraceContext(message.MessageAttributes);
-
-  if (ctx) {
-    await context.with(ctx, async () => {
-      await withSpan(
-        'messaging.process',
-        async () => {
-          await processMessage(message);
-        },
-        {
-          'messaging.system': 'sqs',
-          'messaging.destination': queueName,
-          'messaging.message_id': message.MessageId,
-        },
-      );
-    });
-  } else {
-    // No trace context - create new trace
-    await withSpan('messaging.process', async () => {
-      await processMessage(message);
-    });
-  }
-});
-```
-
-#### RabbitMQ Consumer
-
-```typescript
-import { extractMessageTraceContext, withSpan } from '@manifest-cyber/observability-ts';
-import { context } from '@opentelemetry/api';
-
-channel.consume(queueName, async (msg) => {
-  if (!msg) return;
-
-  const ctx = extractMessageTraceContext(msg.properties.headers);
-
-  if (ctx) {
-    await context.with(ctx, async () => {
-      await withSpan(
-        'messaging.process',
-        async () => {
-          await processMessage(msg);
-        },
-        {
-          'messaging.system': 'rabbitmq',
-          'messaging.destination': queueName,
-        },
-      );
-    });
-  } else {
-    await processMessage(msg);
-  }
-
-  channel.ack(msg);
-});
-```
-
----
-
-## Database Tracing
-
-### MongoDB
-
-```typescript
-import { withSpan } from '@manifest-cyber/observability-ts';
-
-const users = await withSpan(
-  'db.query',
-  async () => {
-    return await db.collection('users').find({ role: 'admin' }).toArray();
-  },
-  {
-    'db.system': 'mongodb',
-    'db.name': 'manifest',
-    'db.operation': 'find',
-    'db.collection': 'users',
-  },
-);
-```
-
-### PostgreSQL
-
-```typescript
-import { withSpan } from '@manifest-cyber/observability-ts';
-
-const result = await withSpan(
-  'db.query',
-  async () => {
-    return await pool.query('SELECT * FROM users WHERE role = $1', ['admin']);
-  },
-  {
-    'db.system': 'postgresql',
-    'db.operation': 'SELECT',
-    'db.statement': 'SELECT * FROM users WHERE role = $1',
-  },
-);
-```
-
----
-
-## Integration with logger-ts
-
-### Automatic Trace Correlation
-
-```typescript
-import { OtelLogger } from '@manifest-cyber/logger-ts';
-import {
-  withSpan,
-  getCurrentTraceId,
-  getCurrentSpanId,
-} from '@manifest-cyber/observability-ts';
-
-const baseLogger = getEnvLogger();
-const logger = OtelLogger.create(baseLogger, { autoTrace: true });
-
-await withSpan('process.asset', async () => {
-  // Logger automatically includes trace_id and span_id
-  logger.info('Processing asset', {
-    assetId,
-    organizationId,
-  });
-
-  // Or manually add trace info
-  logger.info('Asset processed', {
-    assetId,
-    trace_id: getCurrentTraceId(),
-    span_id: getCurrentSpanId(),
-  });
-});
-```
-
-### Message Consumer with Trace-Aware Logging
-
-```typescript
-import { createLoggerWithMessageTrace } from '@manifest-cyber/job-common';
-import { extractMessageTraceContext } from '@manifest-cyber/observability-ts';
-import { context } from '@opentelemetry/api';
-
-consumer.on('message', async (message) => {
-  const logger = createLoggerWithMessageTrace(message, baseLogger);
-  const ctx = extractMessageTraceContext(message.MessageAttributes);
-
-  if (ctx) {
-    await context.with(ctx, async () => {
-      await withSpan('job.process', async () => {
-        logger.info('Processing message', { messageId: message.MessageId });
-        await processMessage(message);
-        logger.info('Message processed successfully');
-      });
-    });
-  }
-});
-```
-
----
-
-## Security Considerations
-
-### ⚠️ Never Trust Client-Provided Trace Context
-
-**CRITICAL**: Do NOT extract `traceparent` headers from browser/client requests.
-
-```typescript
-// ❌ DANGEROUS - Accepting client trace IDs
-app.use((req, res, next) => {
-  extractTraceContext(req.headers); // SECURITY RISK!
-  next();
-});
-
-// ✅ SECURE - Only extract from trusted services
-app.use((req, res, next) => {
-  const isTrustedService = req.headers['x-internal-service'] === 'true';
-
-  if (isTrustedService && req.headers.traceparent) {
-    extractTraceContext(req.headers);
-  }
-  // Otherwise, OTEL will start a new trace (secure default)
-
-  next();
-});
-```
-
-**Why?** Client-controlled trace IDs can:
-
-- Pollute trace data with fake/malicious traces
-- Attempt to correlate unrelated requests
-- Inject arbitrary trace IDs to access other users' traces
-- Cause sampling and storage issues
-
-**Recommended Architecture:**
-
-```
-Browser (web-app)
-  └─> NO traceparent header
-      ↓
-manifest-api (Trust Boundary)
-  └─> Starts NEW trace (root span)
-      ↓
-  └─> Injects traceparent for downstream
-      ↓
-SQS/RabbitMQ
-  └─> Propagates traceparent (trusted)
-      ↓
-job-* services
-  └─> Extracts traceparent (trusted)
-      ↓
-  └─> Continues trace (same trace ID)
-```
-
-**Implementation:**
-
-```typescript
-// manifest-api: Only extract from authenticated services
-import { extractTraceContext } from '@manifest-cyber/observability-ts';
-
-export function extractTrustedTraceContext(req, res, next) {
-  // Check for service-to-service authentication
-  const serviceAuth = req.headers['x-service-auth'];
-  const isInternalService = req.headers['x-internal-service'] === 'true';
-
-  if ((serviceAuth || isInternalService) && req.headers.traceparent) {
-    // Only extract from trusted backend services
-    extractTraceContext(req.headers);
-  }
-  // For browser requests, OTEL auto-instrumentation creates new trace
-
-  next();
-}
-
-app.use(extractTrustedTraceContext);
-```
-
----
-
-## Best Practices
-
-### 1. Span Naming
-
-Follow OpenTelemetry semantic conventions:
-
-```typescript
-// ✅ Good
-'http.client.request';
-'db.query';
-'messaging.process';
-'asset.validate';
-'sbom.parse';
-
-// ❌ Bad
-'API Call';
-'Database';
-'Process Message';
-'DoWork';
-```
-
-### 2. Attribute Naming
-
-Use standard semantic conventions:
-
-```typescript
-// ✅ Good - Standard conventions
-{
-  'http.method': 'POST',
-  'http.status_code': 200,
-  'db.system': 'mongodb',
-  'messaging.system': 'sqs',
-}
-
-// ❌ Bad - Non-standard names
-{
-  'method': 'POST',
-  'status': 200,
-  'database': 'mongo',
-  'queue': 'sqs',
-}
-```
-
-### 3. Cardinality Management
-
-```typescript
-// ✅ Good - Bounded cardinality
-span.setAttribute('http.status_code', 200);
-span.setAttribute('user.role', 'admin');
-span.setAttribute('asset.type', 'sbom');
-
-// ❌ Bad - Unbounded cardinality
-span.setAttribute('user.id', 'user-12345-abcde-67890'); // Too unique
-span.setAttribute('request.timestamp', Date.now()); // Too unique
-span.setAttribute('request.body', JSON.stringify(body)); // Too large
-```
-
-### 4. Error Handling
-
-Always set span status and record exceptions:
-
-```typescript
-import {
-  withSpan,
-  SpanStatusCode,
-  recordException,
-} from '@manifest-cyber/observability-ts';
-
-// Automatic error handling
-await withSpan('operation', async () => {
-  await riskyOperation(); // Errors automatically recorded
-});
-
-// Manual error handling
-const span = createSpan({ name: 'operation' });
-try {
-  await riskyOperation();
-  span.setStatus({ code: SpanStatusCode.OK });
-} catch (error) {
-  span.recordException(error);
-  span.setStatus({
-    code: SpanStatusCode.ERROR,
-    message: error.message,
-  });
-  throw error;
-} finally {
-  span.end();
-}
-```
-
-### 5. Sampling Strategy
-
-```typescript
-// Development: 100% sampling
-await initTracing({
-  sampling: { rate: 1.0 },
-});
-
-// Production: 10% sampling, but always sample errors
-await initTracing({
-  sampling: {
-    rate: 0.1,
-    alwaysOnError: true,
-  },
-});
-```
-
----
-
-## Examples
-
-### Complete Express API Example
-
-```typescript
-import express from 'express';
-import {
-  initTracing,
-  extractTraceContext,
-  withSpan,
-  getCurrentTraceId,
-  SpanStatusCode,
-} from '@manifest-cyber/observability-ts';
-import { OtelLogger } from '@manifest-cyber/logger-ts';
-
-// Initialize tracing
-await initTracing({
-  serviceName: 'manifest-api',
-  exporter: { endpoint: 'http://localhost:4317' },
-});
-
-const app = express();
-const baseLogger = getEnvLogger();
-
-// Tracing middleware
-app.use((req, res, next) => {
-  const ctx = extractTraceContext(req.headers);
-  const logger = OtelLogger.create(baseLogger, { autoTrace: true });
-
-  context.with(ctx, () => {
-    const span = tracer.startSpan('http.server.request', {
-      attributes: {
-        'http.method': req.method,
-        'http.url': req.url,
-      },
-    });
-
-    req.span = span;
-    req.logger = logger;
-
-    res.on('finish', () => {
-      span.setAttribute('http.status_code', res.statusCode);
-      span.setStatus({
-        code: res.statusCode >= 500 ? SpanStatusCode.ERROR : SpanStatusCode.OK,
-      });
-      span.end();
-    });
-
-    next();
-  });
-});
-
-// Route handler
-app.post('/api/sboms/upload', async (req, res) => {
-  await withSpan(
-    'sbom.upload',
-    async () => {
-      req.logger.info('Processing SBOM upload', {
-        organizationId: req.body.organizationId,
-      });
-
-      // Process SBOM
-      const result = await processSBOM(req.body);
-
-      // Send to queue with trace context
-      const traceContext = createMessageTraceContext();
-      await sqs.sendMessage({
-        QueueUrl: 'sbom-process-queue',
-        MessageBody: JSON.stringify(result),
-        MessageAttributes: {
-          traceparent: {
-            DataType: 'String',
-            StringValue: traceContext.traceparent,
-          },
-        },
-      });
-
-      res.json({ success: true, traceId: getCurrentTraceId() });
-    },
-    {
-      'sbom.id': req.body.sbomId,
-      'organization.id': req.body.organizationId,
-    },
-  );
-});
-
-app.listen(3000);
-```
-
-### Complete Job Worker Example
-
-```typescript
-import {
-  initTracing,
-  extractMessageTraceContext,
-  withSpan,
-} from '@manifest-cyber/observability-ts';
-import { createLoggerWithMessageTrace } from '@manifest-cyber/job-common';
-import { Consumer } from 'sqs-consumer';
-
-// Initialize tracing
-await initTracing({
-  serviceName: 'job-sbom-process',
-  exporter: { endpoint: 'http://localhost:4317' },
-});
-
-const consumer = Consumer.create({
-  queueUrl: 'sbom-process-queue',
-  handleMessage: async (message) => {
-    const logger = createLoggerWithMessageTrace(message, baseLogger);
-    const ctx = extractMessageTraceContext(message.MessageAttributes);
-
-    if (ctx) {
-      await context.with(ctx, async () => {
-        await withSpan(
-          'job.process.sbom',
-          async () => {
-            logger.info('Processing SBOM', {
-              messageId: message.MessageId,
-            });
-
-            const sbom = JSON.parse(message.Body);
-
-            // Validate SBOM
-            await withSpan('sbom.validate', async () => {
-              await validateSBOM(sbom);
-            });
-
-            // Store in database
-            await withSpan(
-              'db.insert',
-              async () => {
-                await db.collection('sboms').insertOne(sbom);
-              },
-              {
-                'db.system': 'mongodb',
-                'db.collection': 'sboms',
-              },
-            );
-
-            logger.info('SBOM processed successfully');
-          },
-          {
-            'messaging.message_id': message.MessageId,
-            'sbom.id': sbom.id,
-          },
-        );
-      });
-    }
-  },
-});
-
-consumer.start();
-```
-
----
-
-## Troubleshooting
-
-### Traces Not Appearing
-
-1. **Check endpoint reachability**:
-
-   ```bash
-   curl -v http://localhost:4317
-   ```
-
-2. **Verify initialization**:
-
-   ```typescript
-   import { isTracingInitialized } from '@manifest-cyber/observability-ts';
-   console.log('Tracing initialized:', isTracingInitialized());
-   ```
-
-3. **Check Vector/Collector logs** for export errors
-
-### Missing Parent-Child Relationships
-
-Ensure context propagation:
-
-```typescript
-// ✅ Good - Context is propagated
-const ctx = extractTraceContext(headers);
-await context.with(ctx, async () => {
-  await withSpan('child.operation', async () => {
-    // This span will be a child
-  });
-});
-
-// ❌ Bad - Context not propagated
-const ctx = extractTraceContext(headers);
-// Not using context.with()
-await withSpan('orphaned.operation', async () => {
-  // This span won't have a parent
-});
-```
-
-### High Memory Usage
-
-Reduce sampling in production:
-
-```typescript
-await initTracing({
-  sampling: { rate: 0.1 }, // 10% instead of 100%
-});
-```
-
----
-
-## Additional Resources
-
-- [OpenTelemetry Documentation](https://opentelemetry.io/docs/)
-- [W3C Trace Context Specification](https://www.w3.org/TR/trace-context/)
-- [Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/)
-- [TRACING_IMPLEMENTATION_PLAN.md](./TRACING_IMPLEMENTATION_PLAN.md) - Full implementation roadmap
-
----
-
-**Maintained by**: Manifest Cyber Platform Team  
-**Last Updated**: November 11, 2025