@aws-blocks/bb-metrics 0.1.0

package/src/types.ts

@@ -0,0 +1,119 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Shared types for the Metrics building block.
+ * This file has zero runtime dependencies — types only.
+ */
+import type { ChildLogger } from '@aws-blocks/bb-logger';
+
+/**
+ * Units supported by CloudWatch. Using a unit enables automatic conversions
+ * in dashboards (e.g., Bytes → Megabytes) and clearer Y-axis labels.
+ *
+ * Covers the most common use cases. For unlisted units, use 'None'.
+ */
+export type MetricUnit =
+	| 'Count'
+	| 'Seconds'
+	| 'Milliseconds'
+	| 'Microseconds'
+	| 'Bytes'
+	| 'Kilobytes'
+	| 'Megabytes'
+	| 'Gigabytes'
+	| 'Percent'
+	| 'Bits/Second'
+	| 'None';
+
+/**
+ * Storage resolution for a metric data point.
+ * - 'standard' (60s) — default, lower cost, 15-day retention at full resolution
+ * - 'high' (1s) — higher cost, 3-hour retention at full resolution then aggregated
+ */
+export type MetricResolution = 'standard' | 'high';
+
+/**
+ * Configuration for the Metrics building block.
+ */
+export interface MetricsOptions {
+	/**
+	 * CloudWatch namespace for all metrics emitted by this instance.
+	 * Namespaces group related metrics in CloudWatch dashboards and alarms.
+	 * Defaults to the scope's `fullId` (e.g., 'myapp-appMetrics').
+	 */
+	namespace?: string;
+
+	/**
+	 * Dimensions applied to every metric emitted by this instance.
+	 * Useful for shared context like service name or environment.
+	 * Per-emit dimensions are merged on top of these (per-emit wins on conflict).
+	 */
+	defaultDimensions?: Record<string, string>;
+
+	/**
+	 * Wrap an existing CloudWatch namespace instead of creating one.
+	 * When set, `namespace` is ignored.
+	 */
+	metrics?: ExternalMetricsRef;
+	/** Optional logger for internal operations. When omitted, a default Logger at error level is created. */
+	logger?: ChildLogger;
+}
+
+/**
+ * Options for a single metric emission.
+ */
+export interface EmitOptions {
+	/** Unit of the metric value. Defaults to 'None'. */
+	unit?: MetricUnit;
+	/**
+	 * Dimensions to attach to this data point (max 30 total including defaults).
+	 * Merged with `defaultDimensions` — per-emit dimensions take precedence.
+	 */
+	dimensions?: Record<string, string>;
+	/** Timestamp for the data point. Defaults to now. */
+	timestamp?: Date;
+	/**
+	 * Storage resolution. 'standard' = 60-second aggregation (default).
+	 * 'high' = 1-second aggregation (higher cost, useful for spike detection).
+	 */
+	resolution?: MetricResolution;
+}
+
+/**
+ * A single metric data point for batch emission.
+ */
+export interface MetricDatum {
+	/** Metric name (non-empty, max 1024 characters). */
+	name: string;
+	/** Numeric value. */
+	value: number;
+	/** Unit of the metric value. Defaults to 'None'. */
+	unit?: MetricUnit;
+	/** Dimensions to attach (max 30 total including defaults). */
+	dimensions?: Record<string, string>;
+	/** Timestamp for the data point. Defaults to now. */
+	timestamp?: Date;
+	/** Storage resolution. Defaults to 'standard'. */
+	resolution?: MetricResolution;
+}
+
+/**
+ * Reference to an existing CloudWatch namespace not managed by this BB.
+ * Created via `Metrics.fromExisting()`.
+ */
+export interface ExternalMetricsRef {
+	readonly __brand: 'ExternalMetricsRef';
+	readonly namespace: string;
+}
+
+/**
+ * A child metrics instance with inherited dimensions and namespace.
+ * Provides the same metric emission methods but is not a Scope node.
+ */
+export interface MetricsEmitter {
+	emit(name: string, value: number, options?: EmitOptions): void;
+	emitBatch(metrics: MetricDatum[]): void;
+	flush(): void;
+	child(dimensions: Record<string, string>): MetricsEmitter;
+}

package/src/validation.ts

@@ -0,0 +1,97 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { MetricsErrors } from './errors.js';
+
+function blocksError(name: string, message: string): Error {
+	const err = new Error(`${name}: ${message}`);
+	err.name = name;
+	return err;
+}
+
+/**
+ * Validate a metric name against CloudWatch constraints.
+ * - Must be non-empty
+ * - Max 1024 characters
+ */
+export function validateMetricName(name: string): void {
+	if (!name || name.length === 0) {
+		throw blocksError(MetricsErrors.InvalidMetricName, 'Metric name must not be empty');
+	}
+	if (name.length > 1024) {
+		throw blocksError(MetricsErrors.InvalidMetricName, `Metric name exceeds 1024 characters (got ${name.length})`);
+	}
+}
+
+/**
+ * Validate dimensions against CloudWatch constraints.
+ * - Max 30 dimension key-value pairs
+ * - Keys and values must be non-empty
+ * - Keys and values max 1024 characters each
+ */
+export function validateDimensions(dimensions: Record<string, string>): void {
+	const entries = Object.entries(dimensions);
+	if (entries.length > 30) {
+		throw blocksError(MetricsErrors.InvalidDimensions, `Dimensions exceed 30 entries (got ${entries.length})`);
+	}
+	for (const [key, value] of entries) {
+		if (!key || key.length === 0) {
+			throw blocksError(MetricsErrors.InvalidDimensions, 'Dimension key must not be empty');
+		}
+		if (key.length > 1024) {
+			throw blocksError(MetricsErrors.InvalidDimensions, `Dimension key exceeds 1024 characters: '${key.substring(0, 50)}...'`);
+		}
+		if (value === undefined || value === null || value.length === 0) {
+			throw blocksError(MetricsErrors.InvalidDimensions, `Dimension value for key '${key}' must not be empty`);
+		}
+		if (value.length > 1024) {
+			throw blocksError(MetricsErrors.InvalidDimensions, `Dimension value for key '${key}' exceeds 1024 characters`);
+		}
+	}
+}
+
+/**
+ * Validate batch size (max 100 metrics per EMF document).
+ */
+export function validateBatchSize(count: number): void {
+	if (count > 100) {
+		throw blocksError(MetricsErrors.BatchTooLarge, `Batch exceeds 100 metrics (got ${count})`);
+	}
+}
+
+/** Valid characters for a CloudWatch namespace: alphanumeric, dot, underscore, hash, colon, slash, hyphen, space. */
+const NAMESPACE_PATTERN = /^[a-zA-Z0-9._#:/ -]+$/;
+
+/**
+ * Validate a namespace against CloudWatch constraints.
+ * - Must be non-empty (at least one non-whitespace character)
+ * - Max 256 characters
+ * - Only valid chars: [a-zA-Z0-9._#:/ -]
+ * - Must not start with "AWS/" (reserved for AWS services)
+ */
+export function validateNamespace(namespace: string): void {
+	if (!namespace || namespace.trim().length === 0) {
+		throw blocksError(MetricsErrors.InvalidNamespace, 'Namespace must not be empty');
+	}
+	if (namespace.length > 256) {
+		throw blocksError(MetricsErrors.InvalidNamespace, `Namespace exceeds 256 characters (got ${namespace.length})`);
+	}
+	if (!NAMESPACE_PATTERN.test(namespace)) {
+		throw blocksError(MetricsErrors.InvalidNamespace, `Namespace contains invalid characters: '${namespace.substring(0, 50)}'. Valid: [a-zA-Z0-9._#:/ -]`);
+	}
+	if (namespace.startsWith('AWS/')) {
+		throw blocksError(MetricsErrors.InvalidNamespace, `Namespace must not start with 'AWS/' (reserved for AWS services): '${namespace}'`);
+	}
+}
+
+/**
+ * Merge default dimensions with per-emit dimensions.
+ * Per-emit dimensions take precedence on key conflict.
+ */
+export function mergeDimensions(
+	defaults: Record<string, string>,
+	overrides?: Record<string, string>,
+): Record<string, string> {
+	if (!overrides || Object.keys(overrides).length === 0) return { ...defaults };
+	return { ...defaults, ...overrides };
+}