diff --git a/README.md b/README.md index 3ed556b9..2d8ddd7b 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,10 @@ # datadog-lambda-layer-python +![CircleCI](https://img.shields.io/circleci/build/github/DataDog/datadog-lambda-layer-python) +[![PyPI](https://img.shields.io/pypi/v/datadog-lambda)](https://pypi.org/project/datadog-lambda/) +[![Slack](https://img.shields.io/badge/slack-%23serverless-blueviolet?logo=slack)](https://datadoghq.slack.com/channels/serverless/) +[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/DataDog/datadog-lambda-layer-python/blob/master/LICENSE) + Datadog Lambda Layer for Python (2.7, 3.6 and 3.7) enables custom metric submission from AWS Lambda functions, and distributed tracing between serverful and serverless environments. ## Installation @@ -27,15 +32,15 @@ The minor version of the `datadog-lambda` package always match the layer version The Datadog API must be defined as an environment variable via [AWS CLI](https://docs.aws.amazon.com/lambda/latest/dg/env_variables.html) or [Serverless Framework](https://serverless-stack.com/chapters/serverless-environment-variables.html): -* DD_API_KEY or DD_KMS_API_KEY (if encrypted by KMS) +- DD_API_KEY or DD_KMS_API_KEY (if encrypted by KMS) Set the following Datadog environment variable to `datadoghq.eu` to send your data to the Datadog EU site. -* DD_SITE +- DD_SITE 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 the following Datadog environment variable to `True`. Custom metrics will be submitted asynchronously through CloudWatch Logs and [the Datadog log forwarder](https://github.com/DataDog/datadog-serverless-functions/tree/master/aws/logs_monitoring). -* DD_FLUSH_TO_LOG +- DD_FLUSH_TO_LOG ### The Serverless Framework @@ -62,7 +67,6 @@ functions: DD_API_KEY: ``` - ## Basic Usage ```python @@ -76,10 +80,9 @@ def lambda_handler(event, context): requests.get("https://www.datadoghq.com") ``` - ## Custom Metrics -Custom metrics can be submitted using `lambda_metric` and the Lambda handler function needs to be decorated with `@datadog_lambda_wrapper`. The metrics are submitted as [distribution metrics](https://docs.datadoghq.com/graphing/metrics/distributions/). +Custom metrics can be submitted using `lambda_metric` and the Lambda handler function needs to be decorated with `@datadog_lambda_wrapper`. The metrics are submitted as [distribution metrics](https://docs.datadoghq.com/graphing/metrics/distributions/). **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 Layer, you MUST pick a new metric name to use for `lambda_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. @@ -97,14 +100,14 @@ def lambda_handler(event, context): ``` ### 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/). +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. +[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. -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 Python. +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 Python. 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. @@ -119,7 +122,7 @@ def lambda_handler(event, context): requests.get("https://www.datadoghq.com") ``` -Note, the Datadog Lambda Layer is only needed to enable *distributed* tracing between Lambda and non-Lambda services. For standalone Lambda functions, traces can be found in Datadog APM after configuring [the X-Ray integration](https://docs.datadoghq.com/integrations/amazon_xray/). +Note, the Datadog Lambda Layer is only needed to enable _distributed_ tracing between Lambda and non-Lambda services. For standalone Lambda functions, traces can be found in Datadog APM after configuring [the X-Ray integration](https://docs.datadoghq.com/integrations/amazon_xray/). ### Patching @@ -150,46 +153,48 @@ aws xray create-sampling-rule --cli-input-json file://datadog-sampling-priority- ``` 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" - } + "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" } + } } ``` 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" - } + "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" } + } } ``` @@ -199,7 +204,6 @@ If your Lambda function is triggered by API Gateway via [the non-proxy integrati If your Lambda function is deployed by the Serverless Framework, such a mapping template gets created by default. - ## Opening Issues If you encounter a bug with this package, we want to hear about it. Before opening a new issue, search the existing issues to avoid duplicates. @@ -208,12 +212,10 @@ When opening an issue, include the Datadog Lambda Layer version, Python version, You can also open an issue for a feature request. - ## Contributing If you find an issue with this package and have a fix, please feel free to open a pull request following the [procedures](CONTRIBUTING.md). - ## License Unless explicitly stated otherwise all files in this repository are licensed under the Apache License Version 2.0.