@manifest-cyber/observability-ts 0.2.2 → 0.2.3

package/README.md

@@ -1,211 +1,114 @@
 # @manifest-cyber/observability-ts
 
-> **Unified observability library** for Manifest Cyber's TypeScript services, providing both **Prometheus metrics** and **OpenTelemetry distributed tracing**.
+> Unified observability library for Manifest Cyber's TypeScript services - **Prometheus metrics** and **OpenTelemetry 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
+## Installation
 
 ```bash
 npm install @manifest-cyber/observability-ts
-```
-
-### Tracing Peer Dependencies (Optional)
-
-To use tracing features, install OpenTelemetry dependencies:
 
-```bash
+# Optional: for tracing features
 npm install @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-grpc
 ```
 
----
-
-## 🚀 Quick Start
+## Quick Start
 
-### Metrics Only
+### Metrics
 
 ```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
+### Tracing
 
 ```typescript
-import {
-  createCounter,
-  startMetricsServer,
-  initTracing,
-  withSpan,
-} from '@manifest-cyber/observability-ts';
+import { 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)
+### Tree-Shakeable Imports
 
 ```typescript
-// Import only what you need
-import {
-  createCounter,
-  startMetricsServer,
-} from '@manifest-cyber/observability-ts/metrics';
-import { initTracing, withSpan } from '@manifest-cyber/observability-ts/tracing';
+import { createCounter } from '@manifest-cyber/observability-ts/metrics';
+import { initTracing } 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
-
----
+## Features
 
-## 📚 Documentation
+**Metrics (Prometheus)**
+- Counter, Gauge, Histogram, Summary
+- HTTP metrics server (`/metrics` on port 9090)
+- Timer utilities and operation tracking
+- Type-safe with TypeScript generics
 
-- **[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
+**Tracing (OpenTelemetry)**
+- W3C Trace Context propagation
+- OTLP export (VictoriaTraces, Jaeger, Tempo)
+- Automatic HTTP/gRPC/database instrumentation
+- Manual span creation with `createSpan()` and `withSpan()`
+- SQS and RabbitMQ trace propagation
+- Logger integration for trace correlation
 
----
+## API Overview
 
-## 🔧 API Reference
-
-### Metrics API
-
-#### Creating Metrics
+### Metrics
 
 ```typescript
-import {
-  createCounter,
-  createHistogram,
-  createGauge,
-} from '@manifest-cyber/observability-ts/metrics';
+import { createCounter, createHistogram, createGauge } from '@manifest-cyber/observability-ts/metrics';
 
-// Counter - Monotonically increasing value
+// Counter
 const counter = createCounter({
   name: 'operation_total',
   help: 'Total operations',
   labelNames: ['type', 'status'],
 });
+counter.inc({ type: 'api', status: 'success' });
 
-// Histogram - Distribution of values
+// Histogram
 const histogram = createHistogram({
   name: 'request_duration_seconds',
-  help: 'Request duration in seconds',
+  help: 'Request duration',
   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,
+const gauge = createGauge({
+  name: 'active_connections',
+  help: 'Active connections',
 });
-
-// Access metrics at http://localhost:9090/metrics
+gauge.set(42);
 ```
 
-### Tracing API
-
-#### Initialize Tracing
+### Tracing
 
 ```typescript
-import { initTracing } from '@manifest-cyber/observability-ts/tracing';
+import { initTracing, withSpan, createSpan } from '@manifest-cyber/observability-ts/tracing';
 
+// Initialize
 await initTracing({
-  serviceName: process.env.SERVICE_NAME || 'my-service',
+  serviceName: 'my-service',
   exporter: {
     type: 'otlp-grpc',
-    endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4317',
+    endpoint: 'http://localhost:4317',
   },
   sampling: {
     type: 'parentBased',
@@ -214,132 +117,66 @@ await initTracing({
     },
   },
 });
-```
-
-#### Create Spans
-
-```typescript
-import {
-  withSpan,
-  createSpan,
-  getCurrentSpan,
-} from '@manifest-cyber/observability-ts/tracing';
 
 // Automatic span lifecycle
-const result = await withSpan('database.query', async (span) => {
+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 });
+const span = createSpan('manual.operation');
 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
+### Trace Propagation
 
 ```typescript
-import {
-  injectTraceContext,
+import { 
+  injectTraceContext, 
   extractTraceContext,
+  createMessageTraceContext,
+  extractMessageTraceContext 
 } from '@manifest-cyber/observability-ts/tracing';
 
-// HTTP Client - Inject trace context
-const headers: Record<string, string> = {};
+// HTTP Client
+const headers = {};
 injectTraceContext(headers);
-
 await axios.get('https://api.example.com/users', { headers });
 
-// HTTP Server - Extract trace context
+// HTTP Server
 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 Producer
+await sqs.sendMessage({
+  QueueUrl: queueUrl,
+  MessageBody: JSON.stringify(data),
+  MessageAttributes: createMessageTraceContext(),
 });
 
-// SQS Consumer - Extract trace context
+// SQS Consumer
 extractMessageTraceContext(message.MessageAttributes);
-await withSpan('sqs.process', async (span) => {
-  await processMessage(message);
-});
 ```
 
-#### Get Trace and Span IDs
+## Environment Variables
 
-```typescript
-import {
-  getCurrentTraceId,
-  getCurrentSpanId,
-} from '@manifest-cyber/observability-ts/tracing';
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SERVICE_NAME` | Service name | `'unknown-service'` |
+| `MFST_METRICS_PORT` | Metrics server port | `9090` |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP endpoint | `'http://localhost:4317'` |
+| `OTEL_TRACING_ENABLED` | Enable/disable tracing | `true` |
+| `ENV` | Environment (dev/staging/prod) | `'development'` |
 
-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
+## Example: Express API
 
 ```typescript
 import express from 'express';
@@ -350,15 +187,11 @@ import {
   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',
@@ -367,20 +200,14 @@ const httpRequests = createCounter({
 
 const httpDuration = createHistogram({
   name: 'http_request_duration_seconds',
-  help: 'HTTP request duration in seconds',
+  help: 'HTTP request duration',
   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', () => {
@@ -390,7 +217,6 @@ app.use((req, res, next) => {
       route: req.route?.path || req.path,
       status: res.statusCode.toString(),
     };
-
     httpRequests.inc(labels);
     httpDuration.observe(labels, duration);
   });
@@ -398,14 +224,9 @@ app.use((req, res, next) => {
   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);
   });
@@ -414,207 +235,15 @@ app.get('/api/users/:id', async (req, res) => {
 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!
+## Migration from @manifest-cyber/metrics
 
 ```bash
 npm uninstall @manifest-cyber/metrics
 npm install @manifest-cyber/observability-ts
 ```
 
+Update imports - **all existing code is backward compatible**:
+
 ```typescript
 // Before
 import { createCounter } from '@manifest-cyber/metrics';
@@ -623,36 +252,12 @@ import { createCounter } from '@manifest-cyber/metrics';
 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
+## 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)
+- **NPM**: https://www.npmjs.com/package/@manifest-cyber/observability-ts
+- **GitHub**: https://github.com/manifest-cyber/observability-ts
+- **Issues**: https://github.com/manifest-cyber/observability-ts/issues
 
----
+## License
 
-**Package Version**: 0.2.0  
-**OpenTelemetry Version**: 1.28.0  
-**Last Updated**: November 11, 2025
+MIT © [Manifest Cyber](https://github.com/manifest-cyber)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manifest-cyber/observability-ts",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Unified observability library for Manifest Cyber services - Metrics (Prometheus) and Tracing (OpenTelemetry)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",