From 84014d353f305cc991901e5b0e530858eac15ed7 Mon Sep 17 00:00:00 2001 From: Tian Chu Date: Mon, 3 Aug 2020 12:45:33 -0400 Subject: [PATCH] Update README.md --- README.md | 150 +++++++++--------------------------------------------- 1 file changed, 23 insertions(+), 127 deletions(-) diff --git a/README.md b/README.md index ed30d24c..ff381d54 100644 --- a/README.md +++ b/README.md @@ -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") @@ -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