@maestro-js/metrics 1.0.0-alpha.0

package/README.md

@@ -0,0 +1,231 @@
+# Metrics
+
+## Overview
+
+The Metrics package provides unified application metrics collection that routes through the Log transport system. Emit counters, distributions, sets, and gauges as structured log messages, then attach transports to forward metrics to external systems like Sentry.
+
+## Quick Setup
+
+```ts
+import { Metrics } from '@maestro-js/metrics'
+import { Log } from '@maestro-js/log'
+import * as Sentry from '@sentry/node'
+
+// 1. Create a typed logger for metrics messages
+const metricsLogger = Log.create<[Metrics.LogMessage]>()
+
+// 2. Register the metrics service
+Metrics.Provider.register('default', Metrics.Provider.create({ logger: metricsLogger }))
+
+// 3. Attach the Sentry transport (or any custom transport)
+metricsLogger.addTransport(Metrics.transports.sentryMetrics(Sentry.metrics))
+
+// 4. Emit metrics
+Metrics.increment('order_placed', 1, { tags: { region: 'us-east' } })
+```
+
+## API Reference
+
+### Provider
+
+#### `Metrics.Provider.create(config)`
+
+Create a metrics service instance.
+
+```ts
+Metrics.Provider.create({
+  logger: Log.Logger<[Metrics.LogMessage]>
+})
+```
+
+The `logger` parameter is a typed `Log.Logger` that accepts `Metrics.LogMessage` entries. All metric emissions flow through this logger, so output destination is controlled entirely by the transports attached to it.
+
+#### `Metrics.Provider.register(name, service)`
+
+Register a metrics service instance in the named registry.
+
+```ts
+Metrics.Provider.register('default', Metrics.Provider.create({ logger: metricsLogger }))
+```
+
+### Metric Methods
+
+All four methods are available directly on the `Metrics` facade (resolving the `'default'` provider) or on a named provider instance.
+
+#### `Metrics.increment(name, value?, data?)`
+
+Emit a counter metric, incrementing by `value` (defaults to 1 when omitted).
+
+```ts
+Metrics.increment('user_signup')                                    // increment by 1
+Metrics.increment('items_purchased', 3, { tags: { store: 'web' } }) // increment by 3
+```
+
+#### `Metrics.distribution(name, value, data?)`
+
+Emit a distribution metric for statistical aggregation (p50, p95, p99).
+
+```ts
+Metrics.distribution('api_response_time', 142, { unit: 'millisecond' })
+Metrics.distribution('payload_size', 2048, { unit: 'byte', tags: { endpoint: '/upload' } })
+```
+
+#### `Metrics.set(name, value, data?)`
+
+Emit a set metric tracking unique string or integer values.
+
+```ts
+Metrics.set('unique_customers', 'cust_123')
+Metrics.set('unique_customers', 'cust_456', { tags: { channel: 'mobile' } })
+```
+
+#### `Metrics.gauge(name, value, data?)`
+
+Emit a gauge metric capturing a point-in-time value that can increase or decrease.
+
+```ts
+Metrics.gauge('active_connections', 47)
+Metrics.gauge('queue_depth', 312, { tags: { queue: 'email' } })
+```
+
+### MetricsAdditionalData
+
+Optional metadata passed as the last argument to any metric method.
+
+```ts
+interface MetricsAdditionalData {
+  unit?: MeasurementUnit   // 'millisecond', 'byte', 'percent', 'none', etc.
+  tags?: Record<string, Primitive>  // arbitrary key-value pairs for grouping
+  timestamp?: number       // custom Unix timestamp
+}
+```
+
+**Supported unit categories:**
+
+- **Duration**: `'nanosecond'`, `'microsecond'`, `'millisecond'`, `'second'`, `'minute'`, `'hour'`, `'day'`, `'week'`
+- **Information**: `'bit'`, `'byte'`, `'kilobyte'`, `'megabyte'`, `'gigabyte'`, `'terabyte'`, etc.
+- **Fraction**: `'ratio'`, `'percent'`
+- **None**: `''`, `'none'`
+
+### MetricsLogMessage
+
+Discriminated union of the four metric operations, keyed by `op`. Each variant carries `name`, `value`, and `data` fields. Used to type the logger and transports.
+
+```ts
+type MetricsLogMessage =
+  | { op: 'increment'; name: string; value: number | undefined; data: MetricsAdditionalData | undefined }
+  | { op: 'distribution'; name: string; value: number; data: MetricsAdditionalData | undefined }
+  | { op: 'set'; name: string; value: number | string; data: MetricsAdditionalData | undefined }
+  | { op: 'gauge'; name: string; value: number; data: MetricsAdditionalData | undefined }
+```
+
+## Transports
+
+### Built-in: Sentry Metrics
+
+Route all metrics to Sentry via `Metrics.transports.sentryMetrics()`.
+
+```ts
+import * as Sentry from '@sentry/node'
+
+const metricsLogger = Log.create<[Metrics.LogMessage]>()
+metricsLogger.addTransport(Metrics.transports.sentryMetrics(Sentry.metrics))
+```
+
+The transport accepts any object matching the `Metrics.MetricFunctions` interface (the four metric methods), so it works with any Sentry-compatible metrics API.
+
+### Custom Transports
+
+Write a custom transport by implementing `Log.Transport<[Metrics.LogMessage]>`. The `write` method receives a log message whose `data[0]` is the `MetricsLogMessage`.
+
+```ts
+function datadogTransport(client: DatadogClient): Log.Transport<[Metrics.LogMessage]> {
+  return {
+    write(message) {
+      const metric = message.data[0]
+      if (metric.op === 'increment') {
+        client.increment(metric.name, metric.value ?? 1, metric.data?.tags)
+      } else if (metric.op === 'distribution') {
+        client.distribution(metric.name, metric.value, metric.data?.tags)
+      } else if (metric.op === 'gauge') {
+        client.gauge(metric.name, metric.value, metric.data?.tags)
+      }
+      // handle 'set' as needed
+    }
+  }
+}
+
+metricsLogger.addTransport(datadogTransport(myDatadogClient))
+```
+
+## Common Patterns
+
+### Tagging metrics by request context
+
+```ts
+Metrics.increment('api_request', 1, {
+  tags: { method: 'POST', path: '/orders', status: 201 }
+})
+
+Metrics.distribution('db_query_time', 23, {
+  unit: 'millisecond',
+  tags: { table: 'orders', operation: 'insert' }
+})
+```
+
+### Tracking unique visitors
+
+```ts
+Metrics.set('unique_visitors', sessionId, {
+  tags: { page: '/checkout' }
+})
+```
+
+### Monitoring resource usage
+
+```ts
+Metrics.gauge('memory_usage_mb', process.memoryUsage().heapUsed / 1024 / 1024, {
+  unit: 'megabyte'
+})
+
+Metrics.gauge('active_websocket_connections', connectionPool.size)
+```
+
+### Multiple metric providers
+
+Register named providers for different metric pipelines.
+
+```ts
+const appLogger = Log.create<[Metrics.LogMessage]>()
+const perfLogger = Log.create<[Metrics.LogMessage]>()
+
+appLogger.addTransport(Metrics.transports.sentryMetrics(Sentry.metrics))
+perfLogger.addTransport(datadogTransport(myDatadogClient))
+
+Metrics.Provider.register('default', Metrics.Provider.create({ logger: appLogger }))
+Metrics.Provider.register('perf', Metrics.Provider.create({ logger: perfLogger }))
+
+// Facade calls use 'default'
+Metrics.increment('order_placed')
+```
+
+## Cross-Package Integration
+
+### Depends on
+
+- **@maestro-js/service-registry** -- Provider pattern, named registry, deferred Proxy resolution.
+- **@maestro-js/log** -- Typed logger and transport system. Metrics emissions are structured log messages routed through Log transports.
+
+### Works with
+
+- **@maestro-js/log** -- Metrics piggybacks on the Log transport architecture. Create a dedicated `Log.Logger<[Metrics.LogMessage]>` for metrics, then attach transports to route emissions to Sentry, Datadog, or any custom destination. The same logger can have multiple transports to fan out metrics to several backends simultaneously.
+
+## Package Info
+
+- **Package name**: `@maestro-js/metrics`
+- **Source**: `packages/metrics/src/index.ts`
+- **Types**: `packages/metrics/src/metrics-types.ts`
+- **Sentry transport**: `packages/metrics/src/sentry-metrics-transport.ts`
+- **Tests**: None yet
+- **Build**: `pnpm --filter @maestro-js/metrics build`
+- **Typecheck**: `pnpm --filter @maestro-js/metrics typecheck`

package/dist/index.d.ts

@@ -0,0 +1,139 @@
+import { Log } from '@maestro-js/log';
+
+/**
+ * A time duration.
+ */
+type DurationUnit = 'nanosecond' | 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | 'week';
+/**
+ * Size of information derived from bytes.
+ */
+type InformationUnit = 'bit' | 'byte' | 'kilobyte' | 'kibibyte' | 'megabyte' | 'mebibyte' | 'gigabyte' | 'terabyte' | 'tebibyte' | 'petabyte' | 'exabyte' | 'exbibyte';
+/**
+ * Fractions such as percentages.
+ */
+type FractionUnit = 'ratio' | 'percent';
+/**
+ * Untyped value without a unit.
+ */
+type NoneUnit = '' | 'none';
+type MeasurementUnit = LiteralUnion<DurationUnit | InformationUnit | FractionUnit | NoneUnit>;
+type LiteralUnion<T extends string> = T | Omit<T, T>;
+type Primitive = number | string | boolean | bigint | symbol | null | undefined;
+interface MetricsAdditionalData {
+    unit?: MeasurementUnit;
+    tags?: Record<string, Primitive>;
+    timestamp?: number;
+}
+type MetricsLogMessage = {
+    op: 'increment';
+    name: string;
+    value: number | undefined;
+    data: MetricsAdditionalData | undefined;
+} | {
+    op: 'distribution';
+    name: string;
+    value: number;
+    data: MetricsAdditionalData | undefined;
+} | {
+    op: 'set';
+    name: string;
+    value: number | string;
+    data: MetricsAdditionalData | undefined;
+} | {
+    op: 'gauge';
+    name: string;
+    value: number;
+    data: MetricsAdditionalData | undefined;
+};
+interface MetricFunctions {
+    increment(name: string, value?: number, data?: MetricsAdditionalData): void;
+    distribution(name: string, value: number, data?: MetricsAdditionalData): void;
+    set(name: string, value: number | string, data?: MetricsAdditionalData): void;
+    gauge(name: string, value: number, data?: MetricsAdditionalData): void;
+}
+
+declare function sentryMetricsTransport(sentryMetrics: MetricFunctions): Log.Transport<[MetricsLogMessage]>;
+
+declare function create(config: Metrics.Provider.MetricsServiceConfig): {
+    increment: (name: string, value?: number, data?: MetricsAdditionalData) => void;
+    distribution: (name: string, value: number, data?: MetricsAdditionalData) => void;
+    set: (name: string, value: number | string, data?: MetricsAdditionalData) => void;
+    gauge: (name: string, value: number, data?: MetricsAdditionalData) => void;
+};
+/**
+ * Unified metrics collection piped through the Log transport system.
+ *
+ * Four metric types cover the full spectrum of application observability:
+ * counters ({@link increment}), distributions ({@link distribution}),
+ * sets ({@link set}), and gauges ({@link gauge}). All emissions flow through
+ * a typed `Log.Logger` as structured `MetricsLogMessage` entries, so output
+ * destination is controlled entirely by attaching Log transports.
+ *
+ * @example
+ * ```ts
+ * const metricsLogger = Log.create<[Metrics.LogMessage]>()
+ * Metrics.Provider.register('default', Metrics.Provider.create({ logger: metricsLogger }))
+ * metricsLogger.addTransport(Metrics.transports.sentryMetrics(Sentry.metrics))
+ *
+ * Metrics.increment('order_placed', 1, { tags: { region: 'us-east' } })
+ * Metrics.distribution('payment_latency', 142, { unit: 'millisecond' })
+ * Metrics.set('unique_customers', 'cust_123')
+ * Metrics.gauge('active_connections', 47)
+ * ```
+ */
+declare namespace Metrics {
+    /** Discriminated union of the four metric operations, keyed by `op` */
+    type LogMessage = MetricsLogMessage;
+    /** Interface matching the four metric methods, used to type external metric providers like Sentry */
+    type MetricFunctions = MetricFunctions;
+    namespace Provider {
+        interface MetricsServiceConfig {
+            logger: Log.Logger<[MetricsLogMessage]>;
+        }
+    }
+    /**
+     * The four standard metric operations for application observability.
+     *
+     * Each method emits a structured log message through the configured logger.
+     * Attach Log transports to the logger to route metrics to external systems
+     * like Sentry, Datadog, or custom analytics pipelines. Use `MetricsAdditionalData`
+     * to attach tags, measurement units, and timestamps to any emission.
+     *
+     * @example
+     * ```ts
+     * Metrics.increment('user_signup', 1, { tags: { plan: 'pro' }, unit: 'none' })
+     * Metrics.distribution('response_time', 200, { unit: 'millisecond' })
+     * Metrics.set('unique_visitors', 'user_abc')
+     * Metrics.gauge('queue_depth', 312)
+     * ```
+     */
+    interface MetricsService {
+        /** Emits a counter metric, incrementing by `value` (defaults to 1) */
+        increment: (name: string, value?: number, data?: MetricsAdditionalData) => void;
+        /** Emits a distribution metric for statistical aggregation (p50, p95, p99) */
+        distribution: (name: string, value: number, data?: MetricsAdditionalData) => void;
+        /** Emits a set metric tracking unique string or integer values */
+        set: (name: string, value: number | string, data?: MetricsAdditionalData) => void;
+        /** Emits a gauge metric capturing a point-in-time value that can increase or decrease */
+        gauge: (name: string, value: number, data?: MetricsAdditionalData) => void;
+    }
+}
+/**
+ * Unified metrics collection piped through the Log transport system.
+ * Call `Metrics.Provider.create({ logger })` and register it, then attach transports to the logger.
+ */
+declare const Metrics: {
+    Provider: {
+        create: typeof create;
+        register: (name: "default", item: Metrics.MetricsService) => void;
+    };
+    increment: (name: string, value?: number, data?: MetricsAdditionalData) => void;
+    distribution: (name: string, value: number, data?: MetricsAdditionalData) => void;
+    set: (name: string, value: number | string, data?: MetricsAdditionalData) => void;
+    gauge: (name: string, value: number, data?: MetricsAdditionalData) => void;
+    transports: {
+        sentryMetrics: typeof sentryMetricsTransport;
+    };
+};
+
+export { Metrics };

package/dist/index.js

@@ -0,0 +1,80 @@
+// src/index.ts
+import "@maestro-js/log";
+import { ServiceRegistry } from "@maestro-js/service-registry";
+
+// src/sentry-metrics-transport.ts
+import "@maestro-js/log";
+function sentryMetricsTransport(sentryMetrics) {
+  return {
+    write(message) {
+      const metric = message.data[0];
+      if (metric.op === "increment") {
+        sentryMetrics.increment(metric.name, metric.value, metric.data);
+      } else if (metric.op === "set") {
+        sentryMetrics.set(metric.name, metric.value, metric.data);
+      } else if (metric.op === "distribution") {
+        sentryMetrics.distribution(metric.name, metric.value, metric.data);
+      } else if (metric.op === "gauge") {
+        sentryMetrics.gauge(metric.name, metric.value, metric.data);
+      }
+    }
+  };
+}
+
+// src/index.ts
+function create(config) {
+  const logger = config.logger;
+  function increment(name, value, data) {
+    logger.info({
+      op: "increment",
+      name,
+      value,
+      data
+    });
+  }
+  function distribution(name, value, data) {
+    logger.info({
+      op: "distribution",
+      name,
+      value,
+      data
+    });
+  }
+  function set(name, value, data) {
+    logger.info({
+      op: "set",
+      name,
+      value,
+      data
+    });
+  }
+  function gauge(name, value, data) {
+    logger.info({
+      op: "gauge",
+      name,
+      value,
+      data
+    });
+  }
+  return { increment, distribution, set, gauge };
+}
+var transports = {
+  sentryMetrics: sentryMetricsTransport
+};
+var registry = ServiceRegistry.createRegistry(ServiceRegistry.proxyFunctionsForObject);
+var Provider = {
+  create,
+  register: registry.register
+};
+var facade = registry.resolve("default");
+var Metrics = {
+  Provider,
+  increment: facade.increment,
+  distribution: facade.distribution,
+  set: facade.set,
+  gauge: facade.gauge,
+  transports
+};
+export {
+  Metrics
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@maestro-js/metrics",
+  "description": "Use when working with @maestro-js/metrics. Unified metrics collection piped through the Log transport system. Covers four metric types (counters, distributions, sets, gauges), provider setup, logger integration, Sentry transport, and custom transport authoring. Trigger on metrics emission, observability instrumentation, Sentry metrics integration, or application telemetry tasks.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@maestro-js/service-registry": "1.0.0-alpha.0",
+    "@maestro-js/log": "1.0.0-alpha.0"
+  },
+  "version": "1.0.0-alpha.0",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "repository": "https://github.com/Marcato-Partners/maestro-js",
+  "scripts": {
+    "build": "tsup --config ../../tsup.config.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "echo 'No tests yet'",
+    "format": "prettier --write src/",
+    "lint": "prettier --check src/"
+  }
+}