Bug: No collision detection between dimension keys, metric names, and metadata keys in EMF output

[svozza]

Expected Behavior

The library should prevent collisions between dimension keys, metric names, and metadata keys since they all share the same top-level namespace in the EMF JSON. Per the EMF spec, dimension targets MUST be strings and metric targets MUST be numbers — they cannot coexist under the same key.

Current Behavior

In serializeMetrics() at Metrics.ts:747-769, the EMF output is constructed by spreading objects in this order:

return {
  _aws: { ... },
  ...defaultDimensions,     // 1st
  ...dimensions,            // 2nd
  ...dimensionSetsFlat,     // 3rd
  ...metricValues,          // 4th — overwrites dimensions
  ...this.#metadataStore.getAll(),  // 5th — overwrites metrics
};

Since these keys share the same namespace, collisions can silently corrupt the output:

• A metric named environment overwrites a dimension environment: 'prod' with a number — CloudWatch silently loses the dimension.
• Metadata with key request_count overwrites a metric request_count: 42 with a string — CloudWatch fails to parse the metric.

Code snippet

import { Metrics, MetricUnit } from '@aws-lambda-powertools/metrics';

const metrics = new Metrics({ namespace: 'test' });

// Problem 1: metric overwrites dimension
metrics.addDimension('environment', 'prod');
metrics.addMetric('environment', MetricUnit.Count, 1);
const output1 = metrics.serializeMetrics();
console.log(output1.environment);
// ❌ Outputs: 1 (number) — the dimension string 'prod' was silently overwritten

// Problem 2: metadata overwrites metric
const metrics2 = new Metrics({ namespace: 'test' });
metrics2.addMetric('request_count', MetricUnit.Count, 42);
metrics2.addMetadata('request_count', 'not-a-number');
const output2 = metrics2.serializeMetrics();
console.log(output2.request_count);
// ❌ Outputs: 'not-a-number' (string) — the numeric metric value 42 was overwritten

Steps to Reproduce

Metric overwrites dimension:

1. Create a Metrics instance
2. Add a dimension environment: 'prod'
3. Add a metric named environment
4. Call serializeMetrics() — output.environment is 1, not 'prod'

Metadata overwrites metric:

1. Create a Metrics instance
2. Add a metric request_count with value 42
3. Add metadata with key request_count
4. Call serializeMetrics() — output.request_count is 'not-a-number', not 42

Possible Solution

Maintain a Set of reserved keys and check against it in storeMetric() and addMetadata():

// In storeMetric():
const dimensionKeys = new Set([
  ...Object.keys(this.#dimensionsStore.getDimensions()),
  ...Object.keys(this.#dimensionsStore.getDefaultDimensions()),
]);
if (dimensionKeys.has(name)) {
  throw new Error(`Metric name "${name}" conflicts with an existing dimension key`);
}

// In addMetadata():
if (this.#metricsStore.getMetric(key) !== undefined) {
  throw new Error(`Metadata key "${key}" conflicts with an existing metric name`);
}

Powertools for AWS Lambda (TypeScript) version

2.33.0

AWS Lambda function runtime

22.x

Packaging format used

npm

---

Disclaimer: After creating an issue, please wait until it is triaged and confirmed by a maintainer before implementing it. This will reduce amount of rework and the chance that a pull request gets rejected.

[vishwakt]

@svozza do you think it would be a good idea to implement symmetrical checks across all methods (storeMetric, addMetadata, addDimension, addDimensions, setDefaultDimensions).

Please confirm if this is acceptable, or if you think strictly limiting the checks to the two methods mentioned in the issue would be a good resolution?

[vishwakt]

@svozza @dreamorosi let me know if i can pick this one up next