Metadata

The Metadata utility allows you to fetch data from the AWS Lambda Metadata Endpoint (LMDS). This can be useful for retrieving information about the Lambda execution environment, such as the Availability Zone ID.

Key features

• Fetch execution environment metadata from the Lambda Metadata Endpoint
• Automatic caching for the duration of the Lambda sandbox
• Graceful fallback to empty metadata outside Lambda (local dev, tests)
• Forward-compatible dataclass that can be extended as new fields are added

Getting started

Usage

You can fetch data from the Lambda Metadata Endpoint using the get_lambda_metadata function.

Tip

Metadata is cached for the duration of the Lambda sandbox, so subsequent calls to get_lambda_metadata will return the cached data.

getting_started_metadata.py

from aws_lambda_powertools import Logger
from aws_lambda_powertools.utilities.metadata import LambdaMetadata, get_lambda_metadata
from aws_lambda_powertools.utilities.typing import LambdaContext

logger = Logger()


def lambda_handler(event: dict, context: LambdaContext) -> dict:
    metadata: LambdaMetadata = get_lambda_metadata()
    az_id = metadata.availability_zone_id  # e.g., "use1-az1"

    logger.append_keys(az_id=az_id)
    logger.info("Processing request")

    return {"az_id": az_id}

You can also fetch metadata eagerly during cold start, so it's ready for subsequent invocations:

getting_started_metadata_eager.py

from aws_lambda_powertools import Logger
from aws_lambda_powertools.utilities.metadata import LambdaMetadata, get_lambda_metadata
from aws_lambda_powertools.utilities.typing import LambdaContext

logger = Logger()

# Fetch during cold start — cached for subsequent invocations
metadata: LambdaMetadata = get_lambda_metadata()


def lambda_handler(event: dict, context: LambdaContext) -> dict:
    logger.append_keys(az_id=metadata.availability_zone_id)
    logger.info("Processing request")

    return {"az_id": metadata.availability_zone_id}

Available metadata

Property	Type	Description
availability_zone_id	str or None	The AZ where the function is running (e.g., use1-az1)

Testing your code

The metadata endpoint is not available during local development or testing. To ease testing, the get_lambda_metadata function automatically detects when it's running in a non-Lambda environment and returns an empty LambdaMetadata instance. This allows you to write tests without needing to mock the endpoint.

If you want to mock specific metadata values for testing purposes, you can patch the internal _fetch_metadata function and set the required environment variables:

testing_metadata.py

from unittest.mock import patch

from aws_lambda_powertools.utilities.metadata import LambdaMetadata, clear_metadata_cache, get_lambda_metadata


def test_handler_uses_metadata(monkeypatch):
    # GIVEN a Lambda environment with metadata env vars
    monkeypatch.setenv("AWS_LAMBDA_INITIALIZATION_TYPE", "on-demand")
    monkeypatch.setenv("AWS_LAMBDA_METADATA_API", "127.0.0.1:1234")
    monkeypatch.setenv("AWS_LAMBDA_METADATA_TOKEN", "test-token")

    mock_response = {"AvailabilityZoneID": "use1-az1"}

    with patch(
        "aws_lambda_powertools.utilities.metadata.lambda_metadata._fetch_metadata",
        return_value=mock_response,
    ):
        # WHEN calling get_lambda_metadata
        metadata: LambdaMetadata = get_lambda_metadata()

        # THEN it returns the mocked metadata
        assert metadata.availability_zone_id == "use1-az1"

    # Clean up cache between tests
    clear_metadata_cache()


def test_handler_works_outside_lambda():
    # GIVEN no Lambda environment variables are set
    # WHEN calling get_lambda_metadata
    metadata: LambdaMetadata = get_lambda_metadata()

    # THEN it returns empty metadata without errors
    assert metadata.availability_zone_id is None

We also expose a clear_metadata_cache function that can be used to clear the cached metadata, allowing you to test different metadata values within the same execution context.