View a markdown version of this page

Publishing custom metrics with the embedded metric format - AWS Lambda
How EMF works with Web FunctionsPublishing a custom metricBilling for custom metrics

Publishing custom metrics with the embedded metric format

With the Amazon CloudWatch embedded metric format (EMF), you can publish your own metrics from AWS Lambda Web Functions, such as orders placed, cache hit rate, or payment latency. Your application writes a structured JSON object to its logs, and CloudWatch extracts the metrics from it. Use custom metrics to track what your application does. The metrics that Lambda publishes describe only request outcomes and resource usage.

You can also publish custom metrics by calling the CloudWatch PutMetricData API directly, but we recommend EMF for Web Functions:

  • No added request latency – Your application doesn't call the CloudWatch API on the path that serves your HTTP response.

  • No extra permission – You don't need the cloudwatch:PutMetricData permission. EMF uses the same Amazon CloudWatch Logs permissions that the execution role already needs for logs.

  • Centralization with your logs – Because EMF metrics travel with your logs, the home Region has values from every Region that the endpoint serves. Metrics that you publish with PutMetricData appear only in the Region where you call it.

How EMF works with Web Functions

EMF metrics travel from your application to CloudWatch through the following steps:

  1. Your application writes an EMF-formatted JSON object, followed by a newline, directly to standard output.

  2. Lambda captures it as a log event in the Region where the request ran and centralizes it into the home AWS Region, the same as any other log output. For details, see Web Function logs in Amazon CloudWatch Logs.

  3. CloudWatch extracts metrics from the object in the Region where the request ran, and Lambda replicates the metrics to the home Region. The metrics appear in the namespace that you specify in the object. In the home Region, the metrics include values from every Region that the endpoint serves.

Your custom metrics appear in your own namespace, not in AWS/Lambda/Web. That namespace is reserved for the metrics Lambda publishes.

Publishing a custom metric

The following Node.js example publishes a CheckoutLatency metric and an OrdersPlaced metric under the MyWebApp namespace, with a PaymentProvider dimension. It writes the EMF object with process.stdout.write. Do not pass an EMF object to a console method. Lambda wraps console output in its own JSON log event, and CloudWatch does not extract metrics from the wrapped object.

function publishCheckoutMetrics(provider, latencyMs, orders) {
  process.stdout.write(JSON.stringify({
    _aws: {
      Timestamp: Date.now(),
      CloudWatchMetrics: [
        {
          Namespace: 'MyWebApp',
          Dimensions: [['PaymentProvider']],
          Metrics: [
            { Name: 'CheckoutLatency', Unit: 'Milliseconds' },
            { Name: 'OrdersPlaced', Unit: 'Count' }
          ]
        }
      ]
    },
    PaymentProvider: provider,
    CheckoutLatency: latencyMs,
    OrdersPlaced: orders,
    // Fields outside the metric definitions are kept as searchable log context.
    requestPath: '/checkout'
  }) + '\n');
}

Instead of building EMF objects yourself, you can use an EMF client library, such as aws-embedded-metrics for Node.js on the GitHub website. For the list of libraries, see Creating logs in embedded metric format using the client libraries in the Amazon CloudWatch User Guide. Before you rely on a library, confirm that it writes EMF objects directly to standard output in a Web Function, instead of through console or to a CloudWatch agent.

Note the three roles that fields play in an EMF object:

  • Fields named in Metrics become CloudWatch metrics.

  • Fields named in Dimensions become metric dimensions. Keep the number of distinct dimension values low. Each combination creates a separate metric.

  • Any other field is kept in the log event as context you can query with Amazon CloudWatch Logs Insights, but does not create a metric.

Use the last property deliberately: attach high-cardinality values such as a request ID or customer ID as plain fields rather than as dimensions, so you can find the specific request in Logs Insights without multiplying your metric count.

Billing for custom metrics

EMF generates both log ingestion and custom metric charges. The log event is billed at Amazon CloudWatch Logs prices, and the extracted metrics are billed as CloudWatch custom metrics. The first centralization of a log event is free. CloudWatch extracts EMF metrics in the Region where the request ran, and Lambda replicates them to the home Region, so a request served outside the home Region produces custom metrics in both Regions.

Log volume, the number of metrics, and the number of distinct dimension combinations affect cost. Publish metrics at the granularity you will alarm on or graph, and avoid high-cardinality dimensions.

For current prices, see Amazon CloudWatch pricing.