@payloops/observability 0.0.1 → 0.0.5

package/package.json

@@ -1,9 +1,16 @@
 {
   "name": "@payloops/observability",
-  "version": "0.0.1",
+  "version": "0.0.5",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/payloops/observability"
+  },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
   "exports": {
     ".": {
       "import": "./dist/index.js",
@@ -13,7 +20,10 @@
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts",
     "lint": "eslint src/",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "release": "npm run build && npm run typecheck && npm version patch && git push && git push --tags",
+    "release:minor": "npm run build && npm run typecheck && npm version minor && git push && git push --tags",
+    "release:major": "npm run build && npm run typecheck && npm version major && git push && git push --tags"
   },
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",

package/.env.example

@@ -1,4 +0,0 @@
-# OpenTelemetry
-OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
-OTEL_SERVICE_NAME=loop-service
-NODE_ENV=development

package/.github/workflows/ci.yml

@@ -1,38 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: pnpm/action-setup@v4
-        with:
-          version: 9
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '22'
-          cache: 'pnpm'
-
-      - name: Update npm to latest
-        run: npm install -g npm@latest
-
-      - name: Install dependencies
-        run: pnpm install
-
-      - name: Type check
-        run: pnpm typecheck
-
-      - name: Lint
-        run: pnpm lint
-
-      - name: Build
-        run: pnpm build

package/.github/workflows/publish.yml

@@ -1,40 +0,0 @@
-name: Publish to npm
-
-on:
-  release:
-    types: [created]
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-
-    permissions:
-      contents: read
-      id-token: write
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: pnpm/action-setup@v4
-        with:
-          version: 9
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '22'
-          cache: 'pnpm'
-          registry-url: 'https://registry.npmjs.org'
-
-      - name: Update npm to latest
-        run: npm install -g npm@latest
-
-      - name: Install dependencies
-        run: pnpm install
-
-      - name: Build
-        run: pnpm build
-
-      - name: Publish to npm with provenance
-        run: npm publish --access public --provenance
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/src/index.ts

@@ -1,56 +0,0 @@
-// OpenTelemetry
-export { initTelemetry, shutdownTelemetry, type TelemetryConfig } from './lib/otel';
-
-// Logger
-export { logger, createActivityLogger, createWorkflowLogger, createRequestLogger } from './lib/logger';
-
-// Correlation Context
-export {
-  getCorrelationContext,
-  withCorrelationContext,
-  withCorrelationContextAsync,
-  generateCorrelationId,
-  extractCorrelationId,
-  createPropagationHeaders,
-  createContextFromMemo,
-  CORRELATION_ID_HEADER,
-  REQUEST_ID_HEADER,
-  type CorrelationContext
-} from './lib/context';
-
-// Metrics
-export {
-  // Payment metrics
-  paymentCounter,
-  paymentAmountHistogram,
-  paymentLatencyHistogram,
-  recordPaymentAttempt,
-  recordPaymentAmount,
-  recordPaymentLatency,
-
-  // Webhook metrics
-  webhookDeliveryCounter,
-  webhookLatencyHistogram,
-  recordWebhookDelivery,
-  recordWebhookLatency,
-
-  // HTTP metrics
-  httpRequestCounter,
-  httpRequestLatencyHistogram,
-  activeRequestsGauge,
-  recordHttpRequest,
-
-  // Database metrics
-  dbQueryHistogram,
-  dbConnectionGauge,
-
-  // Workflow metrics
-  workflowStartedCounter,
-  workflowCompletedCounter,
-  workflowFailedCounter,
-  activityLatencyHistogram,
-  recordWorkflowStarted,
-  recordWorkflowCompleted,
-  recordWorkflowFailed,
-  recordActivityLatency
-} from './lib/metrics';

package/src/lib/context.ts

@@ -1,90 +0,0 @@
-import { AsyncLocalStorage } from 'async_hooks';
-import { nanoid } from 'nanoid';
-import { context, propagation } from '@opentelemetry/api';
-
-/**
- * Correlation context for tracking requests across services
- */
-export interface CorrelationContext {
-  correlationId: string;
-  merchantId?: string;
-  orderId?: string;
-  workflowId?: string;
-}
-
-const correlationStorage = new AsyncLocalStorage<CorrelationContext>();
-
-// Standard headers for correlation
-export const CORRELATION_ID_HEADER = 'X-Correlation-ID';
-export const REQUEST_ID_HEADER = 'X-Request-ID';
-
-/**
- * Get the current correlation context
- */
-export function getCorrelationContext(): CorrelationContext | undefined {
-  return correlationStorage.getStore();
-}
-
-/**
- * Run a function with a correlation context
- */
-export function withCorrelationContext<T>(ctx: CorrelationContext, fn: () => T): T {
-  return correlationStorage.run(ctx, fn);
-}
-
-/**
- * Run an async function with a correlation context
- */
-export async function withCorrelationContextAsync<T>(ctx: CorrelationContext, fn: () => Promise<T>): Promise<T> {
-  return correlationStorage.run(ctx, fn);
-}
-
-/**
- * Generate a new correlation ID
- */
-export function generateCorrelationId(): string {
-  return nanoid(21);
-}
-
-/**
- * Extract correlation ID from headers (case-insensitive)
- */
-export function extractCorrelationId(headers: Record<string, string | undefined>): string {
-  // Normalize header keys to lowercase for lookup
-  const normalizedHeaders: Record<string, string | undefined> = {};
-  for (const [key, value] of Object.entries(headers)) {
-    normalizedHeaders[key.toLowerCase()] = value;
-  }
-
-  return (
-    normalizedHeaders[CORRELATION_ID_HEADER.toLowerCase()] ||
-    normalizedHeaders[REQUEST_ID_HEADER.toLowerCase()] ||
-    generateCorrelationId()
-  );
-}
-
-/**
- * Create headers for propagating correlation context to downstream services
- */
-export function createPropagationHeaders(correlationId: string): Record<string, string> {
-  const headers: Record<string, string> = {
-    [CORRELATION_ID_HEADER]: correlationId
-  };
-
-  // Inject OpenTelemetry trace context
-  propagation.inject(context.active(), headers);
-
-  return headers;
-}
-
-/**
- * Create correlation context from Temporal workflow memo
- */
-export function createContextFromMemo(memo: Record<string, unknown>): CorrelationContext {
-  return {
-    correlationId: (memo.correlationId as string) || generateCorrelationId(),
-    merchantId: memo.merchantId as string | undefined,
-    orderId: memo.orderId as string | undefined,
-    workflowId: memo.workflowId as string | undefined
-  };
-}

package/src/lib/logger.ts

@@ -1,77 +0,0 @@
-import pino from 'pino';
-import { trace } from '@opentelemetry/api';
-import { getCorrelationContext } from './context';
-
-const NODE_ENV = process.env.NODE_ENV || 'development';
-const SERVICE_NAME = process.env.OTEL_SERVICE_NAME || 'loop';
-
-/**
- * Mixin that adds trace context to every log entry
- */
-const traceMixin = () => {
-  const mixinData: Record<string, string | undefined> = {};
-
-  // Add OpenTelemetry trace context
-  const span = trace.getActiveSpan();
-  if (span) {
-    const spanContext = span.spanContext();
-    mixinData.trace_id = spanContext.traceId;
-    mixinData.span_id = spanContext.spanId;
-  }
-
-  // Add correlation context
-  const correlationCtx = getCorrelationContext();
-  if (correlationCtx) {
-    mixinData.correlation_id = correlationCtx.correlationId;
-    if (correlationCtx.merchantId) mixinData.merchant_id = correlationCtx.merchantId;
-    if (correlationCtx.orderId) mixinData.order_id = correlationCtx.orderId;
-    if (correlationCtx.workflowId) mixinData.workflow_id = correlationCtx.workflowId;
-  }
-
-  return mixinData;
-};
-
-/**
- * Base logger with trace context mixin
- */
-export const logger = pino({
-  level: NODE_ENV === 'production' ? 'info' : 'debug',
-  mixin: traceMixin,
-  base: {
-    service: SERVICE_NAME,
-    env: NODE_ENV
-  },
-  timestamp: pino.stdTimeFunctions.isoTime,
-  transport: NODE_ENV !== 'production' ? { target: 'pino-pretty', options: { colorize: true } } : undefined
-});
-
-/**
- * Create a child logger for a specific activity
- */
-export function createActivityLogger(activityName: string, correlationId?: string) {
-  return logger.child({
-    activity: activityName,
-    correlationId
-  });
-}
-
-/**
- * Create a child logger for a specific workflow
- */
-export function createWorkflowLogger(workflowId: string, correlationId?: string) {
-  return logger.child({
-    workflowId,
-    correlationId
-  });
-}
-
-/**
- * Create a child logger for HTTP requests
- */
-export function createRequestLogger(requestId: string, method: string, path: string) {
-  return logger.child({
-    requestId,
-    method,
-    path
-  });
-}

package/src/lib/metrics.ts

@@ -1,146 +0,0 @@
-import { metrics, ValueType } from '@opentelemetry/api';
-
-// Create a meter for the application
-const meter = metrics.getMeter('payloops');
-
-// =============================================================================
-// Payment Metrics
-// =============================================================================
-
-export const paymentCounter = meter.createCounter('payments_total', {
-  description: 'Total number of payment attempts',
-  valueType: ValueType.INT
-});
-
-export const paymentAmountHistogram = meter.createHistogram('payment_amount', {
-  description: 'Distribution of payment amounts',
-  unit: 'cents',
-  valueType: ValueType.INT
-});
-
-export const paymentLatencyHistogram = meter.createHistogram('payment_latency_ms', {
-  description: 'Payment processing latency',
-  unit: 'ms',
-  valueType: ValueType.DOUBLE
-});
-
-// =============================================================================
-// Webhook Metrics
-// =============================================================================
-
-export const webhookDeliveryCounter = meter.createCounter('webhook_deliveries_total', {
-  description: 'Total webhook delivery attempts',
-  valueType: ValueType.INT
-});
-
-export const webhookLatencyHistogram = meter.createHistogram('webhook_latency_ms', {
-  description: 'Webhook delivery latency',
-  unit: 'ms',
-  valueType: ValueType.DOUBLE
-});
-
-// =============================================================================
-// HTTP Metrics
-// =============================================================================
-
-export const httpRequestCounter = meter.createCounter('http_requests_total', {
-  description: 'Total HTTP requests',
-  valueType: ValueType.INT
-});
-
-export const httpRequestLatencyHistogram = meter.createHistogram('http_request_latency_ms', {
-  description: 'HTTP request latency',
-  unit: 'ms',
-  valueType: ValueType.DOUBLE
-});
-
-export const activeRequestsGauge = meter.createUpDownCounter('http_active_requests', {
-  description: 'Number of active HTTP requests',
-  valueType: ValueType.INT
-});
-
-// =============================================================================
-// Database Metrics
-// =============================================================================
-
-export const dbQueryHistogram = meter.createHistogram('db_query_duration_ms', {
-  description: 'Database query duration',
-  unit: 'ms',
-  valueType: ValueType.DOUBLE
-});
-
-export const dbConnectionGauge = meter.createUpDownCounter('db_connections_active', {
-  description: 'Number of active database connections',
-  valueType: ValueType.INT
-});
-
-// =============================================================================
-// Temporal Workflow Metrics
-// =============================================================================
-
-export const workflowStartedCounter = meter.createCounter('workflow_started_total', {
-  description: 'Total workflows started',
-  valueType: ValueType.INT
-});
-
-export const workflowCompletedCounter = meter.createCounter('workflow_completed_total', {
-  description: 'Total workflows completed',
-  valueType: ValueType.INT
-});
-
-export const workflowFailedCounter = meter.createCounter('workflow_failed_total', {
-  description: 'Total workflows failed',
-  valueType: ValueType.INT
-});
-
-export const activityLatencyHistogram = meter.createHistogram('activity_latency_ms', {
-  description: 'Activity execution latency',
-  unit: 'ms',
-  valueType: ValueType.DOUBLE
-});
-
-// =============================================================================
-// Helper Functions
-// =============================================================================
-
-export function recordPaymentAttempt(processor: string, currency: string, status: 'success' | 'failed' | 'pending') {
-  paymentCounter.add(1, { processor, currency, status });
-}
-
-export function recordPaymentAmount(amount: number, processor: string, currency: string) {
-  paymentAmountHistogram.record(amount, { processor, currency });
-}
-
-export function recordPaymentLatency(durationMs: number, processor: string, status: 'success' | 'failed') {
-  paymentLatencyHistogram.record(durationMs, { processor, status });
-}
-
-export function recordWebhookDelivery(status: 'success' | 'failed', attempt: number) {
-  webhookDeliveryCounter.add(1, { status, attempt: String(attempt) });
-}
-
-export function recordWebhookLatency(durationMs: number, status: 'success' | 'failed') {
-  webhookLatencyHistogram.record(durationMs, { status });
-}
-
-export function recordHttpRequest(method: string, path: string, statusCode: number, durationMs: number) {
-  const statusClass = `${Math.floor(statusCode / 100)}xx`;
-  httpRequestCounter.add(1, { method, path, status_code: String(statusCode), status_class: statusClass });
-  httpRequestLatencyHistogram.record(durationMs, { method, path, status_class: statusClass });
-}
-
-export function recordWorkflowStarted(workflowType: string, taskQueue: string) {
-  workflowStartedCounter.add(1, { workflow_type: workflowType, task_queue: taskQueue });
-}
-
-export function recordWorkflowCompleted(workflowType: string, taskQueue: string, durationMs: number) {
-  workflowCompletedCounter.add(1, { workflow_type: workflowType, task_queue: taskQueue });
-}
-
-export function recordWorkflowFailed(workflowType: string, taskQueue: string, errorType: string) {
-  workflowFailedCounter.add(1, { workflow_type: workflowType, task_queue: taskQueue, error_type: errorType });
-}
-
-export function recordActivityLatency(activityType: string, durationMs: number, status: 'success' | 'failed') {
-  activityLatencyHistogram.record(durationMs, { activity_type: activityType, status });
-}

package/src/lib/otel.ts

@@ -1,75 +0,0 @@
-import { NodeSDK } from '@opentelemetry/sdk-node';
-import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
-import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
-import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
-import { Resource } from '@opentelemetry/resources';
-import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';
-import { PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
-
-let sdk: NodeSDK | null = null;
-
-export interface TelemetryConfig {
-  serviceName: string;
-  serviceVersion?: string;
-  otlpEndpoint?: string;
-  environment?: string;
-  enabledInstrumentations?: {
-    fs?: boolean;
-    http?: boolean;
-    pg?: boolean;
-  };
-}
-
-export function initTelemetry(config: TelemetryConfig | string, serviceVersion = '0.0.1'): NodeSDK {
-  if (sdk) return sdk;
-
-  // Support both string (legacy) and config object
-  const cfg: TelemetryConfig =
-    typeof config === 'string' ? { serviceName: config, serviceVersion } : config;
-
-  const otlpEndpoint = cfg.otlpEndpoint || process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4318';
-  const environment = cfg.environment || process.env.NODE_ENV || 'development';
-
-  sdk = new NodeSDK({
-    resource: new Resource({
-      [ATTR_SERVICE_NAME]: cfg.serviceName,
-      [ATTR_SERVICE_VERSION]: cfg.serviceVersion || '0.0.1',
-      'deployment.environment': environment
-    }),
-
-    traceExporter: new OTLPTraceExporter({
-      url: `${otlpEndpoint}/v1/traces`
-    }),
-
-    metricReader: new PeriodicExportingMetricReader({
-      exporter: new OTLPMetricExporter({
-        url: `${otlpEndpoint}/v1/metrics`
-      }),
-      exportIntervalMillis: 30000
-    }),
-
-    instrumentations: [
-      getNodeAutoInstrumentations({
-        '@opentelemetry/instrumentation-fs': { enabled: cfg.enabledInstrumentations?.fs ?? false },
-        '@opentelemetry/instrumentation-http': { enabled: cfg.enabledInstrumentations?.http ?? true },
-        '@opentelemetry/instrumentation-pg': { enabled: cfg.enabledInstrumentations?.pg ?? true }
-      })
-    ]
-  });
-
-  sdk.start();
-
-  process.on('SIGTERM', () => {
-    sdk
-      ?.shutdown()
-      .then(() => console.log('Telemetry shut down'))
-      .catch((err) => console.error('Telemetry shutdown error', err));
-  });
-
-  return sdk;
-}
-
-export function shutdownTelemetry(): Promise<void> {
-  if (!sdk) return Promise.resolve();
-  return sdk.shutdown();
-}

package/tsconfig.json

@@ -1,16 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "lib": ["ES2022"],
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "declaration": true,
-    "outDir": "dist",
-    "rootDir": "src"
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
-}