@ciq-dev/neoiq-foundation-node 1.0.0-beta.1

package/README.md

@@ -0,0 +1,293 @@
+# @ciq-dev/neoiq-foundation-node
+
+Node.js observability foundation for CommerceIQ services. Integrates with **Groundcover** via **OpenTelemetry**.
+
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│   Our Service   │────▶│  OTEL Collector │────▶│   Groundcover   │
+│  (auth-service) │     │   (in-cluster)  │     │   (dashboard)   │
+└─────────────────┘     └─────────────────┘     └─────────────────┘
+        │                        │
+        ├── Traces (OTLP) ───────┤
+        └── Metrics (OTLP) ──────┘
+
+        │
+        └── Logs (stdout) ──────▶ Groundcover Agent scrapes container logs
+```
+
+## Features
+
+- **Traces**: Automatic span creation for HTTP requests (incoming & outgoing)
+- **Metrics**: HTTP request counts, durations, errors + custom business metrics
+- **Logs**: Structured JSON logs with automatic trace context (traceId, spanId, correlationId)
+- **Fastify Plugin**: One-line integration for request lifecycle
+- **HTTP Client**: Axios wrapper with retry, circuit breaker, and trace propagation
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install @ciq-dev/neoiq-foundation-node
+
+# Peer dependencies
+npm install @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/sdk-metrics \
+  @opentelemetry/exporter-trace-otlp-grpc @opentelemetry/exporter-metrics-otlp-grpc \
+  @opentelemetry/auto-instrumentations-node @opentelemetry/resources @opentelemetry/semantic-conventions \
+  pino pino-pretty axios axios-retry opossum fastify-plugin
+```
+
+### 2. Initialize (First Line of the App)
+
+```typescript
+import { init, logger, observabilityPlugin } from '@ciq-dev/neoiq-foundation-node';
+
+// Must be called BEFORE other imports
+init({
+  serviceName: 'neoiq-auth-service',
+  serviceVersion: '1.0.0',
+});
+```
+
+### 3. Add Fastify Plugin
+
+```typescript
+import Fastify from 'fastify';
+
+const app = Fastify();
+app.register(observabilityPlugin, { serviceName: 'neoiq-auth-service' });
+```
+
+### 4. Set Environment Variable in Kubernetes
+
+```yaml
+env:
+  - name: OTEL_EXPORTER_OTLP_ENDPOINT
+    value: 'http://otel-stack-deployment-collector.observability.svc.cluster.local:4317'
+```
+
+That's it! Traces and metrics will flow to Groundcover.
+
+---
+
+## API Reference
+
+### `init(options)`
+
+Initialize OpenTelemetry. **Must be called before other imports.**
+
+```typescript
+init({
+  serviceName: 'my-service',           // Required
+  serviceVersion: '1.0.0',             // Default: '1.0.0'
+  environment: 'production',           // Default: 'development'
+  otlpEndpoint: 'http://...:4317',     // Default: cluster OTEL Collector
+  logLevel: 'info',                    // 'debug' | 'info' | 'warn' | 'error'
+  metricsIntervalMs: 5000,             // Default: 5000 (5 seconds)
+});
+```
+
+### `logger`
+
+Structured logger with automatic trace context injection.
+
+```typescript
+import { logger } from '@ciq-dev/neoiq-foundation-node';
+
+logger.info({ userId: '123' }, 'User logged in');
+logger.error({ error: err.message }, 'Failed to process');
+```
+
+**Log Output:**
+```json
+{
+  "level": "info",
+  "time": 1703318400000,
+  "service": "neoiq-auth-service",
+  "traceId": "abc123...",
+  "spanId": "def456...",
+  "correlationId": "req-789",
+  "userId": "123",
+  "msg": "User logged in"
+}
+```
+
+### `getMeter(name, version?)`
+
+Get a meter for custom metrics.
+
+```typescript
+import { getMeter } from '@ciq-dev/neoiq-foundation-node';
+
+const meter = getMeter('neoiq-auth-service');
+
+// Counter
+const counter = meter.createCounter('logins.total');
+counter.add(1, { provider: 'workos' });
+
+// Histogram
+const histogram = meter.createHistogram('token.validation.duration');
+histogram.record(150, { status: 'success' });
+```
+
+### `observabilityPlugin`
+
+Fastify plugin for automatic request handling.
+
+```typescript
+import { observabilityPlugin } from '@ciq-dev/neoiq-foundation-node';
+
+app.register(observabilityPlugin, {
+  serviceName: 'my-service',
+  excludeRoutes: ['/health', '/metrics'],
+});
+```
+
+**Automatically:**
+- Extracts/generates correlation ID (x-request-id header)
+- Creates OpenTelemetry spans for each request
+- Logs request received/completed with full context
+- Records HTTP metrics (http.server.requests.total, http.server.request.duration)
+
+### `createHttpClient(options)`
+
+Create an Axios client with full observability.
+
+```typescript
+import { createHttpClient } from '@ciq-dev/neoiq-foundation-node';
+
+const userClient = createHttpClient({
+  baseURL: 'http://user-service:3000',
+  serviceName: 'user-service',
+  timeout: 10000,
+  retry: { retries: 3 },
+});
+
+const response = await userClient.get('/api/users/123');
+```
+
+**Automatically:**
+- Propagates trace context (traceparent header)
+- Propagates correlation ID (x-request-id header)
+- Logs outbound requests/responses
+- Records HTTP client metrics
+- Retries on 5xx errors with exponential backoff
+- Circuit breaker protection
+
+### `shutdown()`
+
+Gracefully shutdown OTEL providers. Call on application shutdown.
+
+```typescript
+import { shutdown } from '@ciq-dev/neoiq-foundation-node';
+
+process.on('SIGTERM', async () => {
+  await app.close();
+  await shutdown(); // Flush telemetry
+});
+```
+
+---
+
+## Complete Example
+
+```typescript
+// src/index.ts
+
+// STEP 1: Initialize OTEL (must be first!)
+import { init, logger, getMeter, observabilityPlugin, createHttpClient, shutdown } from '@ciq-dev/neoiq-foundation-node';
+
+init({ serviceName: 'neoiq-auth-service' });
+
+// STEP 2: Import dependencies
+import Fastify from 'fastify';
+
+const app = Fastify();
+
+// STEP 3: Register plugin
+app.register(observabilityPlugin, { serviceName: 'neoiq-auth-service' });
+
+// STEP 4: Create HTTP clients
+const userClient = createHttpClient({
+  baseURL: process.env.USER_SERVICE_URL,
+  serviceName: 'user-service',
+});
+
+// STEP 5: Custom metrics
+const meter = getMeter('neoiq-auth-service');
+const loginCounter = meter.createCounter('auth.logins.total');
+
+// STEP 6: Routes
+app.post('/api/v1/auth/login', async (req, reply) => {
+  const { provider } = req.body as any;
+  
+  loginCounter.add(1, { provider });
+  logger.info({ provider }, 'Login attempt');
+  
+  return { success: true };
+});
+
+// STEP 7: Start with graceful shutdown
+app.listen({ port: 3000 });
+
+process.on('SIGTERM', async () => {
+  await app.close();
+  await shutdown(); // Flush telemetry
+});
+```
+
+---
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTEL Collector URL | `http://otel-stack-deployment-collector.observability.svc.cluster.local:4317` |
+| `OTEL_SERVICE_VERSION` | Service version | `1.0.0` |
+| `OTEL_ENVIRONMENT` | Deployment environment | `development` |
+| `LOG_LEVEL` | Log level | `info` |
+
+---
+
+## What Gets Sent to Groundcover
+
+### Traces
+- Every HTTP request (incoming and outgoing)
+- Correlation ID linking requests across services
+- Span attributes: method, url, status_code, duration
+
+### Metrics
+- `http.server.requests.total` - Incoming request count
+- `http.server.request.duration` - Incoming request latency
+- `http.server.requests.errors` - Incoming request errors
+- `http.client.requests.total` - Outgoing request count
+- `http.client.request.duration` - Outgoing request latency
+- Custom business metrics you define
+
+### Logs (via stdout)
+- Structured JSON logs written to stdout (Pino)
+- Include traceId, spanId, correlationId for correlation
+- Groundcover Agent scrapes container logs
+- Automatically correlated with traces in Groundcover dashboard
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Type check
+npm run typecheck
+```
+
+---
+
+## License
+
+MIT
+

package/dist/http-client.d.ts

@@ -0,0 +1,80 @@
+/**
+ * HTTP Client with observability, retry, and circuit breaker.
+ *
+ * Features:
+ * - OpenTelemetry trace context propagation (traceparent header)
+ * - Correlation ID propagation (x-request-id header)
+ * - HTTP client metrics (request count, duration, errors)
+ * - Automatic retries with exponential backoff
+ * - Circuit breaker pattern
+ *
+ * Usage:
+ *   import { createHttpClient } from '@ciq-dev/neoiq-foundation-node';
+ *
+ *   const client = createHttpClient({
+ *     baseURL: 'https://api.example.com',
+ *     serviceName: 'example-api',
+ *   });
+ *
+ *   const response = await client.get('/users');
+ */
+import { AxiosInstance, AxiosRequestConfig, AxiosResponse } from 'axios';
+export interface HttpClientOptions {
+    /**
+     * Base URL for all requests.
+     */
+    baseURL: string;
+    /**
+     * Name of the target service (for metrics and logging).
+     */
+    serviceName: string;
+    /**
+     * Request timeout in milliseconds (default: 30000).
+     */
+    timeout?: number;
+    /**
+     * Retry configuration.
+     */
+    retry?: {
+        /**
+         * Maximum number of retries (default: 3).
+         */
+        retries?: number;
+        /**
+         * Base delay in milliseconds for exponential backoff (default: 1000).
+         */
+        retryDelay?: number;
+        /**
+         * HTTP status codes to retry on (default: [408, 429, 500, 502, 503, 504]).
+         */
+        retryStatusCodes?: number[];
+    };
+    /**
+     * Circuit breaker configuration.
+     */
+    circuitBreaker?: {
+        /**
+         * Whether to enable circuit breaker (default: true).
+         */
+        enabled?: boolean;
+        /**
+         * Time in ms before attempting to close the circuit (default: 30000).
+         */
+        resetTimeout?: number;
+        /**
+         * Error percentage threshold to open the circuit (default: 50).
+         */
+        errorThresholdPercentage?: number;
+    };
+    /**
+     * Additional default headers.
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * Create a configured HTTP client with full observability.
+ * Metrics are exported to OTEL Collector → Groundcover.
+ */
+export declare function createHttpClient(options: HttpClientOptions): AxiosInstance;
+export { AxiosInstance, AxiosRequestConfig, AxiosResponse };
+//# sourceMappingURL=http-client.d.ts.map

package/dist/http-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-client.d.ts","sourceRoot":"","sources":["../src/http-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAc,EACZ,aAAa,EACb,kBAAkB,EAElB,aAAa,EACd,MAAM,OAAO,CAAC;AAUf,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,KAAK,CAAC,EAAE;QACN;;WAEG;QACH,OAAO,CAAC,EAAE,MAAM,CAAC;QAEjB;;WAEG;QACH,UAAU,CAAC,EAAE,MAAM,CAAC;QAEpB;;WAEG;QACH,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;KAC7B,CAAC;IAEF;;OAEG;IACH,cAAc,CAAC,EAAE;QACf;;WAEG;QACH,OAAO,CAAC,EAAE,OAAO,CAAC;QAElB;;WAEG;QACH,YAAY,CAAC,EAAE,MAAM,CAAC;QAEtB;;WAEG;QACH,wBAAwB,CAAC,EAAE,MAAM,CAAC;KACnC,CAAC;IAEF;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAMD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,aAAa,CAqM1E;AAGD,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,aAAa,EAAE,CAAC"}

package/dist/http-client.js

@@ -0,0 +1,188 @@
+"use strict";
+/**
+ * HTTP Client with observability, retry, and circuit breaker.
+ *
+ * Features:
+ * - OpenTelemetry trace context propagation (traceparent header)
+ * - Correlation ID propagation (x-request-id header)
+ * - HTTP client metrics (request count, duration, errors)
+ * - Automatic retries with exponential backoff
+ * - Circuit breaker pattern
+ *
+ * Usage:
+ *   import { createHttpClient } from '@ciq-dev/neoiq-foundation-node';
+ *
+ *   const client = createHttpClient({
+ *     baseURL: 'https://api.example.com',
+ *     serviceName: 'example-api',
+ *   });
+ *
+ *   const response = await client.get('/users');
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHttpClient = createHttpClient;
+const axios_1 = __importDefault(require("axios"));
+const axios_retry_1 = __importDefault(require("axios-retry"));
+const opossum_1 = __importDefault(require("opossum"));
+const api_1 = require("@opentelemetry/api");
+const observability_1 = require("./observability");
+// -----------------------------------------------------------------------------
+// HTTP Client Factory
+// -----------------------------------------------------------------------------
+/**
+ * Create a configured HTTP client with full observability.
+ * Metrics are exported to OTEL Collector → Groundcover.
+ */
+function createHttpClient(options) {
+    const { baseURL, serviceName, timeout = 30000, retry = {}, circuitBreaker: cbOptions = {}, headers = {}, } = options;
+    // Create Axios instance
+    const client = axios_1.default.create({
+        baseURL,
+        timeout,
+        headers: {
+            'Content-Type': 'application/json',
+            ...headers,
+        },
+    });
+    // Setup metrics (per Groundcover guide)
+    const meter = (0, observability_1.getMeter)(`http-client-${serviceName}`);
+    const requestCounter = meter.createCounter('http.client.requests.total', {
+        description: 'Total number of outbound HTTP requests',
+    });
+    const requestDuration = meter.createHistogram('http.client.request.duration', {
+        description: 'Outbound HTTP request duration in milliseconds',
+        unit: 'ms',
+    });
+    const requestErrors = meter.createCounter('http.client.requests.errors', {
+        description: 'Total number of outbound HTTP request errors',
+    });
+    // ---------------------------------------------------------------------------
+    // Request Interceptor - Add trace context and correlation ID
+    // ---------------------------------------------------------------------------
+    client.interceptors.request.use((config) => {
+        // 1. Propagate OpenTelemetry trace context (W3C traceparent)
+        const carrier = {};
+        api_1.propagation.inject(api_1.context.active(), carrier);
+        if (carrier.traceparent) {
+            config.headers.set('traceparent', carrier.traceparent);
+        }
+        if (carrier.tracestate) {
+            config.headers.set('tracestate', carrier.tracestate);
+        }
+        // 2. Propagate correlation ID
+        const reqCtx = (0, observability_1.getRequestContext)();
+        if (reqCtx?.correlationId) {
+            config.headers.set('x-request-id', reqCtx.correlationId);
+        }
+        // 3. Add timing metadata
+        config.__startTime = Date.now();
+        // 4. Log outbound request
+        observability_1.logger.debug({
+            method: config.method?.toUpperCase(),
+            url: `${config.baseURL || ''}${config.url}`,
+            targetService: serviceName,
+            correlationId: reqCtx?.correlationId,
+        }, 'Outbound HTTP request');
+        return config;
+    });
+    // ---------------------------------------------------------------------------
+    // Response Interceptor - Log and record metrics
+    // ---------------------------------------------------------------------------
+    client.interceptors.response.use((response) => {
+        const config = response.config;
+        const durationMs = Date.now() - (config.__startTime || Date.now());
+        const reqCtx = (0, observability_1.getRequestContext)();
+        const labels = {
+            target_service: serviceName,
+            method: config.method?.toUpperCase() || 'GET',
+            status_code: String(response.status),
+        };
+        // Log success
+        observability_1.logger.debug({
+            method: config.method?.toUpperCase(),
+            url: `${config.baseURL || ''}${config.url}`,
+            targetService: serviceName,
+            statusCode: response.status,
+            durationMs,
+            correlationId: reqCtx?.correlationId,
+        }, 'Outbound HTTP response');
+        // Record metrics
+        requestCounter.add(1, labels);
+        requestDuration.record(durationMs, labels);
+        return response;
+    }, (error) => {
+        const config = error.config;
+        const durationMs = config ? Date.now() - (config.__startTime || Date.now()) : 0;
+        const statusCode = error.response?.status || 0;
+        const reqCtx = (0, observability_1.getRequestContext)();
+        const labels = {
+            target_service: serviceName,
+            method: config?.method?.toUpperCase() || 'GET',
+            status_code: String(statusCode),
+        };
+        // Log error
+        observability_1.logger.error({
+            method: config?.method?.toUpperCase(),
+            url: config ? `${config.baseURL || ''}${config.url}` : 'unknown',
+            targetService: serviceName,
+            statusCode,
+            durationMs,
+            error: error.message,
+            correlationId: reqCtx?.correlationId,
+        }, 'Outbound HTTP error');
+        // Record metrics
+        requestCounter.add(1, labels);
+        requestDuration.record(durationMs, labels);
+        requestErrors.add(1, labels);
+        return Promise.reject(error);
+    });
+    // ---------------------------------------------------------------------------
+    // Configure Retry
+    // ---------------------------------------------------------------------------
+    const retryConfig = {
+        retries: retry.retries ?? 3,
+        retryDelay: (retryCount) => {
+            const baseDelay = retry.retryDelay ?? 1000;
+            return baseDelay * Math.pow(2, retryCount - 1); // Exponential backoff
+        },
+        retryCondition: (error) => {
+            const retryStatusCodes = retry.retryStatusCodes ?? [408, 429, 500, 502, 503, 504];
+            const status = error.response?.status;
+            return !error.response || retryStatusCodes.includes(status || 0);
+        },
+        onRetry: (retryCount, error, requestConfig) => {
+            observability_1.logger.warn({
+                retryCount,
+                url: `${requestConfig.baseURL || ''}${requestConfig.url}`,
+                error: error.message,
+                targetService: serviceName,
+            }, 'Retrying HTTP request');
+        },
+    };
+    (0, axios_retry_1.default)(client, retryConfig);
+    // ---------------------------------------------------------------------------
+    // Configure Circuit Breaker (optional wrapper)
+    // ---------------------------------------------------------------------------
+    if (cbOptions.enabled !== false) {
+        const breaker = new opossum_1.default(async (config) => client.request(config), {
+            timeout,
+            resetTimeout: cbOptions.resetTimeout ?? 30000,
+            errorThresholdPercentage: cbOptions.errorThresholdPercentage ?? 50,
+            volumeThreshold: 10,
+        });
+        breaker.on('open', () => {
+            observability_1.logger.warn({ targetService: serviceName, baseURL }, 'Circuit breaker OPEN');
+        });
+        breaker.on('halfOpen', () => {
+            observability_1.logger.info({ targetService: serviceName, baseURL }, 'Circuit breaker HALF-OPEN');
+        });
+        breaker.on('close', () => {
+            observability_1.logger.info({ targetService: serviceName, baseURL }, 'Circuit breaker CLOSED');
+        });
+    }
+    return client;
+}
+//# sourceMappingURL=http-client.js.map

package/dist/http-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-client.js","sourceRoot":"","sources":["../src/http-client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @commerceiq/neoiq-foundation-node
+ *
+ * Node.js observability foundation for CommerceIQ services.
+ * Integrates with Groundcover via OpenTelemetry.
+ *
+ * Flow: App → OpenTelemetry SDK → OTEL Collector → Groundcover
+ */
+export { init, logger, getTracer, getMeter, getRequestContext, runWithContext, getTraceContext, shutdown, als, SpanStatusCode, type InitOptions, type RequestContext, } from './observability';
+export { observabilityPlugin, type PluginOptions } from './plugin';
+export { createHttpClient, type HttpClientOptions } from './http-client';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EACL,IAAI,EACJ,MAAM,EACN,SAAS,EACT,QAAQ,EACR,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,QAAQ,EACR,GAAG,EACH,cAAc,EACd,KAAK,WAAW,EAChB,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,mBAAmB,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AAGnE,OAAO,EAAE,gBAAgB,EAAE,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * @commerceiq/neoiq-foundation-node
+ *
+ * Node.js observability foundation for CommerceIQ services.
+ * Integrates with Groundcover via OpenTelemetry.
+ *
+ * Flow: App → OpenTelemetry SDK → OTEL Collector → Groundcover
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHttpClient = exports.observabilityPlugin = exports.SpanStatusCode = exports.als = exports.shutdown = exports.getTraceContext = exports.runWithContext = exports.getRequestContext = exports.getMeter = exports.getTracer = exports.logger = exports.init = void 0;
+// Core initialization and logging
+var observability_1 = require("./observability");
+Object.defineProperty(exports, "init", { enumerable: true, get: function () { return observability_1.init; } });
+Object.defineProperty(exports, "logger", { enumerable: true, get: function () { return observability_1.logger; } });
+Object.defineProperty(exports, "getTracer", { enumerable: true, get: function () { return observability_1.getTracer; } });
+Object.defineProperty(exports, "getMeter", { enumerable: true, get: function () { return observability_1.getMeter; } });
+Object.defineProperty(exports, "getRequestContext", { enumerable: true, get: function () { return observability_1.getRequestContext; } });
+Object.defineProperty(exports, "runWithContext", { enumerable: true, get: function () { return observability_1.runWithContext; } });
+Object.defineProperty(exports, "getTraceContext", { enumerable: true, get: function () { return observability_1.getTraceContext; } });
+Object.defineProperty(exports, "shutdown", { enumerable: true, get: function () { return observability_1.shutdown; } });
+Object.defineProperty(exports, "als", { enumerable: true, get: function () { return observability_1.als; } });
+Object.defineProperty(exports, "SpanStatusCode", { enumerable: true, get: function () { return observability_1.SpanStatusCode; } });
+// Fastify plugin
+var plugin_1 = require("./plugin");
+Object.defineProperty(exports, "observabilityPlugin", { enumerable: true, get: function () { return plugin_1.observabilityPlugin; } });
+// HTTP client
+var http_client_1 = require("./http-client");
+Object.defineProperty(exports, "createHttpClient", { enumerable: true, get: function () { return http_client_1.createHttpClient; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAEH,kCAAkC;AAClC,iDAayB;AAZvB,qGAAA,IAAI,OAAA;AACJ,uGAAA,MAAM,OAAA;AACN,0GAAA,SAAS,OAAA;AACT,yGAAA,QAAQ,OAAA;AACR,kHAAA,iBAAiB,OAAA;AACjB,+GAAA,cAAc,OAAA;AACd,gHAAA,eAAe,OAAA;AACf,yGAAA,QAAQ,OAAA;AACR,oGAAA,GAAG,OAAA;AACH,+GAAA,cAAc,OAAA;AAKhB,iBAAiB;AACjB,mCAAmE;AAA1D,6GAAA,mBAAmB,OAAA;AAE5B,cAAc;AACd,6CAAyE;AAAhE,+GAAA,gBAAgB,OAAA"}

package/dist/observability.d.ts

@@ -0,0 +1,132 @@
+/**
+ * OpenTelemetry initialization for Node.js services.
+ *
+ * Follows Groundcover Integration Guide - Option 2 (Via OTEL Collector)
+ *
+ * Flow: App → OpenTelemetry SDK → OTEL Collector → Groundcover
+ *
+ * Environment Variables:
+ *   OTEL_EXPORTER_OTLP_ENDPOINT: Collector URL (default: cluster OTEL Collector)
+ *   OTEL_SERVICE_NAME: Service name
+ *   OTEL_SERVICE_VERSION: Service version (default: 1.0.0)
+ *   OTEL_ENVIRONMENT: Deployment environment (default: development)
+ *
+ * Usage:
+ *   import { init, logger, getMeter } from '@ciq-dev/neoiq-foundation-node';
+ *
+ *   init({ serviceName: 'my-service' });
+ *
+ *   logger.info({ action: 'startup' }, 'Service started');
+ *
+ *   const meter = getMeter('my-service');
+ *   const counter = meter.createCounter('requests_total');
+ */
+import { SpanStatusCode } from '@opentelemetry/api';
+import pino from 'pino';
+import { AsyncLocalStorage } from 'async_hooks';
+export interface InitOptions {
+    /**
+     * Service name (required). Shows up in Groundcover.
+     */
+    serviceName: string;
+    /**
+     * Service version (default: 1.0.0).
+     */
+    serviceVersion?: string;
+    /**
+     * Deployment environment (default: development).
+     */
+    environment?: string;
+    /**
+     * OTEL Collector endpoint.
+     * Default: http://otel-stack-deployment-collector.observability.svc.cluster.local:4317
+     */
+    otlpEndpoint?: string;
+    /**
+     * Log level (default: info).
+     */
+    logLevel?: 'debug' | 'info' | 'warn' | 'error';
+    /**
+     * Metrics export interval in ms (default: 5000 per Groundcover guide).
+     */
+    metricsIntervalMs?: number;
+}
+export interface RequestContext {
+    correlationId?: string;
+    traceId?: string;
+    spanId?: string;
+}
+export declare const als: AsyncLocalStorage<RequestContext>;
+/**
+ * Initialize OpenTelemetry SDK with traces and metrics.
+ *
+ * Sends telemetry to OTEL Collector which forwards to Groundcover.
+ * Call this at the very start of the application, before other imports.
+ *
+ * @example
+ *   init({ serviceName: 'canvas-weaver' });
+ */
+export declare function init(options: InitOptions): void;
+/**
+ * Structured logger with automatic trace context injection.
+ * All logs include traceId, spanId, and correlationId when available.
+ */
+export declare const logger: {
+    info: (obj: object, msg?: string) => void;
+    error: (obj: object, msg?: string) => void;
+    warn: (obj: object, msg?: string) => void;
+    debug: (obj: object, msg?: string) => void;
+    child: (bindings: object) => pino.Logger<never, boolean>;
+};
+/**
+ * Get a tracer instance for creating spans.
+ *
+ * @param name - Tracer name (defaults to service name)
+ *
+ * @example
+ *   const tracer = getTracer();
+ *   tracer.startActiveSpan('db.query', (span) => {
+ *     // ... do work
+ *     span.end();
+ *   });
+ */
+export declare function getTracer(name?: string): import("@opentelemetry/api").Tracer;
+/**
+ * Get a meter instance for creating metrics.
+ * Metrics are exported to OTEL Collector → Groundcover.
+ *
+ * @param name - Meter name (typically service name)
+ * @param version - Meter version (default: 1.0.0)
+ *
+ * @example
+ *   const meter = getMeter('canvas-weaver');
+ *   const counter = meter.createCounter('http.requests.total');
+ *   counter.add(1, { method: 'GET', route: '/api/reports' });
+ *
+ *   const histogram = meter.createHistogram('http.request.duration');
+ *   histogram.record(150, { method: 'GET', route: '/api/reports' });
+ */
+export declare function getMeter(name: string, version?: string): import("@opentelemetry/api").Meter;
+/**
+ * Get current request context from AsyncLocalStorage.
+ */
+export declare function getRequestContext(): RequestContext | undefined;
+/**
+ * Run a function with a specific context (for manual context propagation).
+ */
+export declare function runWithContext<T>(ctx: RequestContext, fn: () => T): T;
+/**
+ * Get current trace context as a dictionary.
+ * Useful for logging or passing to external systems.
+ */
+export declare function getTraceContext(): {
+    traceId?: string;
+    spanId?: string;
+};
+/**
+ * Gracefully shutdown OTEL providers.
+ * Call this on application shutdown to flush pending telemetry.
+ */
+export declare function shutdown(): Promise<void>;
+export { SpanStatusCode };
+//# sourceMappingURL=observability.d.ts.map

package/dist/observability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.d.ts","sourceRoot":"","sources":["../src/observability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AASH,OAAO,EAAkB,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAUhD,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAE/C;;OAEG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAMD,MAAM,WAAW,cAAc;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,GAAG,mCAA0C,CAAC;AAgB3D;;;;;;;;GAQG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CA2F/C;AAMD;;;GAGG;AACH,eAAO,MAAM,MAAM;gBACL,MAAM,QAAQ,MAAM;iBACnB,MAAM,QAAQ,MAAM;gBACrB,MAAM,QAAQ,MAAM;iBACnB,MAAM,QAAQ,MAAM;sBACf,MAAM;CACzB,CAAC;AAMF;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,uCAEtC;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,MAAgB,sCAE/D;AAMD;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,GAAG,SAAS,CAE9D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAErE;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CASvE;AAMD;;;GAGG;AACH,wBAAsB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAU9C;AAGD,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/observability.js

@@ -0,0 +1,246 @@
+"use strict";
+/**
+ * OpenTelemetry initialization for Node.js services.
+ *
+ * Follows Groundcover Integration Guide - Option 2 (Via OTEL Collector)
+ *
+ * Flow: App → OpenTelemetry SDK → OTEL Collector → Groundcover
+ *
+ * Environment Variables:
+ *   OTEL_EXPORTER_OTLP_ENDPOINT: Collector URL (default: cluster OTEL Collector)
+ *   OTEL_SERVICE_NAME: Service name
+ *   OTEL_SERVICE_VERSION: Service version (default: 1.0.0)
+ *   OTEL_ENVIRONMENT: Deployment environment (default: development)
+ *
+ * Usage:
+ *   import { init, logger, getMeter } from '@ciq-dev/neoiq-foundation-node';
+ *
+ *   init({ serviceName: 'my-service' });
+ *
+ *   logger.info({ action: 'startup' }, 'Service started');
+ *
+ *   const meter = getMeter('my-service');
+ *   const counter = meter.createCounter('requests_total');
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpanStatusCode = exports.logger = exports.als = void 0;
+exports.init = init;
+exports.getTracer = getTracer;
+exports.getMeter = getMeter;
+exports.getRequestContext = getRequestContext;
+exports.runWithContext = runWithContext;
+exports.getTraceContext = getTraceContext;
+exports.shutdown = shutdown;
+const sdk_node_1 = require("@opentelemetry/sdk-node");
+const auto_instrumentations_node_1 = require("@opentelemetry/auto-instrumentations-node");
+const exporter_trace_otlp_grpc_1 = require("@opentelemetry/exporter-trace-otlp-grpc");
+const exporter_metrics_otlp_grpc_1 = require("@opentelemetry/exporter-metrics-otlp-grpc");
+const sdk_metrics_1 = require("@opentelemetry/sdk-metrics");
+const resources_1 = require("@opentelemetry/resources");
+const semantic_conventions_1 = require("@opentelemetry/semantic-conventions");
+const api_1 = require("@opentelemetry/api");
+Object.defineProperty(exports, "SpanStatusCode", { enumerable: true, get: function () { return api_1.SpanStatusCode; } });
+const pino_1 = __importDefault(require("pino"));
+const async_hooks_1 = require("async_hooks");
+// -----------------------------------------------------------------------------
+// Configuration
+// -----------------------------------------------------------------------------
+// Default OTEL Collector endpoint (per Groundcover guide - Kubernetes internal)
+const DEFAULT_OTEL_COLLECTOR = 'http://otel-stack-deployment-collector.observability.svc.cluster.local:4317';
+exports.als = new async_hooks_1.AsyncLocalStorage();
+// -----------------------------------------------------------------------------
+// Module State
+// -----------------------------------------------------------------------------
+let sdk = null;
+let meterProvider = null;
+let baseLogger;
+let serviceName = 'unknown';
+let initialized = false;
+// -----------------------------------------------------------------------------
+// Initialization
+// -----------------------------------------------------------------------------
+/**
+ * Initialize OpenTelemetry SDK with traces and metrics.
+ *
+ * Sends telemetry to OTEL Collector which forwards to Groundcover.
+ * Call this at the very start of the application, before other imports.
+ *
+ * @example
+ *   init({ serviceName: 'canvas-weaver' });
+ */
+function init(options) {
+    if (initialized) {
+        console.warn('[neoiq-foundation-node] Already initialized, skipping...');
+        return;
+    }
+    const { serviceName: svcName, serviceVersion = process.env.OTEL_SERVICE_VERSION || '1.0.0', environment = process.env.OTEL_ENVIRONMENT || 'development', otlpEndpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT || DEFAULT_OTEL_COLLECTOR, logLevel = process.env.LOG_LEVEL || 'info', metricsIntervalMs = 5000, // 5 seconds per Groundcover guide
+     } = options;
+    serviceName = svcName;
+    // 1. Create Resource (attached to all telemetry)
+    const resource = (0, resources_1.resourceFromAttributes)({
+        [semantic_conventions_1.ATTR_SERVICE_NAME]: serviceName,
+        [semantic_conventions_1.ATTR_SERVICE_VERSION]: serviceVersion,
+        'deployment.environment': environment,
+    });
+    // 2. Setup Metrics Exporter (per Groundcover guide)
+    const metricExporter = new exporter_metrics_otlp_grpc_1.OTLPMetricExporter({ url: otlpEndpoint });
+    const metricReader = new sdk_metrics_1.PeriodicExportingMetricReader({
+        exporter: metricExporter,
+        exportIntervalMillis: metricsIntervalMs,
+    });
+    meterProvider = new sdk_metrics_1.MeterProvider({
+        resource,
+        readers: [metricReader],
+    });
+    api_1.metrics.setGlobalMeterProvider(meterProvider);
+    // 3. Setup Trace Exporter
+    const traceExporter = new exporter_trace_otlp_grpc_1.OTLPTraceExporter({ url: otlpEndpoint });
+    // 4. Initialize NodeSDK with auto-instrumentation
+    sdk = new sdk_node_1.NodeSDK({
+        resource,
+        traceExporter,
+        instrumentations: [
+            (0, auto_instrumentations_node_1.getNodeAutoInstrumentations)({
+                // Disable fs instrumentation (too noisy)
+                '@opentelemetry/instrumentation-fs': { enabled: false },
+            }),
+        ],
+    });
+    sdk.start();
+    // 5. Setup Pino logger with trace context injection
+    baseLogger = (0, pino_1.default)({
+        level: logLevel,
+        base: {
+            service: serviceName,
+            version: serviceVersion,
+            env: environment,
+        },
+        mixin: () => {
+            // Inject trace context into every log (correlates logs with traces in Groundcover)
+            const span = api_1.trace.getActiveSpan();
+            const ctx = exports.als.getStore();
+            const spanContext = span?.spanContext();
+            return {
+                traceId: spanContext?.traceId || ctx?.traceId,
+                spanId: spanContext?.spanId || ctx?.spanId,
+                correlationId: ctx?.correlationId,
+            };
+        },
+        formatters: {
+            level: (label) => ({ level: label }),
+        },
+        transport: environment === 'development'
+            ? { target: 'pino-pretty', options: { colorize: true } }
+            : undefined,
+    });
+    baseLogger.info({
+        endpoint: otlpEndpoint,
+        metricsInterval: `${metricsIntervalMs}ms`,
+    }, `OpenTelemetry initialized. Sending to OTEL Collector.`);
+    initialized = true;
+}
+// -----------------------------------------------------------------------------
+// Logger API
+// -----------------------------------------------------------------------------
+/**
+ * Structured logger with automatic trace context injection.
+ * All logs include traceId, spanId, and correlationId when available.
+ */
+exports.logger = {
+    info: (obj, msg) => baseLogger?.info(obj, msg),
+    error: (obj, msg) => baseLogger?.error(obj, msg),
+    warn: (obj, msg) => baseLogger?.warn(obj, msg),
+    debug: (obj, msg) => baseLogger?.debug(obj, msg),
+    child: (bindings) => baseLogger?.child(bindings),
+};
+// -----------------------------------------------------------------------------
+// Tracer API
+// -----------------------------------------------------------------------------
+/**
+ * Get a tracer instance for creating spans.
+ *
+ * @param name - Tracer name (defaults to service name)
+ *
+ * @example
+ *   const tracer = getTracer();
+ *   tracer.startActiveSpan('db.query', (span) => {
+ *     // ... do work
+ *     span.end();
+ *   });
+ */
+function getTracer(name) {
+    return api_1.trace.getTracer(name || serviceName);
+}
+// -----------------------------------------------------------------------------
+// Meter API
+// -----------------------------------------------------------------------------
+/**
+ * Get a meter instance for creating metrics.
+ * Metrics are exported to OTEL Collector → Groundcover.
+ *
+ * @param name - Meter name (typically service name)
+ * @param version - Meter version (default: 1.0.0)
+ *
+ * @example
+ *   const meter = getMeter('canvas-weaver');
+ *   const counter = meter.createCounter('http.requests.total');
+ *   counter.add(1, { method: 'GET', route: '/api/reports' });
+ *
+ *   const histogram = meter.createHistogram('http.request.duration');
+ *   histogram.record(150, { method: 'GET', route: '/api/reports' });
+ */
+function getMeter(name, version = '1.0.0') {
+    return api_1.metrics.getMeter(name, version);
+}
+// -----------------------------------------------------------------------------
+// Context Helpers
+// -----------------------------------------------------------------------------
+/**
+ * Get current request context from AsyncLocalStorage.
+ */
+function getRequestContext() {
+    return exports.als.getStore();
+}
+/**
+ * Run a function with a specific context (for manual context propagation).
+ */
+function runWithContext(ctx, fn) {
+    return exports.als.run(ctx, fn);
+}
+/**
+ * Get current trace context as a dictionary.
+ * Useful for logging or passing to external systems.
+ */
+function getTraceContext() {
+    const span = api_1.trace.getActiveSpan();
+    if (!span)
+        return {};
+    const ctx = span.spanContext();
+    return {
+        traceId: ctx.traceId,
+        spanId: ctx.spanId,
+    };
+}
+// -----------------------------------------------------------------------------
+// Shutdown
+// -----------------------------------------------------------------------------
+/**
+ * Gracefully shutdown OTEL providers.
+ * Call this on application shutdown to flush pending telemetry.
+ */
+async function shutdown() {
+    if (!initialized)
+        return;
+    try {
+        await meterProvider?.shutdown();
+        await sdk?.shutdown();
+        console.log('[neoiq-foundation-node] OTEL shutdown complete');
+    }
+    catch (error) {
+        console.error('[neoiq-foundation-node] Error during shutdown:', error);
+    }
+}
+//# sourceMappingURL=observability.js.map

package/dist/observability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.js","sourceRoot":"","sources":["../src/observability.ts"],"names":[],"mappings":"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"}

package/dist/plugin.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Fastify Observability Plugin
+ *
+ * Automatically handles:
+ * - Correlation ID extraction/generation (x-request-id header)
+ * - OpenTelemetry trace context propagation
+ * - Request/response logging with trace context
+ * - HTTP server metrics (request count, duration)
+ *
+ * Usage:
+ *   import { observabilityPlugin } from '@ciq-dev/neoiq-foundation-node';
+ *   app.register(observabilityPlugin, { serviceName: 'my-service' });
+ */
+import { FastifyPluginAsync } from 'fastify';
+import { Span } from '@opentelemetry/api';
+interface PluginRequestContext {
+    correlationId: string;
+    traceId: string;
+    spanId: string;
+    startTime: number;
+}
+export interface PluginOptions {
+    /**
+     * Service name for metrics (required).
+     */
+    serviceName: string;
+    /**
+     * Routes to exclude from tracing/metrics (e.g., ['/health']).
+     */
+    excludeRoutes?: string[];
+}
+declare module 'fastify' {
+    interface FastifyRequest {
+        __span?: Span;
+        __requestContext?: PluginRequestContext;
+    }
+}
+export declare const observabilityPlugin: FastifyPluginAsync<PluginOptions>;
+export {};
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,kBAAkB,EAAgC,MAAM,SAAS,CAAC;AAG3E,OAAO,EAA+C,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAOvF,UAAU,oBAAoB;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAGD,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,cAAc;QACtB,MAAM,CAAC,EAAE,IAAI,CAAC;QACd,gBAAgB,CAAC,EAAE,oBAAoB,CAAC;KACzC;CACF;AA8LD,eAAO,MAAM,mBAAmB,mCAG9B,CAAC"}

package/dist/plugin.js

@@ -0,0 +1,176 @@
+"use strict";
+/**
+ * Fastify Observability Plugin
+ *
+ * Automatically handles:
+ * - Correlation ID extraction/generation (x-request-id header)
+ * - OpenTelemetry trace context propagation
+ * - Request/response logging with trace context
+ * - HTTP server metrics (request count, duration)
+ *
+ * Usage:
+ *   import { observabilityPlugin } from '@ciq-dev/neoiq-foundation-node';
+ *   app.register(observabilityPlugin, { serviceName: 'my-service' });
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.observabilityPlugin = void 0;
+const fastify_plugin_1 = __importDefault(require("fastify-plugin"));
+const crypto_1 = require("crypto");
+const api_1 = require("@opentelemetry/api");
+const observability_1 = require("./observability");
+// -----------------------------------------------------------------------------
+// Plugin Implementation
+// -----------------------------------------------------------------------------
+const plugin = async (fastify, options) => {
+    const { serviceName, excludeRoutes = ['/health', '/health/'] } = options;
+    const tracer = api_1.trace.getTracer('neoiq-foundation-node');
+    // Setup metrics (per Groundcover guide)
+    const meter = (0, observability_1.getMeter)(serviceName);
+    const requestCounter = meter.createCounter('http.server.requests.total', {
+        description: 'Total number of HTTP requests',
+    });
+    const requestDuration = meter.createHistogram('http.server.request.duration', {
+        description: 'HTTP request duration in milliseconds',
+        unit: 'ms',
+    });
+    const requestErrors = meter.createCounter('http.server.requests.errors', {
+        description: 'Total number of HTTP request errors',
+    });
+    // ---------------------------------------------------------------------------
+    // ON REQUEST - Extract context, start span
+    // ---------------------------------------------------------------------------
+    fastify.addHook('onRequest', (request, reply, done) => {
+        // Skip health checks
+        if (excludeRoutes.some((route) => request.url.startsWith(route))) {
+            done();
+            return;
+        }
+        // 1. Extract or generate correlation ID from x-request-id header
+        const correlationId = request.headers['x-request-id'] || (0, crypto_1.randomUUID)();
+        // 2. Set correlation ID in response header
+        reply.header('x-request-id', correlationId);
+        // 3. Extract parent trace context from incoming headers (W3C traceparent)
+        const parentContext = api_1.propagation.extract(api_1.context.active(), request.headers);
+        // 4. Start a new span for this request
+        const span = tracer.startSpan(`${request.method} ${request.routeOptions?.url || request.url}`, {
+            kind: 1, // SpanKind.SERVER
+            attributes: {
+                'http.method': request.method,
+                'http.url': request.url,
+                'http.route': request.routeOptions?.url || request.url,
+                'http.user_agent': request.headers['user-agent'] || '',
+                'http.correlation_id': correlationId,
+            },
+        }, parentContext);
+        // 5. Get trace/span IDs
+        const spanContext = span.spanContext();
+        const traceId = spanContext.traceId;
+        const spanId = spanContext.spanId;
+        // 6. Store context
+        const requestContext = {
+            correlationId,
+            traceId,
+            spanId,
+            startTime: Date.now(),
+        };
+        request.__span = span;
+        request.__requestContext = requestContext;
+        // 7. Run in AsyncLocalStorage context
+        observability_1.als.run({ correlationId, traceId, spanId }, () => {
+            observability_1.logger.info({
+                correlationId,
+                traceId,
+                spanId,
+                method: request.method,
+                url: request.url,
+                route: request.routeOptions?.url,
+                userAgent: request.headers['user-agent'],
+            }, 'Request received');
+            done();
+        });
+    });
+    // ---------------------------------------------------------------------------
+    // ON RESPONSE - End span, record metrics
+    // ---------------------------------------------------------------------------
+    fastify.addHook('onResponse', (request, reply, done) => {
+        const ctx = request.__requestContext;
+        const span = request.__span;
+        if (!ctx) {
+            done();
+            return;
+        }
+        const durationMs = Date.now() - ctx.startTime;
+        const route = request.routeOptions?.url || request.url;
+        const labels = {
+            method: request.method,
+            route,
+            status_code: String(reply.statusCode),
+        };
+        // Run in context for proper log correlation
+        observability_1.als.run({ correlationId: ctx.correlationId, traceId: ctx.traceId, spanId: ctx.spanId }, () => {
+            // Log response
+            observability_1.logger.info({
+                correlationId: ctx.correlationId,
+                traceId: ctx.traceId,
+                spanId: ctx.spanId,
+                method: request.method,
+                url: request.url,
+                route,
+                statusCode: reply.statusCode,
+                durationMs,
+            }, 'Request completed');
+            // Record metrics (per Groundcover guide)
+            requestCounter.add(1, labels);
+            requestDuration.record(durationMs, labels);
+            if (reply.statusCode >= 400) {
+                requestErrors.add(1, labels);
+            }
+            // End span
+            if (span) {
+                span.setStatus({
+                    code: reply.statusCode < 400 ? api_1.SpanStatusCode.OK : api_1.SpanStatusCode.ERROR,
+                });
+                span.setAttribute('http.status_code', reply.statusCode);
+                span.setAttribute('http.response_time_ms', durationMs);
+                span.end();
+            }
+            done();
+        });
+    });
+    // ---------------------------------------------------------------------------
+    // ON ERROR - Record exception on span
+    // ---------------------------------------------------------------------------
+    fastify.addHook('onError', (request, reply, error, done) => {
+        const ctx = request.__requestContext;
+        const span = request.__span;
+        if (!ctx) {
+            done();
+            return;
+        }
+        observability_1.als.run({ correlationId: ctx.correlationId, traceId: ctx.traceId, spanId: ctx.spanId }, () => {
+            observability_1.logger.error({
+                correlationId: ctx.correlationId,
+                traceId: ctx.traceId,
+                spanId: ctx.spanId,
+                method: request.method,
+                url: request.url,
+                error: error.message,
+                stack: error.stack,
+            }, 'Request failed');
+            if (span) {
+                span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: error.message });
+                span.recordException(error);
+            }
+            done();
+        });
+    });
+};
+// Export plugin
+exports.observabilityPlugin = (0, fastify_plugin_1.default)(plugin, {
+    name: 'neoiq-observability',
+    fastify: '4.x',
+});
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@ciq-dev/neoiq-foundation-node",
+  "version": "1.0.0-beta.1",
+  "description": "Node.js observability foundation for CommerceIQ services. Integrates with Groundcover via OpenTelemetry.",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "observability",
+    "opentelemetry",
+    "tracing",
+    "metrics",
+    "logging",
+    "groundcover",
+    "commerceiq",
+    "neoiq"
+  ],
+  "author": "CommerceIQ",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.7.0",
+    "@opentelemetry/auto-instrumentations-node": "^0.41.0",
+    "@opentelemetry/exporter-metrics-otlp-grpc": "^0.48.0",
+    "@opentelemetry/exporter-trace-otlp-grpc": "^0.48.0",
+    "@opentelemetry/resources": "^1.21.0",
+    "@opentelemetry/sdk-metrics": "^1.21.0",
+    "@opentelemetry/sdk-node": "^0.48.0",
+    "@opentelemetry/semantic-conventions": "^1.21.0",
+    "axios": "^1.6.0",
+    "axios-retry": "^4.0.0",
+    "fastify": "^4.25.0",
+    "fastify-plugin": "^4.5.0",
+    "opossum": "^8.1.0",
+    "pino": "^8.17.0",
+    "pino-pretty": "^10.3.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/commerceiq/neoiq-foundation-node.git"
+  }
+}