diff --git a/README.md b/README.md index 5f1d3d67..a81efc76 100644 --- a/README.md +++ b/README.md @@ -87,11 +87,8 @@ If you set the value of this variable to "true" then the Lambda layer will incre ### DD_LOGS_INJECTION -By default, the Datadog trace id gets automatically injected into the logs for correlation, if using `console` or a logging library supported for [automatic](https://docs.datadoghq.com/tracing/connect_logs_and_traces/?tab=nodejs#automatic-trace-id-injection) trace id injection. - -See instructions for [manual](https://docs.datadoghq.com/tracing/connect_logs_and_traces/?tab=nodejs#manual-trace-id-injection) trace id injection, if using other logging libraries. - -Set the environment variable `DD_LOGS_INJECTION` to `false` to disable this feature. +Controlls whether or not the Datadog Trace ID is injected into log lines. See [DD_LOGS_INJECTION](#DD_LOGS_INJECTION-environment-variable) under +the Trace & Log Correlation section below. ## Usage @@ -136,6 +133,52 @@ sendDistributionMetric( If your Lambda function is associated with a VPC, you need to ensure it has access to the [public internet](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/). +## Trace & Log Correlation + +### Using the Datadog Tracer + +If you are using the [Datadog Tracer](#datadog-tracer-experimental), follow [these instructions](https://docs.datadoghq.com/tracing/connect_logs_and_traces/nodejs/#automatic-trace-id-injection) +to set up automatic trace-log correlation. + +### Without using the Datadog Tracer + +In order to correlate logs emitted by your Lambda with specific invocations, it +is necessary to add the AWS Request ID to your logs. This is done automatically +for `console.log()`, but you will have to implement this for other logging libraries. + +The AWS Request ID is available in the context that is passed to your lambda handler, +as `context.awsRequestId`. It should be included in your log line as `lambda.request_id`. + +For example, using the [Pino](https://getpino.io/) logger: + +```typescript +const logger = require('pino')(); + +exports.handler = async function(event, context) { + + //This sets up your request-specific logger to emit logs with the Request ID property. + const req_logger = logger.child({ 'lambda.request_id': context.awsRequestId }); + + //Carry on with whatever the lambda needs to do + const work = do.Work(); + + //Write a log message + req_logger.info("Work complete"); + + return work; +} + +``` + +### DD_LOGS_INJECTION environment variable + +By default, the Datadog trace id gets automatically injected into the logs for correlation, if using `console` or a logging library supported for [automatic](https://docs.datadoghq.com/tracing/connect_logs_and_traces/?tab=nodejs#automatic-trace-id-injection) trace id injection. + +See instructions for [manual](https://docs.datadoghq.com/tracing/connect_logs_and_traces/?tab=nodejs#manual-trace-id-injection) trace id injection, if using other logging libraries. + +Set the environment variable `DD_LOGS_INJECTION` to `false` to disable this feature. + + ## Distributed Tracing [Distributed tracing](https://docs.datadoghq.com/tracing/guide/distributed_tracing/?tab=nodejs) allows you to propagate a trace context from a service running on a host to a service running on AWS Lambda, and vice versa, so you can see performance end-to-end. Linking is implemented by injecting Datadog trace context into the HTTP request headers.