@manifest-cyber/observability-ts 0.2.0-prerelease.20251111235219

package/README.md

@@ -0,0 +1,658 @@
+# @manifest-cyber/observability-ts
+
+> **Unified observability library** for Manifest Cyber's TypeScript services, providing both **Prometheus metrics** and **OpenTelemetry distributed tracing**.
+
+[![npm version](https://img.shields.io/npm/v/@manifest-cyber/observability-ts.svg)](https://www.npmjs.com/package/@manifest-cyber/observability-ts)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @manifest-cyber/observability-ts
+```
+
+### Tracing Peer Dependencies (Optional)
+
+To use tracing features, install OpenTelemetry dependencies:
+
+```bash
+npm install @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-grpc
+```
+
+---
+
+## 🚀 Quick Start
+
+### Metrics Only
+
+```typescript
+import { createCounter, startMetricsServer } from '@manifest-cyber/observability-ts';
+
+// Create a counter
+const requestsTotal = createCounter({
+  name: 'http_requests_total',
+  help: 'Total HTTP requests',
+  labelNames: ['method', 'status'],
+});
+
+// Start metrics server
+await startMetricsServer({ serviceName: 'my-service' });
+
+// Increment counter
+requestsTotal.inc({ method: 'GET', status: '200' });
+```
+
+### Metrics + Tracing
+
+```typescript
+import {
+  createCounter,
+  startMetricsServer,
+  initTracing,
+  withSpan,
+} from '@manifest-cyber/observability-ts';
+
+// Initialize both
+await initTracing({ serviceName: 'my-service' });
+await startMetricsServer({ serviceName: 'my-service' });
+
+// Use both together
+await withSpan('process.request', async (span) => {
+  span.setAttribute('user.id', userId);
+  requestsTotal.inc({ method: 'GET', status: '200' });
+  return await processRequest();
+});
+```
+
+### Tree-Shakeable Imports (Recommended)
+
+```typescript
+// Import only what you need
+import {
+  createCounter,
+  startMetricsServer,
+} from '@manifest-cyber/observability-ts/metrics';
+import { initTracing, withSpan } from '@manifest-cyber/observability-ts/tracing';
+```
+
+---
+
+## 📋 Features
+
+### Metrics (Prometheus)
+
+- ✅ **Counter, Gauge, Histogram, Summary** - Standard Prometheus metric types
+- ✅ **HTTP Metrics Server** - Built-in `/metrics` endpoint on port 9090
+- ✅ **Instrumentation Helpers** - Timer utilities, operation tracking
+- ✅ **Pre-configured Buckets** - Optimized for latency, database, and external calls
+- ✅ **Type-safe** - Full TypeScript support with generic label types
+
+### Tracing (OpenTelemetry)
+
+- ✅ **W3C Trace Context** - Standard trace propagation across HTTP and message queues
+- ✅ **OTLP Export** - Export to VictoriaTraces, Jaeger, Tempo, etc.
+- ✅ **Automatic Instrumentation** - HTTP, gRPC, database calls (via sdk-node)
+- ✅ **Manual Spans** - Fine-grained control with `createSpan()` and `withSpan()`
+- ✅ **Message Queue Integration** - SQS and RabbitMQ trace propagation helpers
+- ✅ **Logger Integration** - Correlate logs with traces using logger-ts
+- ✅ **Flexible Sampling** - Environment-based sampling configuration
+
+---
+
+## 📚 Documentation
+
+- **[TRACING_GUIDE.md](./TRACING_GUIDE.md)** - Comprehensive tracing guide with examples
+- **[TRACING_IMPLEMENTATION_PLAN.md](./TRACING_IMPLEMENTATION_PLAN.md)** - Implementation roadmap and architecture
+- **[MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md)** - Migrating from @manifest-cyber/metrics
+
+---
+
+## 🔧 API Reference
+
+### Metrics API
+
+#### Creating Metrics
+
+```typescript
+import {
+  createCounter,
+  createHistogram,
+  createGauge,
+} from '@manifest-cyber/observability-ts/metrics';
+
+// Counter - Monotonically increasing value
+const counter = createCounter({
+  name: 'operation_total',
+  help: 'Total operations',
+  labelNames: ['type', 'status'],
+});
+
+// Histogram - Distribution of values
+const histogram = createHistogram({
+  name: 'request_duration_seconds',
+  help: 'Request duration in seconds',
+  labelNames: ['route', 'method'],
+  buckets: [0.1, 0.5, 1, 2, 5],
+});
+
+// Gauge - Current value that can go up or down
+const gauge = createGauge({
+  name: 'active_connections',
+  help: 'Number of active connections',
+});
+```
+
+#### Using Metrics
+
+```typescript
+// Counter
+counter.inc({ type: 'api', status: 'success' }); // +1
+counter.inc({ type: 'api', status: 'success' }, 5); // +5
+
+// Histogram
+histogram.observe({ route: '/api/users', method: 'GET' }, 0.42);
+
+// Gauge
+gauge.inc(); // +1
+gauge.dec(); // -1
+gauge.set(42); // Set to specific value
+```
+
+#### Instrumentation Helpers
+
+```typescript
+import { Timer, trackOperation } from '@manifest-cyber/observability-ts/metrics';
+
+// Track operation duration
+const result = await trackOperation(
+  histogram,
+  { route: '/api/users', method: 'GET' },
+  async () => {
+    return await fetchUsers();
+  },
+);
+
+// Manual timer
+const timer = new Timer();
+await doWork();
+histogram.observe({ operation: 'work' }, timer.elapsedSeconds());
+```
+
+#### Metrics Server
+
+```typescript
+import { startMetricsServer } from '@manifest-cyber/observability-ts/metrics';
+
+// Start server on port 9090 (default)
+await startMetricsServer({
+  serviceName: 'my-service',
+  port: 9090,
+});
+
+// Access metrics at http://localhost:9090/metrics
+```
+
+### Tracing API
+
+#### Initialize Tracing
+
+```typescript
+import { initTracing } from '@manifest-cyber/observability-ts/tracing';
+
+await initTracing({
+  serviceName: process.env.SERVICE_NAME || 'my-service',
+  exporter: {
+    type: 'otlp-grpc',
+    endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4317',
+  },
+  sampling: {
+    type: 'parentBased',
+    parentBased: {
+      root: { type: 'traceIdRatio', ratio: 0.1 }, // 10% sampling
+    },
+  },
+});
+```
+
+#### Create Spans
+
+```typescript
+import {
+  withSpan,
+  createSpan,
+  getCurrentSpan,
+} from '@manifest-cyber/observability-ts/tracing';
+
+// Automatic span lifecycle
+const result = await withSpan('database.query', async (span) => {
+  span.setAttribute('db.statement', 'SELECT * FROM users');
+  span.setAttribute('db.name', 'manifest');
+  return await db.query('SELECT * FROM users');
+});
+
+// Manual span management
+const span = createSpan('manual.operation', { kind: SpanKind.INTERNAL });
+try {
+  span.setAttribute('custom.attribute', 'value');
+  await doWork();
+  span.setStatus({ code: SpanStatusCode.OK });
+} catch (error) {
+  span.recordException(error);
+  span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+} finally {
+  span.end();
+}
+
+// Get current span
+const activeSpan = getCurrentSpan();
+activeSpan?.setAttribute('user.id', userId);
+```
+
+#### Trace Context Propagation
+
+##### HTTP Propagation
+
+```typescript
+import {
+  injectTraceContext,
+  extractTraceContext,
+} from '@manifest-cyber/observability-ts/tracing';
+
+// HTTP Client - Inject trace context
+const headers: Record<string, string> = {};
+injectTraceContext(headers);
+
+await axios.get('https://api.example.com/users', { headers });
+
+// HTTP Server - Extract trace context
+app.use((req, res, next) => {
+  extractTraceContext(req.headers);
+  next();
+});
+```
+
+##### Message Queue Propagation
+
+```typescript
+import {
+  createMessageTraceContext,
+  extractMessageTraceContext,
+} from '@manifest-cyber/observability-ts/tracing';
+
+// SQS Producer - Add trace context to message
+await withSpan('sqs.send', async (span) => {
+  await sqs.sendMessage({
+    QueueUrl: queueUrl,
+    MessageBody: JSON.stringify(data),
+    MessageAttributes: createMessageTraceContext(),
+  });
+});
+
+// SQS Consumer - Extract trace context
+extractMessageTraceContext(message.MessageAttributes);
+await withSpan('sqs.process', async (span) => {
+  await processMessage(message);
+});
+```
+
+#### Get Trace and Span IDs
+
+```typescript
+import {
+  getCurrentTraceId,
+  getCurrentSpanId,
+} from '@manifest-cyber/observability-ts/tracing';
+
+const traceId = getCurrentTraceId();
+const spanId = getCurrentSpanId();
+
+console.log(`Processing request [trace_id=${traceId}, span_id=${spanId}]`);
+```
+
+---
+
+## 🏗️ Architecture
+
+### Package Structure
+
+```
+@manifest-cyber/observability-ts
+├── /metrics           - Prometheus metrics (tree-shakeable)
+├── /tracing           - OpenTelemetry tracing (tree-shakeable)
+└── (main export)      - Combined exports (convenience)
+```
+
+### Exports
+
+```typescript
+// Main export - Everything
+import { createCounter, initTracing } from '@manifest-cyber/observability-ts';
+
+// Subpath exports - Tree-shakeable
+import { createCounter } from '@manifest-cyber/observability-ts/metrics';
+import { initTracing } from '@manifest-cyber/observability-ts/tracing';
+```
+
+---
+
+## 🔌 Integration Examples
+
+### Express API with Metrics + Tracing
+
+```typescript
+import express from 'express';
+import {
+  createCounter,
+  createHistogram,
+  startMetricsServer,
+  initTracing,
+  withSpan,
+  extractTraceContext,
+  injectTraceContext,
+  getCurrentTraceId,
+} from '@manifest-cyber/observability-ts';
+
+// Initialize observability
+await initTracing({ serviceName: 'api-service' });
+await startMetricsServer({ serviceName: 'api-service' });
+
+// Create metrics
+const httpRequests = createCounter({
+  name: 'http_requests_total',
+  help: 'Total HTTP requests',
+  labelNames: ['method', 'route', 'status'],
+});
+
+const httpDuration = createHistogram({
+  name: 'http_request_duration_seconds',
+  help: 'HTTP request duration in seconds',
+  labelNames: ['method', 'route', 'status'],
+});
+
+const app = express();
+
+// Middleware - Extract trace context
+app.use((req, res, next) => {
+  extractTraceContext(req.headers);
+  next();
+});
+
+// Middleware - Automatic instrumentation
+app.use((req, res, next) => {
+  const start = Date.now();
+
+  res.on('finish', () => {
+    const duration = (Date.now() - start) / 1000;
+    const labels = {
+      method: req.method,
+      route: req.route?.path || req.path,
+      status: res.statusCode.toString(),
+    };
+
+    httpRequests.inc(labels);
+    httpDuration.observe(labels, duration);
+  });
+
+  next();
+});
+
+// Route handler with tracing
+app.get('/api/users/:id', async (req, res) => {
+  await withSpan('http.GET /api/users/:id', async (span) => {
+    span.setAttribute('http.method', 'GET');
+    span.setAttribute('http.route', '/api/users/:id');
+    span.setAttribute('http.target', req.path);
+    span.setAttribute('user.id', req.params.id);
+
+    const user = await fetchUser(req.params.id);
+    res.json(user);
+  });
+});
+
+app.listen(3000);
+```
+
+### Job Worker with Message Queue Tracing
+
+```typescript
+import {
+  initTracing,
+  withSpan,
+  extractMessageTraceContext,
+} from '@manifest-cyber/observability-ts';
+
+await initTracing({ serviceName: 'job-worker' });
+
+// SQS Consumer
+while (true) {
+  const messages = await sqs.receiveMessage({ QueueUrl: queueUrl });
+
+  for (const message of messages.Messages || []) {
+    // Extract trace context from message
+    extractMessageTraceContext(message.MessageAttributes);
+
+    await withSpan('sqs.process', async (span) => {
+      span.setAttribute('messaging.system', 'sqs');
+      span.setAttribute('messaging.operation', 'process');
+      span.setAttribute('messaging.message.id', message.MessageId);
+
+      const body = JSON.parse(message.Body);
+      await processJob(body);
+
+      await sqs.deleteMessage({
+        QueueUrl: queueUrl,
+        ReceiptHandle: message.ReceiptHandle,
+      });
+    });
+  }
+}
+```
+
+### Integration with logger-ts
+
+```typescript
+import { OtelLogger } from '@manifest-cyber/logger-ts';
+import { getCurrentTraceId, getCurrentSpanId } from '@manifest-cyber/observability-ts';
+
+const logger = new OtelLogger({ serviceName: 'my-service' });
+
+await withSpan('operation', async () => {
+  // Logger automatically picks up trace context
+  logger.info('Processing request', {
+    userId: '123',
+    // Trace and span IDs automatically included
+  });
+
+  // Or manually include them
+  logger.info('Manual trace correlation', {
+    trace_id: getCurrentTraceId(),
+    span_id: getCurrentSpanId(),
+  });
+});
+```
+
+---
+
+## 🌐 Environment Variables
+
+### Metrics
+
+| Variable            | Description                     | Default             |
+| ------------------- | ------------------------------- | ------------------- |
+| `SERVICE_NAME`      | Service name for metrics labels | `'unknown-service'` |
+| `MFST_METRICS_PORT` | Port for metrics HTTP server    | `9090`              |
+
+### Tracing
+
+| Variable                      | Description                    | Default                   |
+| ----------------------------- | ------------------------------ | ------------------------- |
+| `SERVICE_NAME`                | Service name for traces        | `'unknown-service'`       |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP endpoint URL              | `'http://localhost:4317'` |
+| `OTEL_TRACING_ENABLED`        | Enable/disable tracing         | `true`                    |
+| `ENV`                         | Environment (dev/staging/prod) | `'development'`           |
+
+---
+
+## 🐳 Deployment
+
+### ECS (SaaS Deployment)
+
+Services run with **Vector sidecar** that receives OTLP traces:
+
+```typescript
+await initTracing({
+  serviceName: process.env.SERVICE_NAME,
+  exporter: {
+    type: 'otlp-grpc',
+    endpoint: 'http://localhost:4317', // Vector sidecar
+  },
+});
+```
+
+**Vector config** routes traces to VictoriaTraces:
+
+```toml
+[sources.otlp]
+type = "opentelemetry"
+grpc.address = "0.0.0.0:4317"
+
+[sinks.victoria_traces]
+type = "http"
+inputs = ["otlp"]
+uri = "http://victoria-traces:4318/opentelemetry/v1/traces"
+```
+
+### Kubernetes (On-Prem Deployment)
+
+Services export to **OpenTelemetry Collector** DaemonSet:
+
+```typescript
+await initTracing({
+  serviceName: process.env.SERVICE_NAME,
+  exporter: {
+    type: 'otlp-grpc',
+    endpoint: 'http://otel-collector:4317',
+  },
+});
+```
+
+**Collector config** forwards to VictoriaTraces:
+
+```yaml
+exporters:
+  otlp:
+    endpoint: http://victoria-traces:4317
+
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [otlp]
+```
+
+---
+
+## 🔬 Sampling
+
+Recommended sampling configuration by environment:
+
+```typescript
+const getSamplingConfig = () => {
+  const env = process.env.ENV || 'development';
+
+  if (env === 'production') {
+    return {
+      type: 'parentBased' as const,
+      parentBased: {
+        root: { type: 'traceIdRatio' as const, ratio: 0.1 }, // 10%
+      },
+    };
+  }
+
+  // 100% sampling in dev/staging
+  return {
+    type: 'alwaysOn' as const,
+  };
+};
+
+await initTracing({
+  serviceName: process.env.SERVICE_NAME,
+  sampling: getSamplingConfig(),
+});
+```
+
+---
+
+## 🧪 Testing
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Build
+npm run build
+
+# Type check
+npm run type-check
+```
+
+---
+
+## 📝 Migration from @manifest-cyber/metrics
+
+See [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md) for detailed migration instructions.
+
+**TL;DR**: Update package name and imports. All existing code is backward compatible!
+
+```bash
+npm uninstall @manifest-cyber/metrics
+npm install @manifest-cyber/observability-ts
+```
+
+```typescript
+// Before
+import { createCounter } from '@manifest-cyber/metrics';
+
+// After
+import { createCounter } from '@manifest-cyber/observability-ts';
+```
+
+---
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+---
+
+## 📄 License
+
+MIT © [Manifest Cyber](https://github.com/manifest-cyber)
+
+---
+
+## 🔗 Links
+
+- **GitHub**: [manifest-cyber/observability-ts](https://github.com/manifest-cyber/observability-ts)
+- **NPM**: [@manifest-cyber/observability-ts](https://www.npmjs.com/package/@manifest-cyber/observability-ts)
+- **Issues**: [Report a bug](https://github.com/manifest-cyber/observability-ts/issues)
+- **Documentation**:
+  - [Tracing Guide](./TRACING_GUIDE.md)
+  - [Implementation Plan](./TRACING_IMPLEMENTATION_PLAN.md)
+  - [Migration Guide](./MIGRATION_GUIDE.md)
+
+---
+
+**Package Version**: 0.2.0  
+**OpenTelemetry Version**: 1.28.0  
+**Last Updated**: November 11, 2025

package/dist/src/index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @manifest-cyber/observability-ts
+ *
+ * Unified observability library for Manifest Cyber services.
+ *
+ * This library provides:
+ * - **Metrics**: Prometheus metrics collection and exposition
+ * - **Tracing**: OpenTelemetry distributed tracing
+ *
+ * @example Metrics
+ * ```typescript
+ * import { createCounter, createHistogram, startMetricsServer } from '@manifest-cyber/observability-ts';
+ *
+ * const requestsTotal = createCounter({
+ *   name: 'http_requests',
+ *   help: 'Total HTTP requests',
+ *   labelNames: ['method', 'status'],
+ * });
+ *
+ * startMetricsServer({ serviceName: 'my-service' });
+ * ```
+ *
+ * @example Tracing
+ * ```typescript
+ * import { initTracing, withSpan } from '@manifest-cyber/observability-ts';
+ *
+ * await initTracing({
+ *   serviceName: 'my-service',
+ *   exporter: { endpoint: 'http://localhost:4317' }
+ * });
+ *
+ * const result = await withSpan('operation', async () => {
+ *   return await doWork();
+ * });
+ * ```
+ *
+ * @example Modular Imports (Tree-shakeable)
+ * ```typescript
+ * // Import only what you need
+ * import { createCounter } from '@manifest-cyber/observability-ts/metrics';
+ * import { initTracing } from '@manifest-cyber/observability-ts/tracing';
+ * ```
+ */
+export { getRegistry, resetRegistry } from './metrics/registry';
+export { startMetricsServer } from './metrics/server';
+export type { MetricsServerOptions } from './metrics/server';
+export { createCounter, createHistogram, createGauge, BUCKETS, DURATION_BUCKETS, // Deprecated, use BUCKETS.DURATION
+MetricNames, ENV_KEY_SERVICE_NAME, } from './metrics/builders';
+export type { HistogramConfig } from './metrics/builders';
+export { Timer, MetricsContext, instrumentAsync, trackOperation, } from './metrics/instrumentation';
+export type { Counter, Histogram, Gauge, Registry } from 'prom-client';
+export { initTracing, isTracingInitialized, getTracerProvider, shutdownTracing, } from './tracing/setup';
+export { getTracer, createSpan, withSpan, withSpanResult, getCurrentSpan, getCurrentTraceId, getCurrentSpanId, addSpanEvent, setSpanAttributes, recordException, withActiveSpan, withActiveSpanAsync, } from './tracing/spans';
+export { injectTraceContext, extractTraceContext, getTraceparent, parseTraceparent, createContextFromTraceparent, createMessageTraceContext, extractMessageTraceContext, withExtractedContext, withExtractedContextAsync, } from './tracing/context';
+export type { Span, Tracer, Context, SpanAttributes } from '@opentelemetry/api';
+export { SpanStatusCode, SpanKind } from '@opentelemetry/api';
+export type { ServiceMetricsConfig, MetricLabels, DurationMetricOptions, Logger, } from './types';
+export type { TracingConfig, ExporterConfig, SamplingConfig, SpanOptions, TracedResult, HttpSpanAttributes, DbSpanAttributes, MessagingSpanAttributes, } from './tracing/types';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAOH,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGhE,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAG7D,OAAO,EACL,aAAa,EACb,eAAe,EACf,WAAW,EACX,OAAO,EACP,gBAAgB,EAAE,mCAAmC;AACrD,WAAW,EACX,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAG1D,OAAO,EACL,KAAK,EACL,cAAc,EACd,eAAe,EACf,cAAc,GACf,MAAM,2BAA2B,CAAC;AAGnC,YAAY,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAOvE,OAAO,EACL,WAAW,EACX,oBAAoB,EACpB,iBAAiB,EACjB,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,SAAS,EACT,UAAU,EACV,QAAQ,EACR,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,4BAA4B,EAC5B,yBAAyB,EACzB,0BAA0B,EAC1B,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,mBAAmB,CAAC;AAG3B,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAChF,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAM9D,YAAY,EACV,oBAAoB,EACpB,YAAY,EACZ,qBAAqB,EACrB,MAAM,GACP,MAAM,SAAS,CAAC;AAEjB,YAAY,EACV,aAAa,EACb,cAAc,EACd,cAAc,EACd,WAAW,EACX,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,iBAAiB,CAAC"}