Papertrail Lambda Extension

This AWS Lambda extension allows sending logs to Papertrail log server from AWS Lambda runtime using Extension API and Logs API.

Installation

To use this extension, it must be compiled and installed as an AWS Lambda Layer

$ GOOS=linux GOARCH=amd64 go build -o bin/extensions/papertrail-lambda-extension main.go
$ chmod +x bin/extensions/papertrail-lambda-extension
$ cd bin
$ zip -r extension.zip extensions/
$ aws lambda publish-layer-version --layer-name "papertrail-lambda-extension" --region <use your region> --zip-file  "fileb://extension.zip"

Use the the ARN of the Layer from the output above in your Lambda function layers configuration (ARN with version)

Configuration

In order to work the extension requires couple of environment variables configurations in the AWS Lambda function:

Name	Description	Default Value
PAPERTRAIL_ADDRESS	Papertrail Host address (logsN.papertrailapp.com:XXXXX)
PAPERTRAIL_PROTOCOL	Papertrail Host network protocol (utc / tcp)	udp
PAPERTRAIL_LEVEL	Log Level for logs to send to Papertrail (DEBUG / INFO / WARN / ERROR / FATAL)	INFO
LAMBDA_LOG_REGEX	Regex (Golang format) for parsing the log output of the source logger	`(?P\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:.\d*)?(-\d{2}:\d{2}

Log Regex

Different AWS Lambda runtimes print the logs in different format and the LAMBDA_LOG_REGEX variable helps to parse the log in proper way. Currently it supports simple log messages without additonal outputs.
Lambda log usualy contains date and time of the record, log level, Lambda Execution ID and the messages.
Sample runtimes regex:

• Python - \[(?P<Level>\b[a-zA-Z]*\b)\]\s*(?P<Date>\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d*)?(-\d{2}:\d{2}|Z?))\s*(?P<UUID>\b[0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12}\b)\s*(?P<Message>.*)
• NodeJS (default) - (?P<Date>\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d*)?(-\d{2}:\d{2}|Z?))\s*(?P<UUID>\b[0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12}\b)\s*(?P<Level>\b[a-zA-Z]*\b)\s*(?P<Message>.*)

Python runtime

import logging

logger = logging.getLogger()
logger.setLevel(logging.INFO)

def lambda_handler(event, context):
    logger.info('info message')
    logger.error('error message')

[INFO]  2021-09-12T17:02:25.260Z    9b11e6a8-4ba0-49a4-943e-66038037f4d2    info message
[ERROR]   2021-09-12T17:02:25.260Z    9b11e6a8-4ba0-49a4-943e-66038037f4d2    error message

NodeJS runtime

exports.handler = async (event, context) => {
  console.log('info message');
  console.error('error message');
};

2021-09-12T17:30:22.463Z	065ceb04-4a9d-47e5-901a-4c9c4990a456	INFO	info message
2021-09-12T17:30:23.200Z	065ceb04-4a9d-47e5-901a-4c9c4990a456	ERROR	error message

Output Format

Logs sent to Papertrail as JSON obejct in same structure:

{
  "time": "2021-09-12T17:30:23.143Z",
  "log": "info message",
  "level": "INFO",
  "lambda_time": "2021-09-12T17:30:23.159Z",
  "lambda_type": "function",
  "lambda_exec_id": "065ceb04-4a9d-47e5-901a-4c9c4990a456"
}

• time - Time of the log sent by the application
• log - Log message parsed by LAMBDA_LOG_REGEX regex
• level - Log message level parsed by LAMBDA_LOG_REGEX regex
• lambda_time - Time when message was received by Logs API
• lambda_type - Lambda log record type
• lambda_exec_id - Lambda Execution ID

Papertrail System

Papertrail system is the name of the AWS Lambda function name in lowercase

Host

AWS Lambda internal IP Address

Lambda Record Type

AWS Lambda record can be function - the logs from the application, platform - different records from the Lambda platform(runtime) and extention - logs generated by the extension. Read more in AWS docs.

TODO

• Support HTTP
• Test UDP

Disclaimer

The project is not affiliated with Papertrail.