Skip to content

The library is no longer needed when using the extension #80

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 3 commits into from
Closed

The library is no longer needed when using the extension #80

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
03bb4ef
The library is no longer needed when using the extension
tianchu Apr 20, 2022
5994ca3
Update README.md
tianchu May 5, 2022
5e002d7
Update README.md
tianchu May 5, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
145 changes: 22 additions & 123 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,119 +5,21 @@
![](https://github.com/DataDog/datadog-lambda-java/workflows/Test%20on%20Master%20branch/badge.svg)
![Maven Central](https://img.shields.io/maven-central/v/com.datadoghq/datadog-lambda-java)

The Datadog Lambda Java Client Library for Java (8 and 11) enables [enhanced lambda metrics](https://docs.datadoghq.com/integrations/amazon_lambda/?tab=awsconsole#real-time-enhanced-lambda-metrics)
and [distributed tracing](https://docs.datadoghq.com/integrations/amazon_lambda/?tab=awsconsole#tracing-with-datadog-apm)
between serverful and serverless environments, as well as letting you send
[custom metrics](https://docs.datadoghq.com/integrations/amazon_lambda/?tab=awsconsole#custom-metrics)
to the Datadog API.
:warning:THIS LIBRARY IS NO LONGER REQUIRED WHEN USING THE LATEST VERSION OF THE DATADOG LAMBDA EXTENSION. THIS README IS ONLY REVELANT IF YOU WANT TO KEEP INSTRUMENTING USING THE DATADOG FORWARDER.:warning:

:warning: Older versions of `datadog-lambda-java` include `log4j <= 2.14.0` as a transitive dependency.
We recommend you upgrade to `datadog-lambda-java 0.3.4` or greater, or `1.4.1` or greater.
[Additional upgrade instructions](https://docs.datadoghq.com/serverless/installation/java/?tab=maven#upgrading) are available on our docs site.
[Additional upgrade instructions](https://docs.datadoghq.com/serverless/installation/java/?tab=maven#upgrading) are available on our docs site.:warning:

## Installation

This library will be distributed through [Maven Central](https://search.maven.org/artifact/com.datadoghq/datadog-lambda-java).
Follow the [installation instructions](https://docs.datadoghq.com/serverless/installation/java/), and view your function's enhanced metrics, traces and logs in Datadog.

## Environment Variables

### DD_LOG_LEVEL

Set to `debug` enable debug logs from the Datadog Lambda Library. Defaults to `info`.

### DD_ENHANCED_METRICS

Generate enhanced Datadog Lambda integration metrics, such as, `aws.lambda.enhanced.invocations` and `aws.lambda.enhanced.errors`. Defaults to `true`.

## Enhanced Metrics

Once [installed](#installation), you should be able to view enhanced metrics for your Lambda function in Datadog.

Check out the official documentation on [Datadog Lambda enhanced metrics](https://docs.datadoghq.com/integrations/amazon_lambda/?tab=java#real-time-enhanced-lambda-metrics).

## Custom Metrics

Once [installed](#installation), you should be able to submit custom metrics from your Lambda function.

Check out the instructions for [submitting custom metrics from AWS Lambda functions](https://docs.datadoghq.com/integrations/amazon_lambda/?tab=java#custom-metrics).

## Installing the Java Tracer

The [Java Tracer](https://docs.datadoghq.com/tracing/setup_overview/setup/java/?tab=containers)
is an optional component that allows you to trace the execution of your Java Lambda function.
The traces will be viewable from your Serverless function details page within Datadog.

Briefly, in order to use the Java tracer, the following prerquisites must be met (detailed below):
1. The `datadog-lambda-java` library must be included in your project, following these [installation instructions](https://docs.datadoghq.com/serverless/installation/java/)
1. You must use a compatible Java runtime
1. You must attach the Java Tracer lambda layer
1. Several environment variables must be set
1. Your handler must instantiate a `new DDLambda` in order to start traces, and call `DDLambda#finish` in order to end traces.


### Cold start considerations

The Java Tracer adds a nontrivial cold start penalty.
Expect roughly 6 seconds per cold start if your Lambda function is configured with 3008MB of memory.
Lambda runtime CPU scales with the amount of memory allocated, so allocating more memory may help alleviate cold start issues.
Also consider using provisioned concurrency to keep your lambda function warm.
Datadog Lambda Library for Java (8 and 11) enables [enhanced Lambda metrics](https://docs.datadoghq.com/serverless/enhanced_lambda_metrics), [distributed tracing](https://docs.datadoghq.com/serverless/distributed_tracing), and [custom metric submission](https://docs.datadoghq.com/serverless/custom_metrics) from AWS Lambda functions.

### Compatible Java runtimes

- java8.al2 (aka Java 8 (Corretto))
- java11 (aka Java 11 (Corretto))

If your lambda function is using Java 8, please change it to Java 8 Corretto.
It's called java8.al2 if you're editing serverless.yaml.

### Required Lambda Layer containing the Java Tracer

```
arn:aws:lambda:[REGION]:464622532012:layer:dd-trace-java:2
```

The lambda layer version (in this case, `2`) will always correspond with the minor version of the `datadog-lambda-java` library.

### Required environment variables for the Java Tracer

```bash
JAVA_TOOL_OPTIONS: "-javaagent:\"/opt/java/lib/dd-java-agent.jar\""
DD_LOGS_INJECTION: "true"
DD_JMXFETCH_ENABLED: "false"
DD_TRACE_ENABLED: "true"
```

### Required code modification for the Java Tracer

In order to use the Java Tracer, you must instantiate a new `DDLambda` at the beginning of your Lambda function and call `DDLambda#finish()` at the end of it.

```java
public class Handler{

public ApiGatewayResponse handleRequest(APIGatewayProxyRequestEvent input, Context context){
DDLambda ddl = new DDLambda(input, context); // required to set various tags inside the tracer

ddl.metric("foo.bar", 42, null);
do_some_stuff();
make_some_http_requests();

ddl.finish(); // Required to complete the trace
return new ApiGatewayResponse();
}
}
```

`DDLambda ddl = new DDLambda(input, context);` starts a new trace (if the Java Tracer agent is attached to the JRE)
and sets tags based on the Lambda context. If there is a trace context attached to the request, that will be used
to set the trace ID and the parent of the span.
## Installation

`ddl.finish();` finishes the active span and closes the active trace scope.
The tracer will flush the trace to Cloudwatch logs once this is called.
This library is distributed through [Maven Central](https://search.maven.org/artifact/com.datadoghq/datadog-lambda-java). It is only required when instrumenting using the Datadog Forwarder, see the [installation instructions](https://docs.datadoghq.com/serverless/guide/datadog_forwarder_java/). Also see the latest [installation instructions](https://docs.datadoghq.com/serverless/installation/java/) using the Datadog Lambda extension.

# Distributed Tracing
## Distributed Tracing

## Upstream Requests
### Upstream Requests

You may want to include this Lambda invocation as a child span of some larger trace.
If so, you should anticipate that the event triggering the Lambda will have some trace context attached to it.
Expand All @@ -130,43 +32,40 @@ Currently supported events are:

If you are using a different event with trace context, you may choose to create a class that implements `Headerable` and supply that as the event instead.

## Downstream Requests
### Downstream Requests

The dd-trace-java tracer will automatically add trace context to outgoing requests for a number of popular services.
The list of instrumented services can be found here: https://docs.datadoghq.com/tracing/setup_overview/compatibility_requirements/java/ .
If you wish to enable a beta integration, please note that you must do so using an environment variable.

# Trace/Log Correlation
### Trace/Log Correlation

Please see [Connecting Java Logs and Traces](https://docs.datadoghq.com/tracing/connect_logs_and_traces/java/?tab=log4j2)

In brief, if you set the environment variable `DD_LOGS_INJECTION=true`, your trace ID and span ID are automatically injected into the MDC.
If you are using JSON-formatted logs and logging using Logback, there is nothing left to do.

## Raw-formatted logs (Log4J, etc.)

For raw formatted logs, you must update your log format and your log parser. Instructions for both are below.

### Log Format

If you are using raw formatted logs, update your formatter to include `dd.trace_context`. E.g.
1. Update Log Format

```xml
<Pattern>"%d{yyyy-MM-dd HH:mm:ss} <%X{AWSRequestId}> %-5p %c:%L %X{dd.trace_context} %m%n"</Pattern>
<!--Please note: Request ID Trace Context -->
```
If you are using raw formatted logs, update your formatter to include `dd.trace_context`. E.g.

Please note that `RequestId` has also been added.
RequestId is not strictly necessary for Trace/Log correlation, but it is useful for correlating logs and invocations.
```xml
<Pattern>"%d{yyyy-MM-dd HH:mm:ss} <%X{AWSRequestId}> %-5p %c:%L %X{dd.trace_context} %m%n"</Pattern>
<!--Please note: Request ID Trace Context -->
```

Please note that `RequestId` has also been added.
RequestId is not strictly necessary for Trace/Log correlation, but it is useful for correlating logs and invocations.

### Grok Parser
2. Update Grok Parser

The following grok parser parses Java logs formatted using the pattern in the previous section.
The following grok parser parses Java logs formatted using the pattern in the previous section.

```
java_tracer %{date("yyyy-MM-dd HH:mm:ss"):timestamp}\s\<%{uuid:lambda.request_id}\>\s%{word:level}\s+%{data:call_site}%{_trace_context}%{data:message}
```
```
java_tracer %{date("yyyy-MM-dd HH:mm:ss"):timestamp}\s\<%{uuid:lambda.request_id}\>\s%{word:level}\s+%{data:call_site}%{_trace_context}%{data:message}
```

## Opening Issues

Expand Down