@aws-blocks/bb-metrics 0.1.0

package/dist/index.aws.js

@@ -0,0 +1,270 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { Scope } from '@aws-blocks/core';
+import { validateMetricName, validateDimensions, validateBatchSize, validateNamespace, mergeDimensions, } from './validation.js';
+import { Logger } from '@aws-blocks/bb-logger';
+export { MetricsErrors } from './errors.js';
+// ── Metrics (AWS runtime via EMF) ───────────────────────────────────────────
+/**
+ * Custom application metrics backed by Amazon CloudWatch (via EMF).
+ *
+ * Metrics emitted from this Building Block appear in CloudWatch under the
+ * configured namespace. Use for dashboards, alarms, and operational visibility.
+ *
+ * Uses CloudWatch Embedded Metric Format (EMF) — writes metric data as
+ * structured JSON to stdout. Lambda captures these and CloudWatch extracts
+ * metrics automatically.
+ *
+ * **When to use:** You need to track numeric measurements over time — request
+ * counts, error rates, latency, queue depths, business KPIs.
+ *
+ * **When NOT to use:** If you need structured log output only, use `Logging`.
+ * If you need distributed request tracing, use `Tracing`. If you need to store
+ * time-series data for querying, use `Database` or `DistributedTable`.
+ *
+ * **Best practices:**
+ * - Keep dimension cardinality low (avoid user IDs or request IDs as dimensions)
+ * - Use consistent metric names across your application
+ * - Use `defaultDimensions` for shared context (service name, environment)
+ * - Prefer `emitBatch` when recording multiple metrics in a single request
+ * - Use units to enable automatic conversions in CloudWatch dashboards
+ *
+ * **Scaling:** CloudWatch accepts unlimited metrics via EMF. Standard resolution
+ * metrics (60s) are retained for 15 days; high-resolution (1s) for 3 hours,
+ * then aggregated. Costs scale with unique metric name + dimension combinations.
+ *
+ * **Local development:** Metrics are written as EMF JSON to stdout (same as AWS).
+ * No disk persistence — metrics are ephemeral in local dev.
+ *
+ * **⚠️ Synchronous:** All metric methods are synchronous (void, not Promise).
+ * EMF writes to stdout which Lambda captures asynchronously. Returning a Promise
+ * would add overhead for zero benefit.
+ *
+ * @example
+ * ```typescript
+ * import { Metrics } from '@aws-blocks/bb-metrics';
+ *
+ * const metrics = new Metrics(scope, 'appMetrics', {
+ *   namespace: 'MyApp/Orders',
+ *   defaultDimensions: { service: 'orders' },
+ * });
+ *
+ * metrics.emit('RequestCount', 1, { unit: 'Count' });
+ * metrics.emit('Latency', 42, { unit: 'Milliseconds' });
+ * ```
+ */
+export class Metrics extends Scope {
+    /** The resolved CloudWatch namespace for metrics emitted by this instance. */
+    namespace;
+    /** Dimensions applied to every metric emitted by this instance. */
+    defaultDimensions;
+    /** @internal Logger for internal operations. Defaults to error-level when not provided. */
+    log;
+    constructor(scope, id, options) {
+        super(id, { parent: scope });
+        this.log = options?.logger ?? new Logger(this, 'logger', { level: 'error' });
+        this.namespace = options?.metrics?.namespace
+            ?? options?.namespace
+            ?? this.fullId;
+        this.defaultDimensions = options?.defaultDimensions ?? {};
+        validateNamespace(this.namespace);
+    }
+    /**
+     * Record a single metric data point via EMF.
+     *
+     * @param name - Metric name (e.g., 'RequestCount', 'Latency'). Non-empty, max 1024 chars.
+     * @param value - Numeric value to record.
+     * @param options - Unit, dimensions, timestamp, and resolution.
+     * @throws {MetricsErrors.InvalidMetricName} If the metric name is empty or exceeds 1024 characters.
+     * @throws {MetricsErrors.InvalidDimensions} If dimensions exceed 30 entries or contain empty keys/values.
+     *
+     * @example
+     * ```typescript
+     * metrics.emit('RequestCount', 1);
+     * metrics.emit('Latency', 42, { unit: 'Milliseconds' });
+     * metrics.emit('ErrorRate', 0.05, {
+     *   unit: 'Percent',
+     *   dimensions: { endpoint: '/api/orders' },
+     * });
+     * ```
+     */
+    emit(name, value, options) {
+        validateMetricName(name);
+        const dims = mergeDimensions(this.defaultDimensions, options?.dimensions);
+        validateDimensions(dims);
+        writeEmf(this.namespace, [{
+                name,
+                value,
+                unit: options?.unit ?? 'None',
+                dimensions: dims,
+                timestamp: options?.timestamp,
+                resolution: options?.resolution ?? 'standard',
+            }]);
+    }
+    /**
+     * Record multiple metric data points in a single EMF document.
+     * Metrics with the same dimension set are grouped into one EMF entry.
+     *
+     * @param metrics - Array of metric data points (max 100 per call).
+     * @throws {MetricsErrors.InvalidMetricName} If any metric name is invalid.
+     * @throws {MetricsErrors.InvalidDimensions} If any metric's dimensions are invalid.
+     * @throws {MetricsErrors.BatchTooLarge} If the batch exceeds 100 metrics.
+     *
+     * @example
+     * ```typescript
+     * metrics.emitBatch([
+     *   { name: 'RequestCount', value: 1, unit: 'Count' },
+     *   { name: 'Latency', value: 42, unit: 'Milliseconds' },
+     *   { name: 'ErrorCount', value: 0, unit: 'Count' },
+     * ]);
+     * ```
+     */
+    emitBatch(metrics) {
+        validateBatchSize(metrics.length);
+        for (const m of metrics) {
+            validateMetricName(m.name);
+            const dims = mergeDimensions(this.defaultDimensions, m.dimensions);
+            validateDimensions(dims);
+        }
+        const resolved = metrics.map(m => ({
+            name: m.name,
+            value: m.value,
+            unit: (m.unit ?? 'None'),
+            dimensions: mergeDimensions(this.defaultDimensions, m.dimensions),
+            timestamp: m.timestamp,
+            resolution: (m.resolution ?? 'standard'),
+        }));
+        writeEmf(this.namespace, resolved);
+    }
+    /**
+     * No-op. EMF writes are synchronous stdout writes — no buffering to flush.
+     */
+    flush() { }
+    /**
+     * Create a child Metrics emitter with inherited namespace and dimensions.
+     * The child merges the provided dimensions on top of the parent's defaults.
+     *
+     * @param dimensions - Additional dimensions for the child instance.
+     * @returns A MetricsEmitter with merged dimensions.
+     *
+     * @example
+     * ```typescript
+     * const requestMetrics = metrics.child({ endpoint: '/api/users', method: 'GET' });
+     * requestMetrics.emit('RequestCount', 1);
+     * ```
+     */
+    child(dimensions) {
+        return new ChildMetrics(this.namespace, { ...this.defaultDimensions, ...dimensions });
+    }
+    /**
+     * Reference an existing CloudWatch namespace not managed by this Building Block.
+     *
+     * @param namespace - The CloudWatch namespace string.
+     *
+     * @example
+     * ```typescript
+     * const metrics = new Metrics(scope, 'legacy', {
+     *   metrics: Metrics.fromExisting('MyOrg/SharedMetrics'),
+     * });
+     * ```
+     */
+    static fromExisting(namespace) {
+        return { __brand: 'ExternalMetricsRef', namespace };
+    }
+}
+// ── ChildMetrics ────────────────────────────────────────────────────────────
+class ChildMetrics {
+    namespace;
+    defaultDimensions;
+    constructor(namespace, defaultDimensions) {
+        this.namespace = namespace;
+        this.defaultDimensions = defaultDimensions;
+    }
+    emit(name, value, options) {
+        validateMetricName(name);
+        const dims = mergeDimensions(this.defaultDimensions, options?.dimensions);
+        validateDimensions(dims);
+        writeEmf(this.namespace, [{
+                name,
+                value,
+                unit: options?.unit ?? 'None',
+                dimensions: dims,
+                timestamp: options?.timestamp,
+                resolution: options?.resolution ?? 'standard',
+            }]);
+    }
+    emitBatch(metrics) {
+        validateBatchSize(metrics.length);
+        for (const m of metrics) {
+            validateMetricName(m.name);
+            const dims = mergeDimensions(this.defaultDimensions, m.dimensions);
+            validateDimensions(dims);
+        }
+        const resolved = metrics.map(m => ({
+            name: m.name,
+            value: m.value,
+            unit: (m.unit ?? 'None'),
+            dimensions: mergeDimensions(this.defaultDimensions, m.dimensions),
+            timestamp: m.timestamp,
+            resolution: (m.resolution ?? 'standard'),
+        }));
+        writeEmf(this.namespace, resolved);
+    }
+    flush() { }
+    child(dimensions) {
+        return new ChildMetrics(this.namespace, { ...this.defaultDimensions, ...dimensions });
+    }
+}
+/**
+ * Write one or more metrics as EMF-formatted JSON lines to stdout.
+ * Groups metrics by dimension set (EMF requires same dimensions per entry).
+ */
+function writeEmf(namespace, metrics) {
+    if (metrics.length === 0)
+        return;
+    const groups = groupByDimensions(metrics);
+    for (const group of groups) {
+        const dimKeys = Object.keys(group.dimensions);
+        const timestamp = group.metrics[0].timestamp?.getTime() ?? Date.now();
+        const emfPayload = {
+            _aws: {
+                Timestamp: timestamp,
+                CloudWatchMetrics: [{
+                        Namespace: namespace,
+                        Dimensions: dimKeys.length > 0 ? [dimKeys] : [[]],
+                        Metrics: group.metrics.map(m => ({
+                            Name: m.name,
+                            Unit: m.unit,
+                            StorageResolution: m.resolution === 'high' ? 1 : 60,
+                        })),
+                    }],
+            },
+            ...group.dimensions,
+        };
+        for (const m of group.metrics) {
+            emfPayload[m.name] = m.value;
+        }
+        process.stdout.write(JSON.stringify(emfPayload) + '\n');
+    }
+}
+/**
+ * Group metrics by their dimension set. EMF requires metrics in the same
+ * CloudWatchMetrics entry to share the same dimension keys and values.
+ */
+function groupByDimensions(metrics) {
+    const groups = new Map();
+    for (const m of metrics) {
+        const key = dimensionKey(m.dimensions);
+        let group = groups.get(key);
+        if (!group) {
+            group = { dimensions: m.dimensions, metrics: [] };
+            groups.set(key, group);
+        }
+        group.metrics.push(m);
+    }
+    return Array.from(groups.values());
+}
+function dimensionKey(dims) {
+    const sorted = Object.entries(dims).sort(([a], [b]) => a.localeCompare(b));
+    return sorted.map(([k, v]) => `${k}=${v}`).join('&');
+}

package/dist/index.browser.d.ts

@@ -0,0 +1,12 @@
+import type { EmitOptions, MetricDatum, ExternalMetricsRef, MetricsEmitter } from './types.js';
+export { MetricsErrors } from './errors.js';
+export type { MetricsOptions, EmitOptions, MetricDatum, MetricUnit, MetricResolution, ExternalMetricsRef, MetricsEmitter, } from './types.js';
+export declare class Metrics implements MetricsEmitter {
+    constructor(..._args: any[]);
+    emit(_name: string, _value: number, _options?: EmitOptions): void;
+    emitBatch(_metrics: MetricDatum[]): void;
+    flush(): void;
+    child(_dimensions: Record<string, string>): MetricsEmitter;
+    static fromExisting(namespace: string): ExternalMetricsRef;
+}
+//# sourceMappingURL=index.browser.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.browser.d.ts","sourceRoot":"","sources":["../src/index.browser.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE/F,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,YAAY,EACX,cAAc,EACd,WAAW,EACX,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,GACd,MAAM,YAAY,CAAC;AAEpB,qBAAa,OAAQ,YAAW,cAAc;gBACjC,GAAG,KAAK,EAAE,GAAG,EAAE;IAC3B,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI;IACjE,SAAS,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,IAAI;IACxC,KAAK,IAAI,IAAI;IACb,KAAK,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,cAAc;IAC1D,MAAM,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,kBAAkB;CAG1D"}

package/dist/index.browser.js

@@ -0,0 +1,13 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+export { MetricsErrors } from './errors.js';
+export class Metrics {
+    constructor(..._args) { }
+    emit(_name, _value, _options) { }
+    emitBatch(_metrics) { }
+    flush() { }
+    child(_dimensions) { return new Metrics(); }
+    static fromExisting(namespace) {
+        return { __brand: 'ExternalMetricsRef', namespace };
+    }
+}

package/dist/index.cdk.d.ts

@@ -0,0 +1,20 @@
+import { Scope } from '@aws-blocks/core/cdk';
+import type { ScopeParent } from '@aws-blocks/core';
+import type { MetricsOptions } from './types.js';
+export { MetricsErrors } from './errors.js';
+export type { MetricsOptions, EmitOptions, MetricDatum, MetricUnit, MetricResolution, ExternalMetricsRef, MetricsEmitter, } from './types.js';
+/**
+ * CDK construct for Metrics.
+ *
+ * EMF writes structured JSON to stdout which Lambda captures in CloudWatch Logs.
+ * CloudWatch automatically extracts metrics — no additional IAM permissions or
+ * environment variables are needed.
+ */
+export declare class Metrics extends Scope {
+    /** The resolved CloudWatch namespace for metrics emitted by this instance. */
+    readonly namespace: string;
+    /** Default dimensions applied to every metric emitted by this instance. */
+    readonly defaultDimensions: Readonly<Record<string, string>>;
+    constructor(scope: ScopeParent, id: string, options?: MetricsOptions);
+}
+//# sourceMappingURL=index.cdk.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.cdk.d.ts","sourceRoot":"","sources":["../src/index.cdk.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,YAAY,EACX,cAAc,EACd,WAAW,EACX,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,GACd,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,qBAAa,OAAQ,SAAQ,KAAK;IACjC,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,2EAA2E;IAC3E,QAAQ,CAAC,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;gBAEjD,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc;CAOpE"}

package/dist/index.cdk.js

@@ -0,0 +1,24 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { Scope } from '@aws-blocks/core/cdk';
+export { MetricsErrors } from './errors.js';
+/**
+ * CDK construct for Metrics.
+ *
+ * EMF writes structured JSON to stdout which Lambda captures in CloudWatch Logs.
+ * CloudWatch automatically extracts metrics — no additional IAM permissions or
+ * environment variables are needed.
+ */
+export class Metrics extends Scope {
+    /** The resolved CloudWatch namespace for metrics emitted by this instance. */
+    namespace;
+    /** Default dimensions applied to every metric emitted by this instance. */
+    defaultDimensions;
+    constructor(scope, id, options) {
+        super(id, { parent: scope });
+        this.namespace = options?.metrics?.namespace
+            ?? options?.namespace
+            ?? this.fullId;
+        this.defaultDimensions = options?.defaultDimensions ?? {};
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { Metrics, MetricsErrors } from './index.aws.js';
+export type { MetricsOptions, EmitOptions, MetricDatum, MetricUnit, MetricResolution, ExternalMetricsRef, MetricsEmitter, } from './types.js';
+//# 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":"AAGA,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACxD,YAAY,EACX,cAAc,EACd,WAAW,EACX,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,GACd,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+export { Metrics, MetricsErrors } from './index.aws.js';

package/dist/index.mock.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Mock (local development) runtime for Metrics.
+ *
+ * Behavior is identical to the AWS runtime — both write EMF-formatted JSON to
+ * stdout. In local dev the output is visible in the terminal; in Lambda it is
+ * captured by CloudWatch Logs. No separate mock implementation is needed.
+ */
+export { Metrics, MetricsErrors } from './index.aws.js';
+export type { MetricsOptions, EmitOptions, MetricDatum, MetricUnit, MetricResolution, ExternalMetricsRef, MetricsEmitter, } from './types.js';
+//# sourceMappingURL=index.mock.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.mock.d.ts","sourceRoot":"","sources":["../src/index.mock.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACxD,YAAY,EACX,cAAc,EACd,WAAW,EACX,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,GACd,MAAM,YAAY,CAAC"}

package/dist/index.mock.js

@@ -0,0 +1,10 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Mock (local development) runtime for Metrics.
+ *
+ * Behavior is identical to the AWS runtime — both write EMF-formatted JSON to
+ * stdout. In local dev the output is visible in the terminal; in Lambda it is
+ * captured by CloudWatch Logs. No separate mock implementation is needed.
+ */
+export { Metrics, MetricsErrors } from './index.aws.js';

package/dist/index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":""}