Constraints and Requirements

Metric Constraints

• Metric name length: 1-255 characters
• Maximum metrics per EMF blob: 100 (auto-flushes when reached)
• Maximum values per metric: 100 (auto-flushes when reached)
• Maximum dimensions per metric: 29 (includes both default and request-specific)
• Dimension name/value: Must be non-empty strings
• Timestamp constraints: Within 14 days in the past or 2 hours in the future
• Total EMF payload size: Keep under CloudWatch Logs limit (256 KB per log event)

Validation and Errors

addMetric Errors

• Throws Error if name is not a valid string
• Throws RangeError if name length not between 1 and 255 characters
• Throws RangeError if value is not a valid number
• Throws RangeError if unit is not a valid MetricUnit
• Throws RangeError if resolution is not a valid MetricResolution

Dimension Errors

• Throws RangeError if adding dimension would exceed 29 total dimensions
• Logs warning if dimension name or value is empty/null/undefined (skips dimension)
• Logs warning if dimension already exists (overwrites previous value)

publishStoredMetrics Errors

• Throws RangeError if throwOnEmptyMetrics enabled and no metrics recorded
• Logs warning if no metrics recorded (when throwOnEmptyMetrics disabled)

Timestamp Errors

• Logs warning if timestamp exceeds 14 days past or 2 hours future constraints
• Metric may be rejected by CloudWatch if timestamp invalid

Environment Variables

Core Configuration

• POWERTOOLS_METRICS_NAMESPACE - Default namespace for metrics (required for organization)
• POWERTOOLS_SERVICE_NAME - Default service name (added as dimension)
• POWERTOOLS_METRICS_FUNCTION_NAME - Function name for cold start metric dimension

Feature Flags

• POWERTOOLS_METRICS_DISABLED - Disable metrics emission (useful for testing)
• POWERTOOLS_DEV - Enable development mode

Decorator Requirements

TypeScript Configuration

Requires experimentalDecorators enabled in tsconfig.json:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

Implementation Requirements

• Handler must be a class method
• Class must implement LambdaInterface from @aws-lambda-powertools/commons/types
• Handler must be properly bound: handlerClass.handler.bind(handlerClass)

Middleware Requirements

Dependencies

• @middy/core version 3.x, 4.x, 5.x, or 6.x as peer dependency
• Middy middleware applied to handler function with .use(logMetrics(...))
• Handler wrapped with middy()

Behavior Constraints

Metric Buffering

• Metrics buffered until publishStoredMetrics() called
• Auto-flush at 100 metrics per EMF blob
• Auto-flush at 100 values per metric
• In singleMetric mode, each metric flushes immediately

Dimension Lifecycle

• Default dimensions: Persist across all metric emissions, not cleared by publishStoredMetrics()
• Request-specific dimensions: Cleared automatically by publishStoredMetrics()
• Service name automatically added as default dimension if provided in constructor

Metadata Lifecycle

• Cleared automatically by publishStoredMetrics()
• No limit on number of metadata entries
• Metadata values must be strings

Cold Start Detection

• Metrics instance must be at module scope (outside handler)
• Creating instance inside handler causes every invocation to be cold start
• ColdStart metric only emitted on actual cold starts (value 1)
• No metric emitted on warm starts (absence indicates warm start)

Configuration Resolution Order

For each setting, resolution follows this priority (highest to lowest):

1. Explicit constructor parameters (highest priority)
2. Custom config service (if provided)
3. Environment variables
4. Defaults (lowest priority)

Example:

// If all three are set:
// - Constructor: namespace = 'explicit'
// - ConfigService: namespace = 'config'
// - Env: POWERTOOLS_METRICS_NAMESPACE = 'env'
// Result: Uses 'explicit'

const metrics = new Metrics({
  namespace: 'explicit',  // Wins
  customConfigService: new CustomConfigService()
});

CloudWatch Constraints

Dimensions

• Maximum 29 dimensions per metric
• High-cardinality dimensions cause performance issues and increased costs
• Each dimension increases CloudWatch metric costs
• Dimension values must be non-empty strings

Metadata

• Not displayed in CloudWatch Metrics UI
• Searchable in CloudWatch Logs Insights
• Cannot be used for CloudWatch alarms or dashboards directly
• No limit on number of metadata entries

Metric Resolution

• Standard (60s): Lower cost, 60-second granularity
• High (1s): Higher cost, 1-second granularity
• High-resolution metrics incur additional CloudWatch charges

Lambda Environment Constraints

EMF Output

• Metrics emitted to stdout as JSON
• CloudWatch agent automatically processes EMF format in Lambda
• Logger must not interfere with stdout (custom logger only for debug/warnings)
• Each EMF blob limited to 256 KB

Function Name Resolution

For cold start metric function_name dimension, resolved in order:

1. Explicit parameter to captureColdStartMetric('name')
2. Constructor option functionName
3. Environment variable POWERTOOLS_METRICS_FUNCTION_NAME
4. Lambda context (when using decorator/middleware)

If none available, ColdStart metric emitted without function_name dimension.

Compatibility

• Language: TypeScript / JavaScript (Node.js)
• Lambda Runtime: Node.js 14.x and higher
• Middy Versions: 3.x, 4.x, 5.x, 6.x
• TypeScript Decorators: Requires experimentalDecorators: true

Performance Considerations

• Metrics emitted asynchronously via EMF (no impact on function latency)
• Buffering up to 100 metrics reduces EMF blob count
• singleMetric() creates new instance per call (memory overhead)
• High dimension cardinality increases CloudWatch costs and can impact performance

Disabled Metrics

When POWERTOOLS_METRICS_DISABLED=true:

• Metrics are not emitted to CloudWatch
• All methods continue to work (no errors)
• Useful for local development and testing
• Does not affect Lambda function execution