@aws-blocks/bb-metrics 0.1.1 → 0.1.3

package/DESIGN.md

@@ -0,0 +1,130 @@
+# Metrics — Design
+
+Design document for Metrics. For usage, see [README.md](./README.md).
+
+**Package:** `@aws-blocks/bb-metrics`
+**Type:** Primitive (no new infrastructure created)
+**AWS Service:** Amazon CloudWatch Metrics (via Embedded Metric Format)
+
+## Key Design Decision: EMF over PutMetricData
+
+Metrics are emitted using **CloudWatch Embedded Metric Format (EMF)** rather than calling the `PutMetricData` API directly.
+
+### Why EMF?
+
+| Concern | PutMetricData | EMF |
+|---------|---------------|-----|
+| **Latency impact** | HTTP call to CloudWatch (~5-50ms) | Synchronous stdout write (~0ms) |
+| **IAM permissions** | Requires `cloudwatch:PutMetricData` | Uses CloudWatch Logs (Lambda has this by default) |
+| **Batching** | Developer must buffer and flush | CloudWatch extracts metrics from log lines automatically |
+| **Error handling** | Network failures require retries | Stdout never fails (kernel-buffered) |
+| **API surface** | Async (`Promise<void>`) | Sync (`void`) — simpler DX |
+| **Cost** | ~$0.01 per 1000 PutMetricData API calls + metric storage | Log ingestion (already paid) + metric storage only |
+| **Cold start** | AWS SDK init adds ~100ms | Zero additional cold start |
+
+### Trade-offs
+
+- **No aggregation control:** EMF extracts metrics at the data point level. If you emit `Latency: 42ms` 1000 times in one invocation, CloudWatch stores 1000 data points (or groups them into a single EMF document with multiple values). With PutMetricData you could pre-aggregate into a StatisticSet.
+- **Log volume:** Each emit writes a JSON line to CloudWatch Logs. High-frequency metrics increase log volume (and log storage cost). Mitigated by CloudWatch Logs Infrequent Access class or retention policies.
+- **Maximum metrics per document:** EMF supports up to 100 metrics per JSON document. The `emitBatch` limit of 100 matches this constraint (vs PutMetricData's 1000 per call).
+
+### Why the trade-offs are acceptable
+
+1. Most BB users emit <100 metrics per invocation — log volume is negligible.
+2. The simplicity of a synchronous, zero-config API far outweighs the rare need for client-side aggregation.
+3. Lambda log costs are typically dominated by application logs, not metric EMF lines.
+
+## Architecture
+
+### Runtime Flow (AWS + Local)
+
+```
+emit('Count', 1, { dimensions: { endpoint: '/api' } })
+  │
+  ├─ validateMetricName('Count')
+  ├─ mergeDimensions(defaults, { endpoint: '/api' })
+  ├─ validateDimensions(merged)
+  │
+  └─ writeEmf(namespace, [{ name, value, unit, dimensions, timestamp, resolution }])
+       │
+       ├─ groupByDimensions(metrics)  // EMF requires same dims per entry
+       │
+       └─ for each group:
+            process.stdout.write(JSON.stringify(emfPayload) + '\n')
+```
+
+### EMF Document Structure
+
+```json
+{
+  "_aws": {
+    "Timestamp": 1718450000000,
+    "CloudWatchMetrics": [{
+      "Namespace": "MyApp/Orders",
+      "Dimensions": [["service", "endpoint"]],
+      "Metrics": [
+        { "Name": "RequestCount", "Unit": "Count", "StorageResolution": 60 },
+        { "Name": "Latency", "Unit": "Milliseconds", "StorageResolution": 60 }
+      ]
+    }]
+  },
+  "service": "orders",
+  "endpoint": "/api",
+  "RequestCount": 1,
+  "Latency": 42
+}
+```
+
+### Dimension Grouping
+
+EMF requires all metrics in a single `CloudWatchMetrics` entry to share the same dimension keys and values. When `emitBatch` receives metrics with different dimension sets, they are grouped and written as separate JSON lines.
+
+### Child Emitters
+
+`child(dimensions)` returns a lightweight `ChildMetrics` object (not a Scope node) that:
+- Inherits the parent's namespace
+- Merges the provided dimensions on top of the parent's `defaultDimensions`
+- Supports further nesting via `child()` on the child itself
+
+This enables per-request or per-endpoint metric scoping without creating new Scope nodes.
+
+## Infrastructure (CDK)
+
+Unlike most Building Blocks, Metrics does **not** create any AWS resources. CloudWatch namespaces are created implicitly on first metric data point arrival.
+
+The CDK construct creates no AWS resources and adds no environment variables or IAM grants. EMF uses CloudWatch Logs (which Lambda already has), so no `cloudwatch:PutMetricData` grant is needed. The construct only:
+1. **Resolves the namespace:** Computes the resolved `namespace` and exposes it as a readonly property.
+2. **Exposes `defaultDimensions`:** Exposes `defaultDimensions` as a readonly property so that other CDK-time consumers (like the Dashboard BB) can read them and build matching CloudWatch widget queries.
+
+### Namespace Resolution Order
+
+```
+ExternalMetricsRef.namespace  (fromExisting)
+  → options.namespace  (constructor arg)
+    → scope.fullId  (default)
+```
+
+## Mock Implementation
+
+There is no separate mock — the AWS runtime (`index.aws.ts`) and the mock (`index.mock.ts`) are identical. Both write EMF JSON to stdout. In local dev, the output is visible in the terminal; in Lambda, it is captured by CloudWatch Logs.
+
+This is unique among Building Blocks. Most BBs need a mock because their AWS runtime makes network calls (DynamoDB, S3, SQS, etc.). Metrics via EMF only writes to stdout, which works identically in all environments.
+
+### Mock vs AWS Behavior Differences
+
+| Behavior Difference | Impact | Mitigation |
+|------------|--------|------------|
+| No CloudWatch extraction | Metrics are written but not extracted into CloudWatch locally | Expected — local dev is for correctness testing, not dashboards |
+| No alarms | Threshold breaches are not detected locally | Document the gap — alarms require CloudWatch infrastructure |
+| No dashboards | Cannot preview dashboard visualizations locally | Document the gap — dashboards are a CloudWatch console feature |
+| No namespace-scoped IAM | Permission errors only surface in AWS | IAM is handled by CDK grants automatically |
+| No log retention limits | Stdout grows unbounded in local dev | Terminal scrollback is the natural limit |
+
+## Validation
+
+All validation matches CloudWatch constraints:
+- **Metric name:** Non-empty, max 1024 characters
+- **Dimensions:** Max 30 key-value pairs, non-empty keys and values, max 1024 chars each
+- **Batch size:** Max 100 metrics per `emitBatch` call (EMF document limit)
+
+Validation runs synchronously before the stdout write. Failures throw typed errors (`MetricsErrors.*`) that can be caught with `isBlocksError()`.

package/README.md

@@ -6,6 +6,8 @@ Custom application metrics backed by Amazon CloudWatch (via Embedded Metric Form
 
 **When NOT to use:** If you need structured log output, use `Logging`. If you need distributed request tracing, use `Tracing`. If you need to store time-series data for querying, use `Database` or `DistributedTable`.
 
+> Design & mock parity details: [DESIGN.md](./DESIGN.md)
+
 ## API
 
 ```typescript

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

@@ -1 +1 @@
-{"version":3,"file":"index.aws.d.ts","sourceRoot":"","sources":["../src/index.aws.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EACX,cAAc,EACd,WAAW,EACX,WAAW,EAGX,kBAAkB,EAClB,cAAc,EACd,MAAM,YAAY,CAAC;AAUpB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEzD,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;AAIpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,qBAAa,OAAQ,SAAQ,KAAM,YAAW,cAAc;IAC3D,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAE7D,2FAA2F;IAC3F,SAAS,CAAC,GAAG,EAAE,WAAW,CAAC;gBAEf,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc;IAUpE;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI;IAe9D;;;;;;;;;;;;;;;;;OAiBG;IACH,SAAS,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,IAAI;IAqBvC;;OAEG;IACH,KAAK,IAAI,IAAI;IAEb;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,cAAc;IAOzD;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,kBAAkB;CAG1D"}
+{"version":3,"file":"index.aws.d.ts","sourceRoot":"","sources":["../src/index.aws.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EACX,cAAc,EACd,WAAW,EACX,WAAW,EAGX,kBAAkB,EAClB,cAAc,EACd,MAAM,YAAY,CAAC;AAWpB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEzD,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;AAIpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,qBAAa,OAAQ,SAAQ,KAAM,YAAW,cAAc;IAC3D,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAE7D,2FAA2F;IAC3F,SAAS,CAAC,GAAG,EAAE,WAAW,CAAC;gBAEf,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc;IAUpE;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI;IAe9D;;;;;;;;;;;;;;;;;OAiBG;IACH,SAAS,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,IAAI;IAqBvC;;OAEG;IACH,KAAK,IAAI,IAAI;IAEb;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,cAAc;IAOzD;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,kBAAkB;CAG1D"}

package/dist/index.aws.js

@@ -1,6 +1,7 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 import { Scope } from '@aws-blocks/core';
+import { BB_NAME, BB_VERSION } from './version.js';
 import { validateMetricName, validateDimensions, validateBatchSize, validateNamespace, mergeDimensions, } from './validation.js';
 import { Logger } from '@aws-blocks/bb-logger';
 export { MetricsErrors } from './errors.js';
@@ -61,7 +62,7 @@ export class Metrics extends Scope {
     /** @internal Logger for internal operations. Defaults to error-level when not provided. */
     log;
     constructor(scope, id, options) {
-        super(id, { parent: scope });
+        super(id, { parent: scope, bbName: BB_NAME, bbVersion: BB_VERSION });
         this.log = options?.logger ?? new Logger(this, 'logger', { level: 'error' });
         this.namespace = options?.metrics?.namespace
             ?? options?.namespace

package/dist/index.test.js

@@ -2,7 +2,14 @@
 // SPDX-License-Identifier: Apache-2.0
 import { test, describe, beforeEach, afterEach } from 'node:test';
 import assert from 'node:assert';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Scope } from '@aws-blocks/core';
 import { Metrics, MetricsErrors } from './index.mock.js';
+import { Metrics as AwsMetrics } from './index.aws.js';
+import { BB_NAME, BB_VERSION } from './version.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
 // ── Helpers ─────────────────────────────────────────────────────────────────
 let stdoutLines = [];
 let origStdoutWrite;
@@ -493,3 +500,42 @@ describe('scope integration', () => {
         assert.ok(typeof m.child === 'function');
     });
 });
+// ── Telemetry Registration ──────────────────────────────────────────────────
+/**
+ * `Scope.getRegisteredBlocks()` only names a block whose `bbName` is in
+ * OFFICIAL_BB_NAMES, and that set is generated from the umbrella's
+ * `aws-blocks.vendorize` map. These tests pin the three coupled artifacts to
+ * each other: the block's generated BB_NAME, its vendorize entry, and the
+ * generated name set. A block that omits `bbMeta` still constructs fine and
+ * every other test still passes, so that gap is only visible here.
+ *
+ * Imported through `./index.mock.js`, the package's default entry, which
+ * re-exports the AWS runtime class — so both conditions resolve to the class
+ * asserted here.
+ */
+describe('telemetry registration', () => {
+    beforeEach(() => {
+        Scope._resetRegistry();
+    });
+    test('BB_NAME is the name the vendorize map and OFFICIAL_BB_NAMES carry', () => {
+        assert.strictEqual(BB_NAME, 'Metrics');
+    });
+    test('BB_VERSION tracks the package version', () => {
+        const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
+        assert.strictEqual(BB_VERSION, pkg.version);
+    });
+    test('the default entry re-exports the AWS runtime class', () => {
+        assert.strictEqual(Metrics, AwsMetrics);
+    });
+    test('an instance carries bbName and bbVersion', () => {
+        const m = new Metrics(fakeScope, 'metrics');
+        assert.strictEqual(m.bbName, BB_NAME);
+        assert.strictEqual(m.bbVersion, BB_VERSION);
+    });
+    test('registers as an official block, so telemetry is allowed to name it', () => {
+        new Metrics(fakeScope, 'metrics');
+        const { blocks, customBlocksCount } = Scope.getRegisteredBlocks();
+        assert.deepStrictEqual(blocks.filter(b => b.name === BB_NAME), [{ name: BB_NAME, version: BB_VERSION }]);
+        assert.strictEqual(customBlocksCount, 0, 'must not be filtered out as an unnamed custom block');
+    });
+});

package/dist/version.d.ts

@@ -0,0 +1,3 @@
+export declare const BB_NAME = "Metrics";
+export declare const BB_VERSION = "0.1.3";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,OAAO,YAAY,CAAC;AACjC,eAAO,MAAM,UAAU,UAAU,CAAC"}

package/dist/version.js

@@ -0,0 +1,3 @@
+// Auto-generated by scripts/generate-version.mjs — do not edit manually
+export const BB_NAME = 'Metrics';
+export const BB_VERSION = '0.1.3';

package/package.json

@@ -1,12 +1,22 @@
 {
   "name": "@aws-blocks/bb-metrics",
-  "version": "0.1.1",
+  "version": "0.1.3",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aws-devtools-labs/aws-blocks.git",
+    "directory": "packages/bb-metrics"
+  },
+  "homepage": "https://github.com/aws-devtools-labs/aws-blocks/tree/main/packages/bb-metrics#readme",
+  "bugs": {
+    "url": "https://github.com/aws-devtools-labs/aws-blocks/issues"
+  },
   "author": "Amazon Web Services",
   "license": "Apache-2.0",
   "type": "module",
   "files": [
     "dist",
     "README.md",
+    "DESIGN.md",
     "src",
     "LICENSE"
   ],
@@ -23,12 +33,13 @@
     }
   },
   "scripts": {
+    "prebuild": "node ../../scripts/generate-version.mjs Metrics",
     "build": "tsc --build",
     "test": "node --test dist/**/*.test.js"
   },
   "dependencies": {
-    "@aws-blocks/core": "^0.1.1",
-    "@aws-blocks/bb-logger": "^0.1.1"
+    "@aws-blocks/core": "^0.1.17",
+    "@aws-blocks/bb-logger": "^0.1.3"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/src/index.aws.ts

@@ -13,6 +13,7 @@ import type {
 	MetricsEmitter,
 } from './types.js';
 import { MetricsErrors } from './errors.js';
+import { BB_NAME, BB_VERSION } from './version.js';
 import {
 	validateMetricName,
 	validateDimensions,
@@ -94,7 +95,7 @@ export class Metrics extends Scope implements MetricsEmitter {
 	protected log: ChildLogger;
 
 	constructor(scope: ScopeParent, id: string, options?: MetricsOptions) {
-		super(id, { parent: scope });
+		super(id, { parent: scope, bbName: BB_NAME, bbVersion: BB_VERSION });
 		this.log = options?.logger ?? new Logger(this, 'logger', { level: 'error' });
 		this.namespace = options?.metrics?.namespace
 			?? options?.namespace

package/src/index.test.ts

@@ -3,8 +3,16 @@
 
 import { test, describe, beforeEach, afterEach } from 'node:test';
 import assert from 'node:assert';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Scope } from '@aws-blocks/core';
 import { Metrics, MetricsErrors } from './index.mock.js';
+import { Metrics as AwsMetrics } from './index.aws.js';
 import type { MetricsEmitter } from './types.js';
+import { BB_NAME, BB_VERSION } from './version.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
 
 // ── Helpers ─────────────────────────────────────────────────────────────────
 
@@ -630,3 +638,52 @@ describe('scope integration', () => {
 		assert.ok(typeof m.child === 'function');
 	});
 });
+
+// ── Telemetry Registration ──────────────────────────────────────────────────
+
+/**
+ * `Scope.getRegisteredBlocks()` only names a block whose `bbName` is in
+ * OFFICIAL_BB_NAMES, and that set is generated from the umbrella's
+ * `aws-blocks.vendorize` map. These tests pin the three coupled artifacts to
+ * each other: the block's generated BB_NAME, its vendorize entry, and the
+ * generated name set. A block that omits `bbMeta` still constructs fine and
+ * every other test still passes, so that gap is only visible here.
+ *
+ * Imported through `./index.mock.js`, the package's default entry, which
+ * re-exports the AWS runtime class — so both conditions resolve to the class
+ * asserted here.
+ */
+describe('telemetry registration', () => {
+	beforeEach(() => {
+		Scope._resetRegistry();
+	});
+
+	test('BB_NAME is the name the vendorize map and OFFICIAL_BB_NAMES carry', () => {
+		assert.strictEqual(BB_NAME, 'Metrics');
+	});
+
+	test('BB_VERSION tracks the package version', () => {
+		const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
+		assert.strictEqual(BB_VERSION, pkg.version);
+	});
+
+	test('the default entry re-exports the AWS runtime class', () => {
+		assert.strictEqual(Metrics, AwsMetrics);
+	});
+
+	test('an instance carries bbName and bbVersion', () => {
+		const m = new Metrics(fakeScope, 'metrics');
+		assert.strictEqual(m.bbName, BB_NAME);
+		assert.strictEqual(m.bbVersion, BB_VERSION);
+	});
+
+	test('registers as an official block, so telemetry is allowed to name it', () => {
+		new Metrics(fakeScope, 'metrics');
+		const { blocks, customBlocksCount } = Scope.getRegisteredBlocks();
+		assert.deepStrictEqual(
+			blocks.filter(b => b.name === BB_NAME),
+			[{ name: BB_NAME, version: BB_VERSION }],
+		);
+		assert.strictEqual(customBlocksCount, 0, 'must not be filtered out as an unnamed custom block');
+	});
+});

package/src/version.ts

@@ -0,0 +1,3 @@
+// Auto-generated by scripts/generate-version.mjs — do not edit manually
+export const BB_NAME = 'Metrics';
+export const BB_VERSION = '0.1.3';