8000 Update README.md · DataDog/datadog-lambda-python@c560396 · GitHub
[go: up one dir, main page]
Skip to content

Commit c560396

Browse files
tianchutianchu
authored
Update README.md
1 parent adfa6df commit c560396

File tree

1 file changed

+17
-259
lines changed

1 file changed

+17
-259
lines changed

‎README.md

Lines changed: 17 additions & 259 deletions
Original file line numberDiff line numberDiff line change
@@ -1,84 +1,30 @@
1-
# datadog-lambda-layer-python
1+
# datadog-lambda-python
22

33
[![CircleCI](https://img.shields.io/circleci/build/github/DataDog/datadog-lambda-layer-python)](https://circleci.com/gh/DataDog/datadog-lambda-layer-python)
44
[![PyPI](https://img.shields.io/pypi/v/datadog-lambda)](https://pypi.org/project/datadog-lambda/)
55
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/datadog-lambda)
66
[![Slack](https://img.shields.io/badge/slack-%23serverless-blueviolet?logo=slack)](https://datadoghq.slack.com/channels/serverless/)
77
[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/DataDog/datadog-lambda-layer-python/blob/master/LICENSE)
88

9-
Datadog Lambda Layer for Python (2.7, 3.6, 3.7 and 3.8) enables custom metric submission from AWS Lambda functions, and distributed tracing between serverful and serverless environments.
9+
Datadog Lambda Library for Python (2.7, 3.6, 3.7 and 3.8) enables enhanced Lambda metrics, distributed tracing, and custom metric submission from AWS Lambda functions.
1010

1111
## IMPORTANT NOTE
1212

1313
AWS Lambda is expected to recieve a [breaking change](https://aws.amazon.com/blogs/compute/upcoming-changes-to-the-python-sdk-in-aws-lambda/) on **January 30, 2021**. If you are using Datadog Python Lambda layer version 7 or below, please upgrade to version 11.
1414

1515
## Installation
1616

17-
Datadog Lambda Layer can be added to a Lambda function via AWS Lambda console, [AWS CLI](https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html#configuration-layers-using) or [Serverless Framework](https://serverless.com/framework/docs/providers/aws/guide/layers/#using-your-layers) using the following ARN.
18-
19-
```
20-
arn:aws:lambda:<AWS_REGION>:464622532012:layer:Datadog-<PYTHON_RUNTIME>:<VERSION>
21-
```
22-
23-
Replace `<AWS_REGION>` with the AWS region where your Lambda function is published to. Replace `<PYTHON_RUNTIME>` with one of the following that matches your Lambda's Python runtime:
24-
25-
- `Datadog-Python27`
26-
- `Datadog-Python36`
27-
- `Datadog-Python37`
28-
- `Datadog-Python38`
29-
30-
Replace `<VERSION>` with the latest layer version that can be found from [releases](https://github.com/DataDog/datadog-lambda-layer-python/releases). For example,
31-
32-
```
33-
arn:aws:lambda:us-east-1:464622532012:layer:Datadog-Python37:1
34-
```
35-
36-
### PyPI
37-
38-
When developing your Lambda function locally where AWS Layer doesn't work, the Datadog Lambda layer can be installed from [PyPI](https://pypi.org/project/datadog-lambda/) by `pip install datadog-lambda` or adding `datadog-lambda` to your project's `requirements.txt`.
39-
40-
The minor version of the `datadog-lambda` package always match the layer version. E.g., datadog-lambda v0.5.0 matches the content in layer version 5.
41-
42-
### The Serverless Framework
43-
44-
[The Datadog Serverless Framework Plugin](https://github.com/DataDog/serverless-plugin-datadog) makes it easy to manage the Datadog instrumentation for all of your Lambda functions in one place.
45-
46-
Instead of the plugin, you can also use the sample `serverless.yml` below as a reference for manually including the Lambda Layer, enable AWS X-Ray tracing, and set up environment variables.
47-
48-
```yaml
49-
provider:
50-
name: aws
51-
runtime: python3.7
52-
tracing:
53-
lambda: true
54-
apiGateway: true
55-
56-
functions:
57-
hello:
58-
handler: handler.hello
59-
events:
60-
- http:
61-
path: hello
62-
method: get
63-
layers:
64-
- arn:aws:lambda:<AWS_REGION>:464622532012:layer:Datadog-<PYTHON_RUNTIME>:<VERSION>
65-
environment:
66-
DD_FLUSH_TO_LOG: true
67-
```
68-
69-
Alternatively, consider using [serverless-plugin-datadog](https://github.com/DataDog/serverless-plugin-datadog). The plugin can take care of adding lambda layers to your functions, and wrapping your handlers.
17+
Check out our [installation instructions for Python](https://docs.datadoghq.com/serverless/installation/python/).
7018

7119
## Environment Variables
7220

7321
### DD_FLUSH_TO_LOG
7422

75-
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).
76-
77-
If set to `false`, you also need to set `DD_API_KEY` and `DD_SITE`.
23+
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). Defaultss to `false`. If set to `false`, you also need to set `DD_API_KEY` and `DD_SITE`.
7824

7925
### DD_API_KEY
8026

81-
If `DD_FLUSH_TO_LOG` is set to false (not recommended), the Datadog API Key must be defined as one of the following environment variables:
27+
If `DD_FLUSH_TO_LOG` is set to `false` (not recommended), the Datadog API Key must be defined by setting one of the following environment variables:
8228

8329
- DD_API_KEY - the Datadog API Key in plain-text, NOT recommended
8430
- DD_KMS_API_KEY - the KMS-encrypted API Key, requires the `kms:Decrypt` permission
@@ -94,231 +40,43 @@ api._api_key = "MY_API_KEY"
9440

9541
### DD_SITE
9642

97-
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`.
43+
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`.
9844

9945
### DD_LOGS_INJECTION
10046

101-
Inject Datadog trace id into logs for [correlation](https://docs.datadoghq.com/tracing/connect_logs_and_traces/?tab=python). Defaults to true.
47+
Inject Datadog trace id into logs for [correlation](https://docs.datadoghq.com/tracing/connect_logs_and_traces/?tab=python). Defaults to `true`.
10248

10349
### DD_LOG_LEVEL
10450

105-
Set to `debug` enable debug los from the Datadog Lambda Layer.
51+
Set to `debug` enable debug los from the Datadog Lambda Layer. Defaults to `info`.
10652

10753
### DD_ENHANCED_METRICS
10854

109-
Generate enhanced Datadog Lambda integration metrics, such as, `aws.lambda.enhanced.invocations` and `aws.lambda.enhanced.errors`. Defaults to true.
55+
Generate enhanced Datadog Lambda integration metrics, such as, `aws.lambda.enhanced.invocations` and `aws.lambda.enhanced.errors`. Defaults to `true`.
11056

11157
### DD_LAMBDA_HANDLER
11258

11359
For use with the [redirected handler](#Redirected-Handler) method. Location of your original lambda handler.
11460

11561
### DD_TRACE_ENABLED
11662

117-
When used with the [redirected handler](#Redirected-Handler) method, will auto initialize the tracer when set to true.
118-
119-
## Basic Usage
120-
121-
Datadog needs to be able to read headers from the incoming Lambda event. To do this, you must wrap your handler function with our library. We provide some easy ways of wrapping your handlers.
122-
123-
### Redirected Handler
124-
125-
We provide a swap in replacement handler, with zero required code changes.
63+
When used with the [redirected handler](#Redirected-Handler) method, will auto initialize the tracer when set to true. Defaults to `false`.
12664

127-
1. Set the environment variable `DD_LAMBDA_HANDLER` to your regular handler location, eg. `myfunc.handler`.
128-
2. Set your handler to `datadog_lambda.handler.handler`.
65+
### DD_MERGE_XRAY_TRACES
12966

130-
### Manual Wrap
131-
132-
You might find it more convenient to wrap your handlers manually.
133-
134-
```python
135-
import requests
136-
from datadog_lambda.wrapper import datadog_lambda_wrapper
137-
from datadog_lambda.metric import lambda_metric
138-
139-
@datadog_lambda_wrapper
140-
def lambda_handler(event, context):
141-
lambda_metric("my_metric", 10, tags=['tag:value'])
142-
requests.get("https://www.datadoghq.com")
143-
```
67+
Set to `true` to merge the X-Ray trace and the Datadog trace, when using both the X-Ray and Datadog tracing. Defaults to `false`.
14468

14569
## Custom Metrics
14670

147-
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/).
148-
149-
**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.
150-
151-
```python
152-
from datadog_lambda.wrapper import datadog_lambda_wrapper
153-
from datadog_lambda.metric import lambda_metric
154-
155-
@datadog_lambda_wrapper
156-
def lambda_handler(event, context):
157-
lambda_metric(
158-
"coffee_house.order_value", # metric
159-
12.45, # value
160-
tags=['product:latte', 'order:online'] # tags
161-
)
162-
```
163-
164-
### VPC
165-
166-
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/).
167-
168-
## Distributed Tracing
169-
170-
[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.
171-
172-
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.
71+
Check out the instructions for [submitting custom metrics from AWS Lambda functions](https://docs.datadoghq.com/integrations/amazon_lambda/?tab=python#custom-metrics).
17372

174-
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.
73+
## Tracing
17574

176-
To enable this feature, you simple need to decorate your Lambda handler function with `@datadog_lambda_wrapper`.
< 10000 /code>
75+
Check out the instructions for [collecting traces from AWS Lambda functions](https://docs.datadoghq.com/integrations/amazon_lambda/?tab=python#trace-collection), and the [official documentation for Datadog trace client](http://pypi.datadoghq.com/trace/docs/index.html).
17776

178-
```python
179-
import requests
180-
from datadog_lambda.wrapper import datadog_lambda_wrapper
181-
182-
@datadog_lambda_wrapper
183-
def lambda_handler(event, context):
184-
requests.get("https://www.datadoghq.com")
185-
```
186-
187-
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/).
188-
189-
### Patching
190-
191-
By default, widely used HTTP client libraries, such as `requests`, `urllib2` and `urllib.request` are patched automatically to inject Datadog trace context into outgoing requests.
192-
193-
You can also manually retrieve the Datadog trace context (i.e., http headers in a Python dict) and inject it to request headers when needed.
194-
195-
```python
196-
import requests
197-
from datadog_lambda.wrapper import datadog_lambda_wrapper
198-
from datadog_lambda.tracing import get_dd_trace_context
199-
200-
@datadog_lambda_wrapper
201-
def lambda_handler(event, context):
202-
headers = get_dd_trace_context()
203-
requests.get("https://www.datadoghq.com", headers=headers)
204-
```
205-
206-
### Sampling
207-
208-
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.
209-
210-
These rules can be created using the following AWS CLI command.
211-
212-
```bash
213-
aws xray create-sampling-rule --cli-input-json file://datadog-sampling-priority-1.json
214-
aws xray create-sampling-rule --cli-input-json file://datadog-sampling-priority-2.json
215-
```
216-
217-
The file content for `datadog-sampling-priority-1.json`:
218-
219-
```json
220-
{
221-
"SamplingRule": {
222-
"RuleName": "Datadog-Sampling-Priority-1",
223-
"ResourceARN": "*",
224-
"Priority": 9998,
225-
"FixedRate": 1,
226-
"ReservoirSize": 100,
227-
"ServiceName": "*",
228-
"ServiceType": "AWS::APIGateway::Stage",
229-
"Host": "*",
230-
"HTTPMethod": "*",
231-
"URLPath": "*",
232-
"Version": 1,
233-
"Attributes": {
234-
"x-datadog-sampling-priority": "1"
235-
}
236-
}
237-
}
238-
```
239-
240-
The file content for `datadog-sampling-priority-2.json`:
241-
242-
```json
243-
{
244-
"SamplingRule": {
245-
"RuleName": "Datadog-Sampling-Priority-2",
246-
"ResourceARN": "*",
247-
"Priority": 9999,
248-
"FixedRate": 1,
249-
"ReservoirSize": 100,
250-
"ServiceName": "*",
251-
"ServiceType": "AWS::APIGateway::Stage",
252-
"Host": "*",
253-
"HTTPMethod": "*",
254-
"URLPath": "*",
255-
"Version": 1,
256-
"Attributes": {
257-
"x-datadog-sampling-priority": "2"
258-
}
259-
}
260-
}
261-
```
262-
263-
### Non-proxy integration
264-
265-
If your Lambda function is triggered by API Gateway via [the non-proxy integration](https://docs.aws.amazon.com/apigateway/latest/developerguide/getting-started-lambda-non-proxy-integration.html), then you have to [set up a mapping template](https://aws.amazon.com/premiumsupport/knowledge-center/custom-headers-api-gateway-lambda/), which passes the Datadog trace context from the incoming HTTP request headers to the Lambda function via the `event` object.
266-
267-
If your Lambda function is deployed by the Serverless Framework, such a mapping template gets created by default.
268-
269-
## Log and Trace Correlations
270-
271-
By default, the Datadog trace id gets automatically injected into the logs for correlation, if using the standard python `logging` library.
272-
273-
If you use a custom logger handler to log in json, you can inject the ids using the helper function `get_correlation_ids` [manually](https://docs.datadoghq.com/tracing/connect_logs_and_traces/?tab=python#manual-trace-id-injection).
274-
275-
Set the environment variable `DD_LOGS_INJECTION` to `false` to disable this feature.
276-
277-
```python
278-
from datadog_lambda.wrapper import datadog_lambda_wrapper
279-
from ddtrace.helpers import get_correlation_ids
280-
281-
@datadog_lambda_wrapper
282-
def lambda_handler(event, context):
283-
trace_id, span_id = get_correlation_ids()
284-
logger.info({
285-
"message": "hello world",
286-
"dd": {
287-
"trace_id": trace_id,
288-
"span_id": span_id
289-
}
290-
})
291-
```
292-
293-
## Datadog Tracer (**Beta**)
294-
295-
You can now trace Lambda functions using Datadog APM's tracing libraries ([dd-trace-py](https://github.com/DataDog/dd-trace-py)).
296-
297-
1. If you are using the Lambda layer, upgrade it to at least version 15.
298-
1. If you are using the pip package `datadog-lambda-python`, upgrade it to at least version `v2.15.0`.
299-
1. Install (or update to) the latest version of [Datadog forwarder Lambda function](https://docs.datadoghq.com/integrations/amazon_web_services/?tab=allpermissions#set-up-the-datadog-lambda-function). Ensure the trace forwarding layer is attached to the forwarder, e.g., ARN for Python 2.7 `arn:aws:lambda:<AWS_REGION>:464622532012:layer:Datadog-Trace-Forwarder-Python27:4`.
300-
1. Set the environment variable `DD_TRACE_ENABLED` to true on your function.
301-
1. Instrument your function using `dd-trace`.
302-
303-
```py
304-
from datadog_lambda.metric import lambda_metric
305-
from datadog_lambda.wrapper import datadog_lambda_wrapper
306-
307-
from ddtrace import tracer
308-
309-
@datadog_lambda_wrapper
310-
def hello(event, context):
311-
return {
312-
"statusCode": 200,
313-
"body": get_message()
314-
}
315-
316-
@tracer.wrap()
317-
def get_message():
318-
return "hello world"
319-
```
77+
## Enhanced Metrics
32078

321-
You can also use `dd-trace` and the X-Ray tracer together and merge the traces into one, using the environment variable `DD_MERGE_XRAY_TRACES` to true on your function.
79+
Check out the official documentation on [Datadog Lambda enhanced metrics](https://docs.datadoghq.com/integrations/amazon_lambda/?tab=python#real-time-enhanced-lambda-metrics).
32280

32381
## Opening Issues
32482

0 commit comments

Comments
 (0)
0