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? |