aws-metadata-utils v1.0.1

aws-metadata-utils

aws-metadata-utils is a small utility library that helps you extract helpful metadata from your AWS event and context objects.

This library is what drives the majority of contextual metadata generated in aws-metadata-utils, MikroLog, MikroTrace, and MikroMetric outputs.

Usage

Here's an example of running aws-metadata-utils in AWS Lambda and just returning back the metadata.

import { getMetadata } from 'aws-metadata-utils';

export async function handler(event: any, context: any) {
  // Pass in your AWS event and context objects, such as from API Gateway
  const metadata = getMetadata(event, context);

  return {
    statusCode: 200,
    body: JSON.stringify(metadata)
  };
}

aws-metadata-utils will attempt to pick out various interesting details for you from the event and context objects, such as the function name, region, account ID, correlation ID (AWS request ID) and the stage that is used.

The result of the above example could result in an object with the following shape:

{
  "accountId": "123412341234",
  "correlationId": "6c933bd2-9535-45a8-b09c-84d00b4f50cc",
  "functionMemorySize": "1024",
  "functionName": "somestack-FunctionName",
  "functionVersion": "$LATEST",
  "region": "eu-north-1",
  "resource": "/functionName",
  "runtime": "AWS_Lambda_node16.x",
  "stage": "shared",
  "timestampRequest": "1657389598171",
  "user": "some user",
  "viewerCountry": "SE"
}

Usage: Getting the correlation ID

You can also use aws-metadata-utils to only get a correlation ID.

import { getCorrelationId } from 'aws-metadata-utils';

export async function handler(event: any, context: any) {
  // Pass in your AWS event and context objects, such as from API Gateway
  const correlationId = getCorrelationId(event, context);

  return {
    statusCode: 200,
    body: JSON.stringify(correlationId)
  };
}

To get the correlation ID it first checks if an appropriate ID is passed:

1. Via an event — EventBridge: event.detail.metadata.correlationId
2. Via a header — API Gateway: event.headers.x-correlation-id
3. Set new one from AWS request ID (context.awsRequestId)

If none of the above match, set it as empty.

Dynamic metadata

The dynamic metadata fields are picked up automatically if you pass them in during instantiation. Most of those metadata fields will relate to unique value types available in AWS, primarily Lambda.

If these values are not available, they will be dropped at the time of log output. In effect, this means you won't have to deal with them (being empty or otherwise) if you use aws-metadata-utils in another type of context.