{"id":2873,"library":"aws-embedded-metrics","title":"AWS Embedded Metrics","description":"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.","status":"active","version":"3.5.0","language":"en","source_language":"en","source_url":"https://github.com/awslabs/aws-embedded-metrics-python","tags":["aws","metrics","cloudwatch","observability","emf","monitoring"],"install":[{"cmd":"pip install aws-embedded-metrics","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Used 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.","package":"boto3","optional":true}],"imports":[{"symbol":"get_metrics","correct":"from aws_embedded_metrics import get_metrics"},{"symbol":"metric_scope","correct":"from aws_embedded_metrics import metric_scope"}],"quickstart":{"code":"from aws_embedded_metrics import metric_scope\n\n@metric_scope\ndef process_data(metrics):\n    metrics.set_namespace(\"MyApplication\")\n    metrics.put_dimensions({\"Service\": \"DataProcessor\", \"Operation\": \"Transform\"})\n\n    # Add multiple metric values for a single metric\n    metrics.put_metric(\"ProcessingLatency\", 100, \"Milliseconds\")\n    metrics.put_metric(\"ProcessingLatency\", 95, \"Milliseconds\")\n    metrics.put_metric(\"ProcessingLatency\", 105, \"Milliseconds\")\n\n    metrics.set_property(\"Region\", \"us-east-1\")\n    metrics.set_property(\"ContainerId\", \"abc-123\")\n\n    print(\"Processing data...\")\n\nif __name__ == \"__main__\":\n    # In a deployed AWS environment, these metrics would be collected by the CloudWatch Agent\n    # and sent to CloudWatch. Locally, they are printed to stdout in EMF format.\n    process_data()","lang":"python","description":"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."},"warnings":[{"fix":"Review your metric and dimension definitions. Ensure compliance with new validation rules. Explicitly manage dimension preservation if needed using `metrics.set_preserve_dimensions()`.","message":"Version 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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Consolidate your dimensions or create multiple dimension sets if you require more than 30 distinct dimensions per metric group.","message":"Version 2.0.0 enforced a limit of 30 dimensions per dimension set. Exceeding this limit will now raise a `DimensionSetExceededError`.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"Metrics 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.","severity":"gotcha","affected_versions":"*"},{"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.","message":"High-resolution metrics (1-second granularity) require explicit configuration. By default, metrics are collected at 1-minute resolution.","severity":"gotcha","affected_versions":">=3.1.0"},{"fix":"Upgrade to `aws-embedded-metrics>=3.3.0` for improved async generator support. Always test thoroughly when using with complex asynchronous patterns.","message":"When 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.","severity":"gotcha","affected_versions":"<3.3.0"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}