or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

api-reference.mdconstraints.mdindex.mdusage-patterns.md
tile.json

usage-patterns.mddocs/

Usage Patterns

Basic Patterns

Manual Flushing

import { Metrics, MetricUnit } from '@aws-lambda-powertools/metrics';

const metrics = new Metrics({
  namespace: 'serverlessAirline',
  serviceName: 'orders'
});

export const handler = async (event: any) => {
  metrics.addMetric('invocations', MetricUnit.Count, 1);
  metrics.addMetric('itemsProcessed', MetricUnit.Count, event.items.length);
  metrics.publishStoredMetrics();
};

Decorator Auto-Flushing

import type { Context } from 'aws-lambda';
import type { LambdaInterface } from '@aws-lambda-powertools/commons/types';
import { Metrics, MetricUnit } from '@aws-lambda-powertools/metrics';

const metrics = new Metrics({
  namespace: 'serverlessAirline',
  serviceName: 'orders'
});

class Lambda implements LambdaInterface {
  @metrics.logMetrics({
    captureColdStartMetric: true,
    throwOnEmptyMetrics: true,
    defaultDimensions: { environment: process.env.ENVIRONMENT || 'dev' }
  })
  public async handler(event: any, _context: Context) {
    metrics.addMetric('orderProcessed', MetricUnit.Count, 1);
  }
}

const handlerClass = new Lambda();
export const handler = handlerClass.handler.bind(handlerClass);

Middleware Auto-Flushing

import { Metrics, MetricUnit } from '@aws-lambda-powertools/metrics';
import { logMetrics } from '@aws-lambda-powertools/metrics/middleware';
import middy from '@middy/core';

const metrics = new Metrics({
  namespace: 'serverlessAirline',
  serviceName: 'orders'
});

const lambdaHandler = async (event: any) => {
  metrics.addMetric('orderProcessed', MetricUnit.Count, 1);
};

export const handler = middy(lambdaHandler).use(
  logMetrics(metrics, {
    captureColdStartMetric: true,
    throwOnEmptyMetrics: true,
    defaultDimensions: { environment: process.env.ENVIRONMENT || 'dev' }
  })
);

Dimension Patterns

Default Dimensions (Persistent)

const metrics = new Metrics({
  namespace: 'serverlessAirline',
  serviceName: 'orders',
  defaultDimensions: {
    environment: process.env.ENVIRONMENT || 'dev',
    version: process.env.APP_VERSION || '1.0.0',
    aws_region: process.env.AWS_REGION || 'us-east-1'
  }
});

export const handler = async (event: any) => {
  // Default dimensions automatically included
  metrics.addMetric('orderProcessed', MetricUnit.Count, 1);
  metrics.publishStoredMetrics();
};

Request-Specific Dimensions (Cleared After Publish)

export const handler = async (event: any) => {
  metrics.addDimensions({
    customer_id: event.customerId,
    order_type: event.orderType,
    payment_method: event.paymentMethod
  });

  metrics.addMetric('orderCreated', MetricUnit.Count, 1);
  metrics.publishStoredMetrics(); // Clears request-specific dimensions
};

Mixed Dimensions

const metrics = new Metrics({
  namespace: 'serverlessAirline',
  serviceName: 'orders',
  defaultDimensions: { environment: 'prod', team: 'checkout' }
});

export const handler = async (event: any) => {
  // Request-specific dimensions
  metrics.addDimension('customer_tier', event.tier);
  metrics.addDimension('region', event.region);

  metrics.addMetric('checkoutCompleted', MetricUnit.Count, 1);
  metrics.publishStoredMetrics(); // Default dimensions remain, request dimensions cleared
};

Metadata Patterns

Request Tracing

export const handler = async (event: any) => {
  metrics.addMetadata('request_id', event.requestContext?.requestId);
  metrics.addMetadata('correlation_id', event.headers?.['x-correlation-id']);
  metrics.addMetadata('trace_id', event.headers?.['x-amzn-trace-id']);

  metrics.addMetric('orderCreated', MetricUnit.Count, 1);
  metrics.publishStoredMetrics();
};

Entity Tracking

export const handler = async (event: any) => {
  // High-cardinality as metadata
  metrics.addMetadata('user_id', event.userId);
  metrics.addMetadata('order_id', event.orderId);

  // Low-cardinality as dimension
  metrics.addDimension('customer_tier', event.customerTier);

  metrics.addMetric('checkoutCompleted', MetricUnit.Count, 1);
  metrics.publishStoredMetrics();
};

Error Context

export const handler = async (event: any) => {
  try {
    // Process order
    metrics.addMetric('orderSuccess', MetricUnit.Count, 1);
  } catch (error) {
    // Error details as metadata
    metrics.addMetadata('error_type', error.name);
    metrics.addMetadata('error_message', error.message);
    metrics.addMetadata('order_id', event.orderId);

    // Error category as dimension (low cardinality)
    metrics.addDimension('error_category', categorizeError(error));
    metrics.addMetric('orderFailure', MetricUnit.Count, 1);

    throw error;
  } finally {
    metrics.publishStoredMetrics();
  }
};

Cold Start Patterns

Manual Capture

const metrics = new Metrics({
  namespace: 'serverlessAirline',
  serviceName: 'orders',
  functionName: 'order-processor'
});

export const handler = async (event: any) => {
  metrics.captureColdStartMetric();
  metrics.addMetric('orderProcessed', MetricUnit.Count, 1);
  metrics.publishStoredMetrics();
};

Automatic with Decorator/Middleware

See Decorator/Middleware examples above with captureColdStartMetric: true option.

Advanced Patterns

Single Metric (Different Dimensions Per Metric)

export const handler = async (event: any) => {
  // Regular metrics with standard dimensions
  metrics.addDimension('region', 'us-east-1');
  metrics.addMetric('orderProcessed', MetricUnit.Count, 1);

  // Single metric with different dimensions
  const singleMetric = metrics.singleMetric();
  singleMetric.addDimension('payment_processor', 'stripe');
  singleMetric.addMetric('paymentCharge', MetricUnit.Count, event.amount);
  // Automatically flushed

  metrics.publishStoredMetrics();
};

Multiple Single Metrics (Loop)

export const handler = async (event: any) => {
  // Emit metric for each payment with specific dimensions
  for (const payment of event.payments) {
    const singleMetric = metrics.singleMetric();
    singleMetric.addDimension('payment_method', payment.method);
    singleMetric.addDimension('currency', payment.currency);
    singleMetric.addMetric('paymentAmount', MetricUnit.Count, payment.amount);
  }

  // Aggregated metrics
  metrics.addMetric('totalPayments', MetricUnit.Count, event.payments.length);
  metrics.publishStoredMetrics();
};

Custom Timestamp (Backfilling)

export const handler = async (event: any) => {
  const eventTimestamp = new Date(event.timestamp);
  metrics.setTimestamp(eventTimestamp);

  metrics.addMetric('orderReceived', MetricUnit.Count, 1);
  metrics.publishStoredMetrics();
};

Multiple Namespaces

const appMetrics = new Metrics({ namespace: 'Application', serviceName: 'orders' });
const businessMetrics = new Metrics({ namespace: 'Business', serviceName: 'orders' });

export const handler = async (event: any) => {
  // Technical metrics
  appMetrics.addMetric('apiCall', MetricUnit.Count, 1);
  appMetrics.addMetric('latency', MetricUnit.Milliseconds, 150);
  appMetrics.publishStoredMetrics();

  // Business metrics
  businessMetrics.addMetric('revenue', MetricUnit.Count, event.amount);
  businessMetrics.publishStoredMetrics();
};

Multiple Metrics Instances with Middleware

import { logMetrics } from '@aws-lambda-powertools/metrics/middleware';
import middy from '@middy/core';

const orderMetrics = new Metrics({ namespace: 'airline', serviceName: 'orders' });
const paymentMetrics = new Metrics({ namespace: 'airline', serviceName: 'payments' });

const lambdaHandler = async (event: any) => {
  orderMetrics.addMetric('orderCreated', MetricUnit.Count, 1);
  paymentMetrics.addMetric('paymentProcessed', MetricUnit.Count, 1);
};

// Both flushed automatically
export const handler = middy(lambdaHandler).use(
  logMetrics([orderMetrics, paymentMetrics], { captureColdStartMetric: true })
);

Custom Config Service

import type { ConfigServiceInterface } from '@aws-lambda-powertools/metrics/types';

class CustomConfigService implements ConfigServiceInterface {
  getNamespace(): string { return process.env.CUSTOM_NAMESPACE || 'default'; }
  getFunctionName(): string { return process.env.CUSTOM_FUNCTION_NAME || 'unknown'; }
  getServiceName(): string { return process.env.CUSTOM_SERVICE_NAME || 'service'; }
}

const metrics = new Metrics({
  customConfigService: new CustomConfigService()
});

Metric Serialization (Testing)

import { Metrics, MetricUnit } from '@aws-lambda-powertools/metrics';

const metrics = new Metrics({ namespace: 'test', serviceName: 'orders' });
metrics.addMetric('orderProcessed', MetricUnit.Count, 1);

// Get EMF output without publishing
const emfOutput = metrics.serializeMetrics();
console.log(JSON.stringify(emfOutput));

High-Resolution Metrics

import { MetricResolution } from '@aws-lambda-powertools/metrics';

metrics.addMetric('apiLatency', MetricUnit.Milliseconds, 250, MetricResolution.High);

Conditional Metrics

export const handler = async (event: any) => {
  if (event.shouldTrack) {
    metrics.addMetric('trackedOperation', MetricUnit.Count, 1);
  }

  if (metrics.hasStoredMetrics()) {
    metrics.publishStoredMetrics();
  }
};

Strict Mode (Require Metrics)

const metrics = new Metrics({ namespace: 'airline', serviceName: 'orders' });
metrics.setThrowOnEmptyMetrics(true);

export const handler = async (event: any) => {
  // Must add at least one metric or publishStoredMetrics() throws
  metrics.addMetric('invocations', MetricUnit.Count, 1);
  metrics.publishStoredMetrics();
};