aws-metadata-utils

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.

Field	Type	Description
accountId	string	The AWS account ID that the system is running in.
correlationId	string	Correlation ID (AWS request ID) for this function call.
functionMemorySize	string	Memory size of the current function.
functionName	string	The name of the function.
functionVersion	string	The version of the function.
region	string	The region of the responding function/system.
resource	string	The resource (channel, URL path...) that is responding.
runtime	string	What runtime is used?
stage	string	What AWS stage are we in?
timestampRequest	string	Request time in Unix epoch of the incoming request.
user	string	The user in this context.
viewerCountry	string	Which country did AWS CloudFront infer the user to be in?