Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@tianchu
tianchu authored Aug 3, 2020
1 parent 61ce22c commit 84014d3
Showing 1 changed file with 23 additions and 127 deletions.
150 changes: 23 additions & 127 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,91 +6,27 @@
[![Godoc](https://img.shields.io/badge/godoc-reference-blue.svg)](https://godoc.org/github.com/DataDog/datadog-lambda-go)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/DataDog/datadog-lambda-go/blob/master/LICENSE)

Datadog's Lambda Go client library enables distributed tracing between serverful and serverless environments.
Datadog Lambda Library for Go enables enhanced Lambda metrics, distributed tracing, and custom metric submission from AWS Lambda functions.

## Installation

```bash
go get github.com/DataDog/datadog-lambda-go
```

You can set the following environment variables via the AWS CLI or Serverless Framework

### DD_API_KEY

Your datadog API key

### DD_SITE

Which Datadog site to use. Set this to `datadoghq.eu` to send your data to the Datadog EU site.

### DD_LOG_LEVEL

How much logging datadog-lambda-go should do. Set this to "debug" for extensive logs.
Follow the [installation instructions](https://docs.datadoghq.com/serverless/installation/go/), and view your function's enhanced metrics, traces and logs in Datadog.

### DD_FLUSH_TO_LOG

If your Lambda function powers a performance-critical task (e.g., a consumer-facing API). You can avoid the added latencies of metric-submitting API calls, by setting this value to true. Custom metrics will be submitted asynchronously through CloudWatch Logs and the Datadog log forwarder.

### DD_ENHANCED_METRICS

The Lambda layer will increment a Lambda integration metric called `aws.lambda.enhanced.invocations` with each invocation and `aws.lambda.enhanced.errors` if the invocation results in an error. These metrics are tagged with the function name, region, account, runtime, memorysize, and `cold_start:true|false`. This is enabled by default.

## Usage
## Enhanced Metrics

Datadog needs to be able to read headers from the incoming Lambda event. Wrap your Lambda handler function like so:
Once [installed](#installation), you should be able to view enhanced metrics for your Lambda function in Datadog.

```go
package main

import (
"github.com/aws/aws-lambda-go/lambda"
"github.com/DataDog/datadog-lambda-go"
)

func main() {
// Wrap your lambda handler like this
lambda.Start(ddlambda.WrapHandler(myHandler, nil))
/* OR with manual configuration options
lambda.Start(ddlambda.WrapHandler(myHandler, &ddlambda.Config{
BatchInterval: time.Second * 15
APIKey: "my-api-key",
}))
*/
}

func myHandler(ctx context.Context, event MyEvent) (string, error) {
// ...
}
```
Check out the official documentation on [Datadog Lambda enhanced metrics](https://docs.datadoghq.com/integrations/amazon_lambda/?tab=go#real-time-enhanced-lambda-metrics).

## Custom Metrics

Custom metrics can be submitted using the `Metric` function. The metrics are submitted as [distribution metrics](https://docs.datadoghq.com/graphing/metrics/distributions/).
Once [installed](#installation), you should be able to submit custom metrics from your Lambda function.

**IMPORTANT NOTE:** If you have already been submitting the same custom metric as non-distribution metric (e.g., gauge, count, or histogram) without using the datadog-lambda-go lib, you MUST pick a new metric name to use for `ddlambda.Metric`. Otherwise that existing metric will be converted to a distribution metric and the historical data prior to the conversion will be no longer queryable.
Check out the instructions for [submitting custom metrics from AWS Lambda functions](https://docs.datadoghq.com/integrations/amazon_lambda/?tab=go#custom-metrics).

```go
ddlambda.Metric(
"coffee_house.order_value", // Metric name
12.45, // The value
"product:latte", "order:online" // Associated tags
)
```

### VPC

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/).

## Distributed Tracing

[Distributed tracing](https://docs.datadoghq.com/tracing/guide/distributed_tracing/?tab=python) 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.
## Tracing

Distributed tracing headers are language agnostic, e.g., a trace can be propagated between a Java service running on a host to a Lambda function written in Go.

Because the trace context is propagated through HTTP request headers, the Lambda function needs to be triggered by AWS API Gateway or AWS Application Load Balancer.

To enable this feature, make sure any outbound requests have Datadog's tracing headers.
Use `ddlambda.AddTraceHeaders(ctx, req)` to inject the Datadog tracing headers to the outbound requests.

```go
req, err := http.NewRequest("GET", "http://example.com/status")
Expand All @@ -103,68 +39,28 @@ To enable this feature, make sure any outbound requests have Datadog's tracing h
}
```

## Sampling

The traces for your Lambda function are converted by Datadog from AWS X-Ray traces. X-Ray needs to sample the traces that the Datadog tracing agent decides to sample, in order to collect as many complete traces as possible. You can create X-Ray sampling rules to ensure requests with header `x-datadog-sampling-priority:1` or `x-datadog-sampling-priority:2` via API Gateway always get sampled by X-Ray.
## Environment Variables

These rules can be created using the following AWS CLI command.
### DD_FLUSH_TO_LOG

```bash
aws xray create-sampling-rule --cli-input-json file://datadog-sampling-priority-1.json
aws xray create-sampling-rule --cli-input-json file://datadog-sampling-priority-2.json
```
Set to `true` (recommended) to send custom metrics asynchronously (with no added latency to your Lambda function executions) through CloudWatch Logs with the help of [Datadog Forwarder](https://github.com/DataDog/datadog-serverless-functions/tree/master/aws/logs_monitoring). Defaults to `false`. If set to `false`, you also need to set `DD_API_KEY` and `DD_SITE`.

The file content for `datadog-sampling-priority-1.json`:

```json
{
"SamplingRule": {
"RuleName": "Datadog-Sampling-Priority-1",
"ResourceARN": "*",
"Priority": 9998,
"FixedRate": 1,
"ReservoirSize": 100,
"ServiceName": "*",
"ServiceType": "AWS::APIGateway::Stage",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {
"x-datadog-sampling-priority": "1"
}
}
}
```
### DD_API_KEY

The file content for `datadog-sampling-priority-2.json`:

```json
{
"SamplingRule": {
"RuleName": "Datadog-Sampling-Priority-2",
"ResourceARN": "*",
"Priority": 9999,
"FixedRate": 1,
"ReservoirSize": 100,
"ServiceName": "*",
"ServiceType": "AWS::APIGateway::Stage",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {
"x-datadog-sampling-priority": "2"
}
}
}
```
If `DD_FLUSH_TO_LOG` is set to `false` (not recommended), the Datadog API Key must be defined.

### DD_SITE

If `DD_FLUSH_TO_LOG` is set to `false` (not recommended), and your data need to be sent to the Datadog EU site, you must set `DD_SITE` to `datadoghq.eu`. Defaults to `datadoghq.com`.

## Non-proxy integration
### DD_LOG_LEVEL

If your Lambda function is triggered by API Gateway via the non-proxy integration, then you have to set up a mapping template, which passes the Datadog trace context from the incoming HTTP request headers to the Lambda function via the event object.
Set to `debug` enable debug logs from the Datadog Lambda Library. Defaults to `info`.

### DD_ENHANCED_METRICS

If your Lambda function is deployed by the Serverless Framework, such a mapping template gets created by default.
Generate enhanced Datadog Lambda integration metrics, such as, `aws.lambda.enhanced.invocations` and `aws.lambda.enhanced.errors`. Defaults to `true`.

## Opening Issues

Expand Down

0 comments on commit 84014d3

Please sign in to comment.