Registry / aws / aws-embedded-metrics

aws-embedded-metrics

library3.5.0pypypi✓ verified 24d ago

The AWS Embedded Metrics Python library provides an easy way to emit custom metrics asynchronously, allowing users to consolidate logs and metrics into a single data stream without complex metric client setup. It formats metric data in a structured log format (EMF) for consumption by CloudWatch Logs and then CloudWatch. The current version is 3.5.0, and it follows an active release cadence with frequent updates.

aws observability

pip install aws-embedded-metrics

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · AWS-EMBEDDED-METRI

aws-embedded-metrics

awspythonv3.5.0

Install

4.0s avg

Import

689ms

Disk

27MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.5.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.726s · 27.3MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 4.0s · import 0.652s · 30MB

27MB installed

● package 27MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

MetricsLogger

✓ from aws_embedded_metrics import MetricsLogger

✗ from aws_embedded_metrics import get_metrics

metric_scope

✓ from aws_embedded_metrics import metric_scope

MetricsContext

✓ from aws_embedded_metrics import MetricsContext

This quickstart demonstrates how to use the `@metric_scope` decorator to capture custom metrics. Metrics, dimensions, and properties defined within the decorated function will be flushed as a single Embedded Metric Format (EMF) log entry at the end of the function's execution. Locally, these entries are printed to stdout; in AWS environments, they are typically picked up by the CloudWatch Agent.

from aws_embedded_metrics import metric_scope @metric_scope def process_data(metrics): metrics.set_namespace("MyApplication") metrics.put_dimensions({"Service": "DataProcessor", "Operation": "Transform"}) # Add multiple metric values for a single metric metrics.put_metric("ProcessingLatency", 100, "Milliseconds") metrics.put_metric("ProcessingLatency", 95, "Milliseconds") metrics.put_metric("ProcessingLatency", 105, "Milliseconds") metrics.set_property("Region", "us-east-1") metrics.set_property("ContainerId", "abc-123") print("Processing data...") if __name__ == "__main__": # In a deployed AWS environment, these metrics would be collected by the CloudWatch Agent # and sent to CloudWatch. Locally, they are printed to stdout in EMF format. process_data()

Debug

Known issues

breakingVersion 3.0.0 introduced significant changes to dimension and metric validation, preventing duplicate dimensions, and altering how custom dimensions are cleared and preserved across flushes. Code relying on previous behavior might break.

fix

Review your metric and dimension definitions. Ensure compliance with new validation rules. Explicitly manage dimension preservation if needed using `metrics.set_preserve_dimensions()`.

affects: >=3.0.0

breakingVersion 2.0.0 enforced a limit of 30 dimensions per dimension set. Exceeding this limit will now raise a `DimensionSetExceededError`.

fix

Consolidate your dimensions or create multiple dimension sets if you require more than 30 distinct dimensions per metric group.

affects: >=2.0.0

gotchaMetrics are emitted to `stdout` in Embedded Metric Format (EMF). For these metrics to appear in CloudWatch, you *must* have a CloudWatch Agent configured to collect logs from `stdout` and forward them to CloudWatch Logs, or run in an environment (like Lambda) where this is handled automatically.

fix

Ensure your deployment environment (EC2, ECS, EKS) has the CloudWatch Agent running and properly configured to ingest EMF logs from your application's `stdout`. Verify agent logs for processing errors.

affects: *

gotchaHigh-resolution metrics (1-second granularity) require explicit configuration. By default, metrics are collected at 1-minute resolution.

fix

To enable high-resolution for a metric, call `metrics.set_storage_resolution(1)` for that metric or globally within the scope. Be aware of increased costs for high-resolution metrics.

affects: >=3.1.0

gotchaWhen using `@metric_scope` with asynchronous functions or generators, ensure your Python version and library version are compatible, and be aware of potential context propagation issues in complex async workflows. Version 3.3.0 specifically fixed issues with async generator functions.

fix

Upgrade to `aws-embedded-metrics>=3.3.0` for improved async generator support. Always test thoroughly when using with complex asynchronous patterns.

affects: <3.3.0

Upgrade

Version history

3.5.0latest on PyPI · released Mar 27, 2026

Audit

Dependencies

boto3optionalUsed for AWS SDK interactions, particularly for credential resolution and certain internal AWS calls. Marked as optional in pyproject.toml but practically required for many use cases.

Agent activity

44 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/awslabs/aws-embedded-metrics-python ↗

packagehttps://pypi.org/project/aws-embedded-metrics/ ↗

homepagehttps://aws.amazon.com/cloudwatch/ ↗