README
Cazoo Logger
A highly opinionated structured logger for NodeJS Lambda functions.
Installation
Cazoo Logger is available on npm
npm i cazoo-logger
Basic usage
Cazoo-logger builds logger instances from the event and context of your lambda handler. The constructed loggers write JSON blobs to stdout which include a context
section.
import { CloudwatchEvent, Context} from 'aws-lambda'
import Logger from 'cazoo-logger'
function handle(event: CloudwatchEvent, context: Context) {
const log = Logger.fromContext(event, context)
log.info("handler invoked")
}
/*
{
level: 'info',
msg: 'handler invoked',
v: 1,
context: {
request_id: "abc234",
account_id: 01246545248719,
function: {
name: "my-handler",
version: context.functionVersion,
service: context.logStreamName,
stage: event.requestContext.stage
},
event: {
source: "aws.events",
type: "Scheduled Event",
id: "89170034-9c85-4ae4-b9df-04207ab07dad"
}
}
}
*/
Logging structured data
Alongside the context
field, our log schema defines a data
field for recording arbitrary structured data.
const customer = { age: 57, name: 'karen' }
const log = Logger.empty()
log.withData({customer}).info("Customer entered the store")
/*
{
level: 'info',
msg: 'Customer entered the store',
v: 1,
data: {
customer: {
name: 'karen',
age: 57
}
}
}
*/
Logging errors
Errors are treated as a special case of structured data, and can be written to the log with the recordError
method.
const error = new Error('A thing you wish had worked did not, in fact, work')
const log = Logger.empty()
log.recordError(error, 'something broke')
/**
{
level: 'error',
msg: "Huh... that didn't work",
error: {
message: "A thing you wish had worked did not, in fact work",
stack: [...],
name: "Error"
}
}
**/
Since the withData
method returns a new logger, we can chain these ideas together.
function handle(event: AwsGatewayProxyEvent, context: Context) {
const customer = readCustomerFrom(event)
const log = Logger.forAPIGatewayEvent(event, context).withData({customer})
try {
saveCustomerToDatabase(customer)
} catch (e) {
log.recordError(e)
}
}
/**
{
level: 'error',
msg: "Failed to save customer to database",
context: {
request_id: "abc1234592823645",
account_id: "01246545248719",
function: {
name: "insert-customer",
version: "v10.7.2",
stage: "dev"
},
http: {
method: "POST",
path: "/customers"
},
},
data: {
customer: {
name: 'karen',
age: 57
}
},
error: {
message: "Failed to save customer to database",
stack: [...],
name: "ConnectionError"
}
}
**/
Timeout logging
The logger will getRemainingTimeInMillis
from the lambda context and create a timeout.
This is for the logger to log just before is going to timeout the lambda, so we can start putting information out about timeouts.
Because of the way the lambda works, this has to be logged before the actual timeout happens. The time between the log and the timeout we call it buffer. The default buffer is 10ms. This default can be overriden using the environment variable CAZOO_LOGGER_TIMEOUT_BUFFER_MS
.
We just log an error indicating that the timeout happens, with type lambda.timeout
.
WARNING! 🚨🚨🚨
We need to manually cancel the timeout by calling logger.done()
before returning the lambda, otherwise we will get timeouts from previous executions when the lambda has been re-executed in a warmed start environment.
withLambdaLogger
withLambdaLogger
is an HOF that provides a correctly instantiated logger in the handler context.
It accepts an option object that will be passed to the instantiated logger.
import { CloudwatchEvent, Context} from 'aws-lambda'
import { withLambdaLogger } from 'cazoo-logger'
const loggerOptions = {
// ...
}
export const lambdaHanlder = withLambdaLogger(handle, loggerOptions)
function handle(event: CloudwatchEvent, context: Context) {
const log = context.logger
log.info("handler invoked")
}
/*
{
level: 'info',
msg: 'handler invoked',
v: 1,
context: {
request_id: "abc234",
account_id: 01246545248719,
function: {
name: "my-handler",
version: context.functionVersion,
service: context.logStreamName,
stage: event.requestContext.stage
},
event: {
source: "aws.events",
type: "Scheduled Event",
id: "89170034-9c85-4ae4-b9df-04207ab07dad"
}
}
}
*/