diff --git a/.gitignore b/.gitignore index 0ba74f5c4a271..075eb9b9d6cde 100644 --- a/.gitignore +++ b/.gitignore @@ -105,6 +105,8 @@ content/en/synthetics/cicd_integrations/circleci_orb.md content/en/serverless/libraries_integrations/plugin.md content/en/serverless/libraries_integrations/macro.md content/en/serverless/libraries_integrations/cli.md +content/en/serverless/libraries_integrations/cdk.md +content/en/serverless/libraries_integrations/extension.md # Runtime data pids diff --git a/Makefile b/Makefile index 8fa06bb7d1a2f..a616a6361a11d 100644 --- a/Makefile +++ b/Makefile @@ -113,6 +113,10 @@ clean-auto-doc: ##Remove all doc automatically created rm -f content/en/serverless/libraries_integrations/macro.md ;fi @if [ content/en/serverless/libraries_integrations/cli.md ]; then \ rm -f content/en/serverless/libraries_integrations/cli.md ;fi + @if [ content/en/serverless/libraries_integrations/extension.md ]; then \ + rm -f content/en/serverless/libraries_integrations/extension.md ;fi + @if [ content/en/serverless/libraries_integrations/cdk.md ]; then \ + rm -f content/en/serverless/libraries_integrations/cdk.md ;fi @if [ content/en/synthetics/cicd_integrations/circleci_orb.md ]; then \ rm -f content/en/synthetics/cicd_integrations/circleci_orb.md ;fi @if [ content/en/synthetics/cicd_integrations/github_actions.md ]; then \ diff --git a/config/_default/menus/menus.en.yaml b/config/_default/menus/menus.en.yaml index 68b5ca792d4b4..f84588e037ccc 100644 --- a/config/_default/menus/menus.en.yaml +++ b/config/_default/menus/menus.en.yaml @@ -837,85 +837,82 @@ main: parent: serverless_installation identifier: serverless_installation_dotnet weight: 106 + - name: Advanced Configurations + url: serverless/configuration + parent: serverless + identifier: serverless_configuration + weight: 2 - name: Libraries & Integrations url: serverless/libraries_integrations parent: serverless identifier: libraries_integrations - weight: 2 + weight: 3 - name: Datadog Lambda Extension url: serverless/libraries_integrations/extension/ parent: libraries_integrations - weight: 201 - - name: Datadog Lambda Library - url: serverless/libraries_integrations/library/ - parent: libraries_integrations - weight: 202 + weight: 301 - name: Datadog Serverless Plugin url: serverless/libraries_integrations/plugin/ parent: libraries_integrations - weight: 203 + weight: 302 - name: Datadog Serverless Macro url: serverless/libraries_integrations/macro/ parent: libraries_integrations - weight: 204 + weight: 303 - name: Datadog Serverless CLI url: serverless/libraries_integrations/cli/ parent: libraries_integrations - weight: 205 - - name: Lambda Code Signing - url: serverless/libraries_integrations/lambda_code_signing/ + weight: 304 + - name: Datadog CDK Construct + url: serverless/libraries_integrations/cdk/ parent: libraries_integrations - weight: 206 + weight: 305 + - name: Enhanced Lambda Metrics + url: serverless/enhanced_lambda_metrics + parent: serverless + weight: 4 - name: Distributed Tracing url: serverless/distributed_tracing identifier: serverless_distributed_tracing parent: serverless - weight: 3 - - name: Collect Lambda Payloads - url: serverless/distributed_tracing/collect_lambda_payloads - parent: serverless_distributed_tracing - weight: 301 + weight: 5 - name: Trace Merging (Advanced) url: serverless/distributed_tracing/serverless_trace_merging parent: serverless_distributed_tracing - weight: 302 + weight: 502 - name: Trace Propagation (Advanced) url: serverless/distributed_tracing/serverless_trace_propagation parent: serverless_distributed_tracing - weight: 303 + weight: 503 - name: Custom Metrics url: serverless/custom_metrics parent: serverless identifier: custom_metrics - weight: 4 - - name: Enhanced Lambda Metrics - url: serverless/enhanced_lambda_metrics - parent: serverless - weight: 5 + weight: 6 - name: Deployment Tracking url: serverless/deployment_tracking parent: serverless - weight: 6 + weight: 7 - name: Troubleshooting url: serverless/troubleshooting parent: serverless identifier: serverless_troubleshooting - weight: 7 + weight: 8 - name: Azure App Service Extension url: serverless/azure_app_services parent: serverless identifier: serverless_app_services - weight: 8 + weight: 9 - name: Glossary url: serverless/glossary parent: serverless identifier: serverless_glossary - weight: 9 + weight: 10 - name: Guides url: serverless/guide/ identifier: serverless_guides parent: serverless - weight: 10 + weight: 11 - name: Metrics url: metrics/ identifier: metrics_top_level diff --git a/content/en/continuous_integration/setup_tests/dotnet.md b/content/en/continuous_integration/setup_tests/dotnet.md index dd0c4ad9a54f9..55715236aa288 100644 --- a/content/en/continuous_integration/setup_tests/dotnet.md +++ b/content/en/continuous_integration/setup_tests/dotnet.md @@ -154,7 +154,7 @@ To instrument your test suite without requiring an Agent, configure the followin **Default**: `false` `DD_API_KEY` (Required) -: The [Datadog API key][6] used to upload the test results.
+: The [Datadog API key][5] used to upload the test results.
**Default**: `(empty)` Then, prefix your test command with `dd-trace ci run`. Use the `--dd-service` parameter to provide the name of the service or library. Use the `--dd-env` parameter to provide the environment where tests are being run (`local` when running tests on a developer workstation, `ci` when running them on a CI provider, etc.) For example: @@ -163,7 +163,7 @@ Then, prefix your test command with `dd-trace ci run`. Use the `--dd-service` pa dd-trace ci run --dd-service=my-dotnet-app --dd-env=ci -- dotnet test {{< /code-block >}} -Alternatively, you can provide the [Datadog API key][6] using the `--api-key` parameter, for example: +Alternatively, you can provide the [Datadog API key][5] using the `--api-key` parameter, for example: {{< code-block lang="bash" >}} dd-trace ci run --api-key --dd-service=my-dotnet-app --dd-env=ci -- dotnet test @@ -171,10 +171,10 @@ dd-trace ci run --api-key --dd-service=my-dotnet-app --dd-env=ci -- do When the `--api-key` is set, Agentless mode is automatically enabled. -Additionally, configure which [Datadog site][7] to which you want to send data. Your Datadog site is: {{< region-param key="dd_site" >}}. +Additionally, configure which [Datadog site][6] to which you want to send data. Your Datadog site is: {{< region-param key="dd_site" >}}. `DD_SITE` (Required) -: The [Datadog site][7] to upload results to.
+: The [Datadog site][6] to upload results to.
**Default**: `datadoghq.com`
**Selected site**: {{< region-param key="dd_site" code="true" >}} @@ -187,6 +187,5 @@ Additionally, configure which [Datadog site][7] to which you want to send data. [2]: /tracing/setup_overview/setup/dotnet-core/?tab=windows#configuration [3]: https://www.nuget.org/packages/Datadog.Trace [4]: /tracing/setup_overview/custom_instrumentation/dotnet/ -[5]: /continuous_integration/setup_tests/dotnet/#agentless-beta -[6]: https://app.datadoghq.com/organization-settings/api-keys -[7]: /getting_started/site/ \ No newline at end of file +[5]: https://app.datadoghq.com/organization-settings/api-keys +[6]: /getting_started/site/ diff --git a/content/en/data_security/guide/tls_deprecation_1_2.md b/content/en/data_security/guide/tls_deprecation_1_2.md index 6e1c14f3a8454..535214d3b2051 100644 --- a/content/en/data_security/guide/tls_deprecation_1_2.md +++ b/content/en/data_security/guide/tls_deprecation_1_2.md @@ -119,7 +119,7 @@ On a 64 bit .Net Framework (version 4 and above): [3]: https://caniuse.com/tls1-2 [4]: https://github.com/DataDog/dd-agent/blob/5.32.8/packaging/datadog-agent/source/setup_agent.sh [5]: https://www.openssl.org/news/changelog.html#openssl-101. -[6]: https://docs.microsoft.com/en-us/dotnet/framework/network-programming/tls#%23configuring-security-via-appcontext-switches-for-net-framework-46-or-later-versions +[6]: https://docs.microsoft.com/en-us/dotnet/framework/network-programming/tls#configuring-security-via-appcontext-switches-for-net-framework-46-or-later-versions [7]: https://docs.microsoft.com/en-us/dotnet/framework/network-programming/tls [8]: https://github.com/markekraus/BetterTls [9]: https://docs.microsoft.com/en-us/officeonlineserver/enable-tls-1-1-and-tls-1-2-support-in-office-online-server diff --git a/content/en/getting_started/tagging/unified_service_tagging.md b/content/en/getting_started/tagging/unified_service_tagging.md index dd551f2c0c469..8adb0ea76bb39 100644 --- a/content/en/getting_started/tagging/unified_service_tagging.md +++ b/content/en/getting_started/tagging/unified_service_tagging.md @@ -379,120 +379,7 @@ instances: #### AWS Lambda functions -Depending on how you build and deploy your AWS Lambda-based serverless applications, you may have several options available for applying the `env`, `service` and `version` tags to metrics, traces and logs. - -*Note*: These tags are specified through AWS resource tags instead of environment variables. - -{{< tabs >}} - -{{% tab "Serverless Framework" %}} - -Tag your Lambda functions using the [tags][1] option: - -```yaml -# serverless.yml -service: service-name -provider: - name: aws - # to apply the tags to all functions - tags: - env: "" - service: "" - version: "" - -functions: - hello: - # this function will inherit the service level tags config above - handler: handler.hello - world: - # this function will overwrite the tags - handler: handler.users - tags: - env: "" - service: "" - version: "" -``` - -If you have installed the [Datadog serverless plugin][2], the plugin automatically tags the Lambda functions with the `service` and `env` tags using the `service` and `stage` values from the serverless application definition, unless a `service` or `env` tag already exists. - -[1]: https://www.serverless.com/framework/docs/providers/aws/guide/functions#tags -[2]: https://docs.datadoghq.com/serverless/serverless_integrations/plugin -{{% /tab %}} - -{{% tab "AWS SAM" %}} - -Tag your Lambda functions using the [Tags][1] option: - -```yaml -AWSTemplateFormatVersion: '2010-09-09' -Transform: AWS::Serverless-2016-10-31 -Resources: - MyLambdaFunction: - Type: AWS::Serverless::Function - Properties: - Tags: - env: "" - service: "" - version: "" -``` - -If you have installed the [Datadog serverless macro][2], you can also specify a `service` and `env` tag as parameters: - -```yaml -Transform: - - AWS::Serverless-2016-10-31 - - Name: DatadogServerless - Parameters: - service: "" - env: "" -``` - - -[1]: https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-function.html#sam-function-tags -[2]: https://docs.datadoghq.com/serverless/serverless_integrations/macro -{{% /tab %}} - -{{% tab "AWS CDK" %}} - -Tag your app, stack, or individual Lambda functions using the [Tags class][1]. If you have installed the [Datadog serverless macro][2], you can also specify a `service` and `env` tag as parameters: - -```javascript -import * as cdk from "@aws-cdk/core"; - -class CdkStack extends cdk.Stack { - constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) { - super(scope, id, props); - this.addTransform("DatadogServerless"); - - new cdk.CfnMapping(this, "Datadog", { - mapping: { - Parameters: { - service: "", - env: "", - }, - }, - }); - } -} -``` - - -[1]: https://docs.aws.amazon.com/cdk/latest/guide/tagging.html -[2]: https://docs.datadoghq.com/serverless/serverless_integrations/macro -{{% /tab %}} - -{{% tab "Custom" %}} - -Apply the `env`, `service` and `version` tags following the AWS instructions for [Tagging Lambda Functions][1]. - - -[1]: https://docs.aws.amazon.com/lambda/latest/dg/configuration-tags.html -{{% /tab %}} - -{{< /tabs >}} - -Ensure the `DdFetchLambdaTags` option is set to `true` on the CloudFormation stack for your [Datadog Forwarder][13]. This option defaults to `true` since version `3.19.0`. - +See [how to connect your Lambda telemetry using tags][13]. ## Further Reading {{< partial name="whats-next/whats-next.html" >}} @@ -510,4 +397,4 @@ Ensure the `DdFetchLambdaTags` option is set to `true` on the CloudFormation sta [10]: /integrations/statsd/ [11]: https://www.chef.io/ [12]: https://www.ansible.com/ -[13]: /serverless/forwarder/ +[13]: /serverless/configuration/#connect-telemetry-using-tags diff --git a/content/en/mobile/_index.md b/content/en/mobile/_index.md index 5cdf2c3adb59a..aaa314cf8eed8 100644 --- a/content/en/mobile/_index.md +++ b/content/en/mobile/_index.md @@ -88,11 +88,11 @@ On the Incidents page, you can view, search and filter all incidents that you ha 1. Navigate to **Account**. 2. Click **Notifications**. 3. Select the toggle for **Enable Notifications**. (**Note**: For Android, notifications will be enabled automatically when you install the latest version of the Datadog mobile app.) -4. Next, in the Datadog web app, navigate to [Incident Notification Rules][21]. +4. Next, in the Datadog web app, navigate to [Incident Notification Rules][13]. 5. Create or edit a notification rule and under **Notify**, type your name. Two options should appear, allowing you to choose between email notifications and your mobile device. 6. Select your mobile device and click **Save**. -For more information on configuring Incident Notification Rules, see the [Incidents settings docs][22]. +For more information on configuring Incident Notification Rules, see the [Incidents settings docs][14]. ## Widgets @@ -209,7 +209,7 @@ Delete a widget by long pressing, dragging, and dropping the widget to the **Rem {{< img src="mobile/slo_widget.png" alt="Application Uptime SLO widgets displayed on Android and iOS devices" responsive="true" style="width:100%; background:none; border:none; box-shadow:none;">}} -View your [SLOs][13] from your mobile home screen with Datadog widgets. You can add any SLOs from your organization as a widget, along with a timeframe. +View your [SLOs][15] from your mobile home screen with Datadog widgets. You can add any SLOs from your organization as a widget, along with a timeframe. Timeframe options are: - 7 days @@ -319,7 +319,7 @@ Delete a widget by long pressing, dragging, and dropping the widget to the "Remo {{< img src="mobile/monitor_widget.png" alt="Configured monitor widgets displayed on Android and iOS screens" responsive="true" style="width:100%; background:none; border:none; box-shadow:none;">}} -View your [monitors][14] from your home screen with Datadog widgets. Tap any cell to open the **Monitor Search** screen in the app, with your monitors already filled in. +View your [monitors][16] from your home screen with Datadog widgets. Tap any cell to open the **Monitor Search** screen in the app, with your monitors already filled in. **Note**: If you do not have any monitor saved views, the widget shows you all monitors by default. @@ -417,7 +417,7 @@ Delete a widget by long pressing, dragging, and dropping the widget on the "Remo {{< img src="mobile/shortcut_shadow.png" style="width:100%; background:none; border:none; box-shadow:none;" alt="Quick Actions">}} -Long-press the app icon to display a quick-action sheet of your top five [Frequently Viewed By Me][15] dashboards for iOS (measured by view count and recency), or your five most opened dashboards on mobile for Android. Tap a result to open the dashboard in-app. +Long-press the app icon to display a quick-action sheet of your top five [Frequently Viewed By Me][17] dashboards for iOS (measured by view count and recency), or your five most opened dashboards on mobile for Android. Tap a result to open the dashboard in-app. ## Search from home screen @@ -439,7 +439,7 @@ With the shortcut, you can access your dashboards and monitors through three key {{< img src="mobile/siri_shadow.png" style="width:100%; background:none; border:none; box-shadow:none;" alt="Shortcuts">}} -For more information about Siri shortcuts and suggestions, read the [Apple Siri documentation][16]. +For more information about Siri shortcuts and suggestions, read the [Apple Siri documentation][18]. ## Handoff @@ -452,7 +452,7 @@ For Handoff to work, each device must: - Have Wi-Fi enabled - Have Handoff enabled -For more information about Handoff, read the [Apple Handoff documentation][17]. +For more information about Handoff, read the [Apple Handoff documentation][19]. ## Account @@ -460,7 +460,7 @@ Switch organizations or log out from the Account page. ## Troubleshooting -For help with troubleshooting, [contact Datadog support][18]. You can also send a message in the [Datadog public Slack][19] [#mobile-app][20] channel. +For help with troubleshooting, [contact Datadog support][20]. You can also send a message in the [Datadog public Slack][21] [#mobile-app][22] channel. ### Further Reading @@ -478,13 +478,13 @@ For help with troubleshooting, [contact Datadog support][18]. You can also send [10]: https://app.datadoghq.com/dashboard/lists [11]: /dashboards/ [12]: /monitors/incident_management -[13]: /dashboards/widgets/slo/#setup -[14]: /logs/explorer/saved_views/ -[15]: https://app.datadoghq.com/dashboard/lists/preset/5 -[16]: https://support.apple.com/en-us/HT209055 -[17]: https://support.apple.com/en-us/HT209455 -[18]: /help/ -[19]: https://chat.datadoghq.com/ -[20]: https://datadoghq.slack.com/archives/C0114D5EHNG -[21]: https://app.datadoghq.com/incidents/settings#Rules -[22]: /monitors/incident_management/incident_settings/#rules +[13]: https://app.datadoghq.com/incidents/settings#Rules +[14]: /monitors/incident_management/incident_settings/#rules +[15]: /dashboards/widgets/slo/#setup +[16]: /logs/explorer/saved_views/ +[17]: https://app.datadoghq.com/dashboard/lists/preset/5 +[18]: https://support.apple.com/en-us/HT209055 +[19]: https://support.apple.com/en-us/HT209455 +[20]: /help/ +[21]: https://chat.datadoghq.com/ +[22]: https://datadoghq.slack.com/archives/C0114D5EHNG diff --git a/content/en/monitors/service_level_objectives/metric.md b/content/en/monitors/service_level_objectives/metric.md index 18ff293464394..edcc2171aa198 100644 --- a/content/en/monitors/service_level_objectives/metric.md +++ b/content/en/monitors/service_level_objectives/metric.md @@ -24,7 +24,7 @@ On the [SLO status page][1], select **New SLO +**. Then select [**Metric**][2]. 1. There are two queries to define. The numerator query defines the sum of the good events, while the denominator query defines the sum of the total events. Your queries must use COUNT, RATE, or percentile-enabled DISTRIBUTION metrics to ensure the SLO calculation behaves correctly. 2. Use the `FROM` field to include or exclude specific groups using tags. -3. For percentile-enabled DISTRIBUTION metrics, you must use the `count values...` aggregator to specify a numerical threshold for the metric to count. This feature is called Threshold Queries and allows you to count the number of raw values that match a numerical threshold to produce counts for your numerator and denominator. For more information, see [Threshold Queries][4]. +3. For percentile-enabled DISTRIBUTION metrics, you must use the `count values...` aggregator to specify a numerical threshold for the metric to count. This feature is called Threshold Queries and allows you to count the number of raw values that match a numerical threshold to produce counts for your numerator and denominator. For more information, see [Threshold Queries][3]. 4. Optionally, for percentile-enabled DISTRIBUTION metrics, use the dropdown immediately to the right of the `count values..` aggregator to break your SLI out by specific groups. 5. Optionally, for COUNT or RATE metrics, use the `sum by` aggregator to break your SLI out by specific groups. @@ -44,7 +44,7 @@ By grouping these SLIs you can visualize each individual group’s status, good By default, the bar graph shows the overall counts of good and bad requests for the entire SLO. You can scope the bar graph down to an individual group's good and bad requests counts by clicking on its corresponding row in the table. In addition, you can also choose to show or hide good request counts or bad request counts by selecting the appropriate option in the legend directly below the bar graph. -**Note**: If you are using monitor-based SLIs, you can also [view monitor groups][3]. +**Note**: If you are using monitor-based SLIs, you can also [view monitor groups][4]. ### Set your SLO targets @@ -66,5 +66,5 @@ Here you can add contextual information about the purpose of the SLO, including [1]: https://app.datadoghq.com/slo [2]: https://app.datadoghq.com/slo/new/metric -[3]: /monitors/service_level_objectives/monitor/ -[4]: /metrics/distributions/#threshold-queries +[3]: /metrics/distributions/#threshold-queries +[4]: /monitors/service_level_objectives/monitor/ diff --git a/content/en/security_platform/security_signal_management/_index.md b/content/en/security_platform/security_signal_management/_index.md index 79c4868894bab..d898a70f8f596 100644 --- a/content/en/security_platform/security_signal_management/_index.md +++ b/content/en/security_platform/security_signal_management/_index.md @@ -59,11 +59,11 @@ To exclusively show Audit Logs generated by actions taken in the Cloud Security * Select the "Security Monitoring" facet under the "Event Name" facet. + + + [1]: /account_management/rbac/?tab=datadogapplication#pagetitle [2]: /account_management/rbac/permissions/#cloud-security-platform [3]: /security_platform/notification_rules/ [4]: /account_management/audit_logs/#overview [5]: /account_management/audit_logs/#retention - - - diff --git a/content/en/serverless/_index.md b/content/en/serverless/_index.md index 2f692da5ddb7d..0293aee712120 100644 --- a/content/en/serverless/_index.md +++ b/content/en/serverless/_index.md @@ -15,9 +15,12 @@ further_reading: - link: "https://www.datadoghq.com/state-of-serverless" tag: "Blog" text: "The State of Serverless" -- link: "/integrations/amazon_xray/" +- link: "/serverless/installation/" tag: "Documentation" - text: "AWS X-Ray Integration" + text: "Installing Serverless Monitoring" +- link: '/serverless/configuration/' + tag: 'Documentation' + text: 'Configure Serverless Monitoring' - link: "/integrations/amazon_lambda/" tag: "Documentation" text: "AWS Lambda Integration" @@ -48,19 +51,9 @@ further_reading: The following section outlines Datadog's solution for monitoring AWS serverless applications and Lambda functions. You can also learn more about support for monitoring [Azure serverless][2] and [Google serverless][3] applications. -## Quick start +## Explore Datadog Serverless Monitoring for AWS Lambda -If you are new to Datadog, you can get started by [signing up for a Datadog account][4], then following the instructions for [installing Datadog's Lambda Extension][5]. These steps configure your Lambda functions to send real-time metrics, logs, and traces to Datadog: - -{{< img src="serverless/aws-fully-managed-services-serverless-monitoring-hero.png" alt="Datadog Serverless Monitoring" style="width:100%;" >}} - -## Installation instructions - -For more detailed installation instructions, select the Lambda runtime below for instructions to instrument your serverless application: - -{{< partial name="serverless/getting-started-languages.html" >}} - -## Explore Datadog Serverless Monitoring +To get started, follow the [installation instructions][4] to collect metrics, traces, and logs from your serverless applications. ### Monitor your entire serverless stack in the Serverless view @@ -90,13 +83,13 @@ Easily correlate serverless code, configuration, and deployment changes with met {{< img src="serverless/serverless_deployment_tracking.jpeg" alt="Datadog Serverless Monitoring" style="width:100%;" >}} -## Other serverless clouds +## Datadog Serverless Monitoring for other serverless clouds ### Azure App Service The Datadog extension for Azure App Service provides tracing capabilities for Azure Web Apps. -Use the [Azure App Service view][6] to: +Use the [Azure App Service view][5] to: - Quickly identify apps with high latency or errors @@ -106,11 +99,11 @@ Use the [Azure App Service view][6] to: - Map the apps running on your App Service Plans to identify apps that may be impacting costs or performance -The Datadog extension for Azure App Service provides tracing capabilities for Azure Web Apps. For more information about setting up tracing in Azure, see the [Azure App Service Extension documentation][7]. +The Datadog extension for Azure App Service provides tracing capabilities for Azure Web Apps. For more information about setting up tracing in Azure, see the [Azure App Service Extension documentation][6]. ### Google Cloud Functions -Google Cloud Functions is a lightweight, event-based, asynchronous compute solution that allows you to create small, single-purpose functions. To monitor serverless functions running on Google Cloud Platform, enable the [Google Cloud Platform integration][8]. +Google Cloud Functions is a lightweight, event-based, asynchronous compute solution that allows you to create small, single-purpose functions. To monitor serverless functions running on Google Cloud Platform, enable the [Google Cloud Platform integration][7]. ## Further Reading @@ -119,8 +112,7 @@ Google Cloud Functions is a lightweight, event-based, asynchronous compute solut [1]: http://app.datadoghq.com/functions [2]: /serverless/#azure-app-service [3]: /serverless/#google-cloud-functions -[4]: https://app.datadoghq.com/signup/ -[5]: https://app.datadoghq.com/signup/agent#lambda -[6]: https://app.datadoghq.com/functions?cloud=azure&config_serverless-azure-app=true&group=service -[7]: /infrastructure/serverless/azure_app_services/#overview -[8]: /integrations/google_cloud_platform/ +[4]: /serverless/installation +[5]: https://app.datadoghq.com/functions?cloud=azure&config_serverless-azure-app=true&group=service +[6]: /infrastructure/serverless/azure_app_services/#overview +[7]: /integrations/google_cloud_platform/ diff --git a/content/en/serverless/configuration/_index.md b/content/en/serverless/configuration/_index.md new file mode 100644 index 0000000000000..fec599a7f829a --- /dev/null +++ b/content/en/serverless/configuration/_index.md @@ -0,0 +1,650 @@ +--- +title: Configure Serverless Monitoring +kind: documentation +further_reading: + - link: '/serverless/installation/' + tag: 'Documentation' + text: 'Installing Serverless Monitoring' + - link: '/serverless/troubleshooting/' + tag: 'Documentation' + text: 'Troubleshoot Serverless Monitoring' +aliases: + - /serverless/distributed_tracing/collect_lambda_payloads + - /serverless/libraries_integrations/lambda_code_signing + - /serverless/guide/forwarder_extension_migration/ + - /serverless/guide/extension_private_link/ +--- + +First, [install][1] Datadog serverless monitoring to begin collecting metrics, traces, and logs. After installation is complete, refer to the following topics to configure your installation to suit your monitoring needs. + +### Metrics +- [Collect metrics from non-Lambda resources](#collect-metrics-from-non-lambda-resources) +- [Submit custom metrics](#submit-custom-metrics) + +### Logs +- [Configure logs collection](#configure-logs-collection) +- [Collect logs from non-Lambda resources](#collect-logs-from-non-lambda-resources) +- [Connect logs and traces](#connect-logs-and-traces) + +### APM +- [Configure trace collection](#configure-trace-collection) +- [Collect the request and response payloads](#collect-the-request-and-response-payloads) +- [Collect traces from non-Lambda resources](#collect-traces-from-non-lambda-resources) +- [Propagate trace context over AWS resources](#propagate-trace-context-over-aws-resources) +- [Merge X-Ray and Datadog traces](#merge-x-ray-and-datadog-traces) +- [Link errors to your source code](#link-errors-to-your-source-code) + +### Others +- [Connect telemetry using tags](#connect-telemetry-using-tags) +- [Send telemetry over AWS PrivateLink or a proxy](#send-telemetry-over-privatelink-or-proxy) +- [Migrate to the Datadog Lambda extension](#migrate-to-the-datadog-lambda-extension) +- [Enable AWS Lambda code signing](#enable-aws-lambda-code-signing) +- [Troubleshoot](#troubleshoot) + +## Connect telemetry using tags + +Connect Datadog telemetry together through the use of reserved (`env`, `service`, and `version`) and custom tags. You can use these tags to navigate seamlessly across metrics, traces, and logs. Add the extra parameters below for the installation method you use. + +{{< tabs >}} +{{% tab "Datadog CLI" %}} + +Ensure you are using the latest version of the [Datadog CLI][1] and run the `datadog-ci lambda instrument` command with appropriate extra arguments. For example: + +```sh +datadog-ci lambda instrument \ + --env dev \ + --service web \ + --version v1.2.3 \ + --extra-tags "team:avengers,project:marvel" + # ... other required arguments, such as function names +``` + +[1]: https://docs.datadoghq.com/serverless/serverless_integrations/cli +{{% /tab %}} +{{% tab "Serverless Framework" %}} + +Ensure you are using the latest version of the [Datadog serverless plugin][1] and apply the tags using the `env`, `service`, `version` and `tags` parameters. For example: + +```yaml +custom: + datadog: + # ... other required parameters, such as the Datadog site and API key + env: dev + service: web + version: v1.2.3 + tags: "team:avengers,project:marvel" +``` + +By default, if you don't define `env` and `service`, the plugin automatically uses the `stage` and `service` values from the serverless application definition. To disable this feature, set `enableTags` to `false`. + +[1]: https://docs.datadoghq.com/serverless/serverless_integrations/plugin +{{% /tab %}} +{{% tab "AWS SAM" %}} + +Ensure you are using the latest version of the [Datadog serverless macro][1] and apply the tags using the `env`, `service`, `version` and `tags` parameters. For example: + +```yaml +Transform: + - AWS::Serverless-2016-10-31 + - Name: DatadogServerless + Parameters: + # ... other required parameters, such as the Datadog site and API key + env: dev + service: web + version: v1.2.3 + tags: "team:avengers,project:marvel" +``` + +[1]: https://docs.datadoghq.com/serverless/serverless_integrations/macro +{{% /tab %}} +{{% tab "AWS CDK" %}} + +Ensure you are using the latest version of the [Datadog serverless cdk construct][1] and apply the tags using the `env`, `service`, `version` and `tags` parameters. For example: + +```typescript +const datadog = new Datadog(this, "Datadog", { + // ... other required parameters, such as the Datadog site and API key + env: "dev", + service: "web", + version: "v1.2.3", + tags: "team:avengers,project:marvel" +}); +datadog.addLambdaFunctions([]); +``` + +[1]: https://github.com/DataDog/datadog-cdk-constructs +{{% /tab %}} +{{% tab "Others" %}} + +If you are collecting telemetry from your Lambda functions using the [Datadog Lambda extension][1], set the following environment variables on your Lambda functions. For example: +- DD_ENV: dev +- DD_SERVICE: web +- DD_VERSION: v1.2.3 +- DD_TAGS: team:avengers,project:marvel + +If you are collecting telemetry from your Lambda functions using the [Datadog Forwarder Lambda function][2], set the `env`, `service`, `version`, and additional tags as AWS resource tags on your Lambda functions. Ensure the `DdFetchLambdaTags` option is set to `true` on the CloudFormation stack for your Datadog Forwarder. This option defaults to true since version 3.19.0. + +[1]: /serverless/libraries_integrations/extension/ +[2]: /serverless/libraries_integrations/forwarder/ +{{% /tab %}} +{{< /tabs >}} + +Datadog can also enrich the collected telemetry with existing AWS resource tags defined on your Lambda functions. + +- If you are collecting telemetry from your Lambda functions using the [Datadog Lambda extension][2], enable the [Datadog AWS integration][3]. + +- If you are collecting telemetry from your Lambda functions using the [Datadog Forwarder Lambda function][4], set the `DdFetchLambdaTags` option to `true` on the CloudFormation stack for your Datadog Forwarder. This option defaults to true since version 3.19.0. + +## Collect the request and response payloads + +
This feature is currently supported for Python, Node.js, Java, and .NET.
+ +Datadog can [collect and visualize the JSON request and response payloads of AWS Lambda functions][5], giving you deeper insight into your serverless applications and helping troubleshoot Lambda function failures. + +This feature is disabled by default. Follow the instructions below for the installation method you use. + +{{< tabs >}} +{{% tab "Datadog CLI" %}} + +Ensure you are using the latest version of the [Datadog CLI][1] and run the `datadog-ci lambda instrument` command with the extra `--capture-lambda-payload` argument. For example: + +```sh +datadog-ci lambda instrument \ + --capture-lambda-payload true + # ... other required arguments, such as function names +``` + +[1]: https://docs.datadoghq.com/serverless/serverless_integrations/cli +{{% /tab %}} +{{% tab "Serverless Framework" %}} + +Ensure you are using the latest version of the [Datadog serverless plugin][1] and set the `captureLambdaPayload` to `true`. For example: + +```yaml +custom: + datadog: + # ... other required parameters, such as the Datadog site and API key + captureLambdaPayload: true +``` + +[1]: https://docs.datadoghq.com/serverless/serverless_integrations/plugin +{{% /tab %}} +{{% tab "AWS SAM" %}} + +Ensure you are using the latest version of the [Datadog serverless macro][1] and set the `captureLambdaPayload` parameter to `true`. For example: + +```yaml +Transform: + - AWS::Serverless-2016-10-31 + - Name: DatadogServerless + Parameters: + # ... other required parameters, such as the Datadog site and API key + captureLambdaPayload: true +``` + +[1]: https://docs.datadoghq.com/serverless/serverless_integrations/macro +{{% /tab %}} +{{% tab "AWS CDK" %}} + +Ensure you are using the latest version of the [Datadog serverless cdk construct][1] and set the `captureLambdaPayload` parameter to `true`. For example: + +```typescript +const datadog = new Datadog(this, "Datadog", { + // ... other required parameters, such as the Datadog site and API key + captureLambdaPayload: true +}); +datadog.addLambdaFunctions([]); +``` + +[1]: https://github.com/DataDog/datadog-cdk-constructs +{{% /tab %}} +{{% tab "Others" %}} + +Set the environment variable `DD_CAPTURE_LAMBDA_PAYLOAD` to `true` on your Lambda functions. + +{{% /tab %}} +{{< /tabs >}} + +To prevent any sensitive data within request or response JSON objects from being sent to Datadog, you can scrub specific parameters. + +To do this, add a new file `datadog.yaml` in the same folder as your Lambda function code. Obfuscation of fields in the Lambda payload is then available through [the replace_tags block][6] within `apm_config` settings in `datadog.yaml`: + +```yaml +apm_config: + replace_tags: + # Replace all the occurrences of "foobar" in any tag with "REDACTED": + - name: "*" + pattern: "foobar" + repl: "REDACTED" + # Replace "auth" from request headers with an empty string + - name: "function.request.headers.auth" + pattern: "(?s).*" + repl: "" + # Replace "apiToken" from response payload with "****" + - name: "function.response.apiToken" + pattern: "(?s).*" + repl: "****" +``` + +As an alternative, you can also populate the `DD_APM_REPLACE_TAGS` environment variable on your Lambda function to obfuscate specific fields: + +```yaml +DD_APM_REPLACE_TAGS=[ + { + "name": "*", + "pattern": "foobar", + "repl": "REDACTED" + }, + { + "name": "function.request.headers.auth", + "pattern": "(?s).*", + "repl": "" + }, + { + "name": "function.response.apiToken", + "pattern": "(?s).*" + "repl": "****" + } +] +``` + +## Collect metrics from non-Lambda resources + +In addition to collecting real-time [Datadog Lambda enhanced metrics][7], Datadog can also help you collect metrics for AWS managed resources—such as [API Gateway][8], [AppSync][9], and [SQS][10]—to help you monitor your entire serverless application. The metrics are also enriched with the corresponding AWS resource tags. + +To collect these metrics, set up the [Datadog AWS integration][3]. + +## Collect logs from non-Lambda resources + +Logs generated by managed resources besides AWS Lambda functions can be valuable in helping identify the root cause of issues in your serverless applications. Datadog recommends you [collect logs][11] from the following AWS managed resources in your environment: +- APIs: API Gateway, AppSync, ALB +- Queues & Streams: SQS, SNS, Kinesis +- Data Stores: DynamoDB, S3, RDS + +## Collect traces from non-Lambda resources + +
This feature is currently supported for Python, Node.js, Java, and .NET.
+ +Datadog can infer APM spans based on the incoming Lambda events for the AWS managed resources that trigger the Lambda function. This can be help visualize the relationship between AWS managed resources and identify performance issues in your serverless applications. See [additional product details][12]. + +The following resources are currently supported: + +- API Gateway (REST API, HTTP API, and WebSocket) +- Function URLs +- SQS +- SNS (SNS messages delivered through SQS are also supported) +- Kinesis Streams (if data is a JSON string or base64 encoded JSON string) +- EventBridge (custom events, where `Details` is a JSON string) +- S3 +- DynamoDB + +To disable this feature, set `DD_TRACE_MANAGED_SERVICES` to `false`. + +## Configure logs collection + +### Filter or scrub information from logs + +To exclude the `START` and `END` logs, set the environment variable `DD_LOGS_CONFIG_PROCESSING_RULES` to `[{"type": "exclude_at_match", "name": "exclude_start_and_end_logs", "pattern": "(START|END) RequestId"}]`. Alternatively, you can add a `datadog.yaml` file in your project root directory with the following content: + +```yaml +logs_config: + processing_rules: + - type: exclude_at_match + name: exclude_start_and_end_logs + pattern: (START|END) RequestId +``` + +Datadog recommends keeping the `REPORT` logs, as they are used to populate the invocations list in the serverless function views. + +To scrub or filter other logs before sending them to Datadog, see [Advanced Log Collection][13]. + +### Disable logs collection + +Logs collection through the Datadog Lambda extension is enabled by default. + +If you want to stop collecting logs using the Datadog Forwarder Lambda function, remove the subscription filter from your own Lambda function's CloudWatch log group. + +If you want to stop collecting logs using the Datadog Lambda extension, follow the instructions below for the installation method you use: + +{{< tabs >}} +{{% tab "Serverless Framework" %}} + +```yaml +custom: + datadog: + # ... other required parameters, such as the Datadog site and API key + enableDDLogs: false +``` + +{{% /tab %}} +{{% tab "AWS SAM" %}} + +```yaml +Transform: + - AWS::Serverless-2016-10-31 + - Name: DatadogServerless + Parameters: + # ... other required parameters, such as the Datadog site and API key + enableDDLogs: false +``` + +{{% /tab %}} +{{% tab "AWS CDK" %}} + +```typescript +const datadog = new Datadog(this, "Datadog", { + // ... other required parameters, such as the Datadog site and API key + enableDatadogLogs: false +}); +datadog.addLambdaFunctions([]); +``` + +{{% /tab %}} +{{% tab "Others" %}} + +Set the environment variable `DD_SERVERLESS_LOGS_ENABLED` to `false` on your Lambda functions. + +{{% /tab %}} +{{< /tabs >}} + +## Configure trace collection + +To see what libraries and frameworks are automatically instrumented by the Datadog APM client, see [Compatibility Requirements for APM][14]. To instrument custom applications, see Datadog's APM guide for [custom instrumentation][15]. + +### Filter or scrub sensitive information from traces + +To filter traces before sending them to Datadog, see [Ignoring Unwanted Resources in APM][16]. + +To scrub trace attributes for data security, see [Configure the Datadog Agent or Tracer for Data Security][17]. + +### Disable trace collection + +Trace collection through the Datadog Lambda extension is enabled by default. If you want to stop collecting traces from your Lambda functions, follow the instructions below: + +{{< tabs >}} +{{% tab "Datadog CLI" %}} + +```sh +datadog-ci lambda instrument \ + --tracing false + # ... other required arguments, such as function names +``` +{{% /tab %}} +{{% tab "Serverless Framework" %}} + +```yaml +custom: + datadog: + # ... other required parameters, such as the Datadog site and API key + enableDDTracing: false +``` + +{{% /tab %}} +{{% tab "AWS SAM" %}} + +```yaml +Transform: + - AWS::Serverless-2016-10-31 + - Name: DatadogServerless + Parameters: + # ... other required parameters, such as the Datadog site and API key + enableDDTracing: false +``` + +{{% /tab %}} +{{% tab "AWS CDK" %}} + +```typescript +const datadog = new Datadog(this, "Datadog", { + // ... other required parameters, such as the Datadog site and API key + enableDatadogTracing: false +}); +datadog.addLambdaFunctions([]); +``` + +{{% /tab %}} +{{% tab "Others" %}} + +Set the environment variable `DD_TRACE_ENABLED` to `false` on your Lambda functions. + +{{% /tab %}} +{{< /tabs >}} + +## Connect logs and traces + +If you are using the [Lambda extension][2] to collect traces and logs, Datadog automatically adds the AWS Lambda request ID to the `aws.lambda` span under the `request_id` tag. Additionally, Lambda logs for the same request are added under the `lambda.request_id` attribute. The Datadog trace and log views are connected using the AWS Lambda request ID. + +If you are using the [Forwarder Lambda function][4] to collect traces and logs, `dd.trace_id` is automatically injected into logs (enabled by the environment variable `DD_LOGS_INJECTION`). The Datadog trace and log views are connected using the Datadog trace ID. This feature is supported for most applications using a popular runtime and logger (see the [support by runtime][18]). + +If you are using a runtime or custom logger that isn't supported, follow these steps: +- When logging in JSON, you need to obtain the Datadog trace ID using `dd-trace` and add it to your logs under the `dd.trace_id` field: + ```javascript + { + "message": "This is a log", + "dd": { + "trace_id": "4887065908816661012" + } + // ... the rest of your log + } + ``` +- When logging in plaintext, you need to: + 1. Obtain the Datadog trace ID using `dd-trace` and add it to your log. + 2. Clone the default Lambda log pipeline, which is read-only. + 3. Enable the cloned pipeline and disable the default one. + 4. Update the [Grok parser][19] rules of the cloned pipeline to parse the Datadog trace ID into the `dd.trace_id` attribute. For example, use rule `my_rule \[%{word:level}\]\s+dd.trace_id=%{word:dd.trace_id}.*` for logs that look like `[INFO] dd.trace_id=4887065908816661012 My log message`. + +## Link errors to your source code + +
This feature is supported for Go and Java.
+ +[Datadog source code integration][20] allows you to link your telemetry (such as stack traces) to the source code of your Lambda functions in GitHub. Follow the instructions below to enable the feature. **Note**: You must deploy from a local Git repository that is neither dirty nor ahead of remote. + +{{< tabs >}} +{{% tab "Datadog CLI" %}} + +Run `datadog-ci lambda instrument` with `--source-code-integration true` to automatically send Git metadata in the current local directory and add the required tags to your Lambda functions. + +**Note**: You must set environment variable `DATADOG_API_KEY` for `datadog-ci` to upload Git metadata. `DATADOG_API_KEY` is also set on your Lambda functions to send telemetry unless you also have `DATADOG_API_KEY_SECRET_ARN` defined, which takes precedence over `DATADOG_API_KEY`. + + +```sh +# ... other required environment variables, such as DATADOG_SITE + +# required, to upload git metadata +export DATADOG_API_KEY= + +# optional, DATADOG_API_KEY is used if undefined +export DATADOG_API_KEY_SECRET_ARN= + +datadog-ci lambda instrument \ + --source-code-integration true + # ... other required arguments, such as function names +``` +{{% /tab %}} +{{% tab "Serverless Framework" %}} + +With `enableSourceCodeIntegration` set to `true`, the Datadog serverless plugin automatically sends Git metadata in the current local directory and adds the required tags to your Lambda functions. + +**Note**: You must set the `apiKey` parameter for the plugin to upload Git metadata. `apiKey` is also set on your Lambda functions to send telemetry unless you also have `apiKeySecretArn` defined, which takes precedence over `apiKey`. + +```yaml +custom: + datadog: + # ... other required parameters, such as the Datadog site + apiKey: # required, to upload git metadata + apiKeySecretArn: # optional, apiKey will be used if undefined + enableSourceCodeIntegration: true # default is true +``` + +{{% /tab %}} +{{% tab "AWS CDK" %}} + +Change your initialization function as follows to pass the gitHash value to the CDK stack: + +```typescript +async function main() { + // Make sure to add @datadog/datadog-ci via your package manager + const datadogCi = require("@datadog/datadog-ci"); + const gitHash = await datadogCi.gitMetadata.uploadGitCommitHash('{Datadog_API_Key}', '') + + const app = new cdk.App(); + // Pass in the hash to the ExampleStack constructor + new ExampleStack(app, "ExampleStack", {}, gitHash); +} +``` + +In your stack constructor, add an optional `gitHash` parameter, and call `addGitCommitMetadata()`: + +```typescript +export class ExampleStack extends cdk.Stack { + constructor(scope: cdk.App, id: string, props?: cdk.StackProps, gitHash?: string) { + ... + ... + datadog.addGitCommitMetadata([], gitHash) + } +} +``` + +{{% /tab %}} +{{% tab "Others" %}} + +1. Set the environment variable `DD_TAGS="git.commit.sha:,git.repository_url="` on your Lambda functions +2. Run [datadog-ci git-metadata upload][1] in your CI pipeline to upload Git metadata +3. Optionally, [install a GitHub App][2] to display inline source code snippets + +[1]: https://github.com/DataDog/datadog-ci/tree/master/src/commands/git-metadata +[2]: https://app.datadoghq.com/account/settings#integrations/github-apps +{{% /tab %}} +{{< /tabs >}} + +## Submit custom metrics + +You can monitor your custom business logic by [submitting custom metrics][21]. + +## Send telemetry over PrivateLink or proxy + +The Datadog Lambda Extension needs access to the public internet to send data to Datadog. If your Lambda functions are deployed in a VPC without access to public internet, you can [send data over AWS PrivateLink][22] to the `datadoghq.com` [Datadog site][23], or [send data over a proxy][24] for all other sites. + +If you are using the Datadog Forwarder, follow these [instructions][25]. + +## Propagate trace context over AWS resources + +Datadog automatically injects the trace context into outgoing AWS SDK requests and extracts the trace context from the Lambda event. This enables Datadog to trace a request or transaction over distributed services. See [Serverless Trace Propagation][26]. + +## Merge X-Ray and Datadog traces + +AWS X-Ray supports tracing through certain AWS managed services such as AppSync and Step Functions, which is not supported by Datadog APM natively. You can enable the [Datadog X-Ray integration][27] and merge the X-Ray traces with the Datadog native traces. See [additional details][28]. + +## Enable AWS Lambda code signing + +[Code signing for AWS Lambda][29] helps to ensure that only trusted code is deployed from your Lambda functions to AWS. When you enable code signing on your functions, AWS validates that all of the code in your deployments is signed by a trusted source, which you define from your code signing configuration. + +If your Lambda functions are configured to use code signing, you must add Datadog's Signing Profile ARN to your function's code signing configuration before you can deploy Lambda functions using Lambda Layers published by Datadog. + +Datadog's Signing Profile ARN: + +``` +arn:aws:signer:us-east-1:464622532012:/signing-profiles/DatadogLambdaSigningProfile/9vMI9ZAGLc +``` + +## Migrate to the Datadog Lambda extension + +Datadog can collect the monitoring data from your Lambda functions either using the [Forwarder Lambda function][4] or the [Lambda extension][2]. Datadog recommends the Lambda extension for new installations. If you are unsure, see [Deciding to migrate to the Datadog Lambda extension][30]. + +To migrate, compare the [installation instructions using the Datadog Lambda Extension][1] against the [instructions using the Datadog Forwarder][31]. For your convenience, the key differences are summarized below. + +**Note**: Datadog recommends migrating your dev and staging applications first and migrating production applications one by one. + +{{< tabs >}} +{{% tab "Datadog CLI" %}} + +1. Upgrade `@datadog/datadog-ci` to the latest version +2. Update the `--layer-version` argument and set it to the latest version for your runtime. +3. Set the `--extension-version` argument to the latest extension version. The latest extension version is `{{< latest-lambda-layer-version layer="extension" >}}`. +4. Set the required environment variables `DATADOG_SITE` and `DATADOG_API_KEY_SECRET_ARN`. +5. Remove the `--forwarder` argument. +6. If you configured the Datadog AWS integration to automatically subscribe the Forwarder to Lambda log groups, disable that after you migrate _all_ the Lambda functions in that region. + +{{% /tab %}} +{{% tab "Serverless Framework" %}} + +1. Upgrade `serverless-plugin-datadog` to the latest version, which installs the Datadog Lambda Extension by default, unless you set `addExtension` to `false`. +2. Set the required parameters `site` and `apiKeySecretArn`. +3. Set the `env`, `service`, and `version` parameters if you previously set them as Lambda resource tags. The plugin will automatically set them through the Datadog reserved environment variables instead, such as `DD_ENV`, when using the extension. +4. Remove the `forwarderArn` parameter, unless you want to keep the Forwarder for collecting logs from non-Lambda resources and you have `subscribeToApiGatewayLogs`, `subscribeToHttpApiLogs`, or `subscribeToWebsocketLogs` set to `true`. +5. If you configured the Datadog AWS integration to automatically subscribe the Forwarder to Lambda log groups, disable that after you migrate _all_ the Lambda functions in that region. + +{{% /tab %}} +{{% tab "AWS SAM" %}} + +1. Update the `datadog-serverless-macro` CloudFormation stack to pick up the latest version. +2. Set the `extensionLayerVersion` parameter to the latest extension version. The latest extension version is `{{< latest-lambda-layer-version layer="extension" >}}`. +3. Set the required parameters `site` and `apiKeySecretArn`. +4. Remove the `forwarderArn` parameter. +5. If you configured the Datadog AWS integration to automatically subscribe the Forwarder to Lambda log groups, disable that after you migrate _all_ the Lambda functions in that region. + +{{% /tab %}} +{{% tab "AWS CDK" %}} + +1. Upgrade `datadog-cdk-constructs` or `datadog-cdk-constructs-v2` to the latest version. +2. Set the `extensionLayerVersion` parameter to the latest extension version. The latest extension version is `{{< latest-lambda-layer-version layer="extension" >}}`. +3. Set the required parameters `site` and `apiKeySecretArn`. +4. Set the `env`, `service`, and `version` parameters if you previously set them as Lambda resource tags. The construct will automatically set them through the Datadog reserved environment variables instead, such as `DD_ENV`, when using the extension. +5. Remove the `forwarderArn` parameter. +6. If you configured the Datadog AWS integration to automatically subscribe the Forwarder to Lambda log groups, disable that after you migrate _all_ the Lambda functions in that region. + +{{% /tab %}} +{{% tab "Others" %}} + +1. Upgrade the Datadog Lambda library layer for your runtime to the latest version. +2. Install the latest version of the Datadog Lambda extension. +3. Set the required environment variables `DD_SITE` and `DD_API_KEY_SECRET_ARN`. +3. Set the `DD_ENV`, `DD_SERVICE`, and `DD_VERSION` environment variables if you previously set them as Lambda resource tags. +4. Remove the subscription filter that streams logs from your Lambda function's log group to the Datadog Forwarder. +5. If you configured the Datadog AWS integration to automatically subscribe the Forwarder to Lambda log groups, disable that after you migrate _all_ the Lambda functions in that region. + +{{% /tab %}} +{{< /tabs >}} + +## Troubleshoot + +If you have trouble configuring your installations, set the environment variable `DD_LOG_LEVEL` to `debug` for debugging logs. For additional troubleshooting tips, see the [serverless monitoring troubleshooting guide][32]. + +## Further Reading + +{{< partial name="whats-next/whats-next.html" >}} + + + +[1]: /serverless/installation/ +[2]: /serverless/libraries_integrations/extension/ +[3]: /integrations/amazon_web_services/ +[4]: /serverless/libraries_integrations/forwarder/ +[5]: https://www.datadoghq.com/blog/troubleshoot-lambda-function-request-response-payloads/ +[6]: /tracing/setup_overview/configure_data_security/#scrub-sensitive-data-from-your-spans +[7]: /serverless/enhanced_lambda_metrics +[8]: /integrations/amazon_api_gateway/#data-collected +[9]: /integrations/amazon_appsync/#data-collected +[10]: /integrations/amazon_sqs/#data-collected +[11]: /integrations/amazon_web_services/#log-collection +[12]: https://www.datadoghq.com/blog/monitor-aws-fully-managed-services-datadog-serverless-monitoring/ +[13]: /agent/logs/advanced_log_collection/ +[14]: /tracing/setup_overview/compatibility_requirements/ +[15]: /tracing/setup_overview/custom_instrumentation/ +[16]: /tracing/guide/ignoring_apm_resources/ +[17]: /tracing/setup_overview/configure_data_security/ +[18]: /tracing/connect_logs_and_traces/ +[19]: /logs/log_configuration/parsing/ +[20]: /integrations/guide/source-code-integration +[21]: /serverless/custom_metrics +[22]: /agent/guide/private-link/ +[23]: /getting_started/site/ +[24]: /agent/proxy/ +[25]: https://github.com/DataDog/datadog-serverless-functions/tree/master/aws/logs_monitoring#aws-privatelink-support +[26]: /serverless/distributed_tracing/serverless_trace_propagation/ +[27]: /integrations/amazon_xray/ +[28]: /serverless/distributed_tracing/serverless_trace_merging +[29]: https://docs.aws.amazon.com/lambda/latest/dg/configuration-codesigning.html +[30]: /serverless/guide/extension_motivation/ +[31]: /serverless/guide#install-using-the-datadog-forwarder +[32]: /serverless/guide/troubleshoot_serverless_monitoring/ diff --git a/content/en/serverless/custom_metrics/_index.md b/content/en/serverless/custom_metrics/_index.md index 3d8b713225170..643edddb13d91 100644 --- a/content/en/serverless/custom_metrics/_index.md +++ b/content/en/serverless/custom_metrics/_index.md @@ -8,9 +8,10 @@ kind: documentation There are a few different ways to submit custom metrics to Datadog from a Lambda function. - **Creating custom metrics from logs or traces**: If your Lambda functions are already sending trace or log data to Datadog, and the data you want to query is captured in an existing log or trace, you can [generate custom metrics from logs and traces](#creating-custom-metrics-from-logs-or-traces) without re-deploying or making any changes to your application code. -- **Submitting custom metrics using the Datadog Lambda Extension**: If you want to submit custom metrics directly from your Lambda function, Datadog recommends using the [Datadog Lambda Extension](#with-the-datadog-lambda-extension). [Check whether the Datadog Lambda Extension is supported][1] in your Lambda function runtime. +- **Submitting custom metrics using the Datadog Lambda extension**: If you want to submit custom metrics directly from your Lambda function, Datadog recommends using the [Datadog Lambda extension](#with-the-datadog-lambda-extension). [Check whether the Datadog Lambda extension is supported][1] in your Lambda function runtime. - **Submitting custom metrics using the Datadog Forwarder Lambda**: If you want to submit custom metrics from a runtime that is not yet supported by the Datadog Lambda Extension, you can use the [Datadog Forwarder Lambda](#with-the-datadog-forwarder). -- **(Deprecated) Submitting custom metrics from CloudWatch logs**: The method to submit custom metrics by printing a log formatted as `MONITORING|||||#` has been [deprecated](#deprecated-cloudwatch-logs), and you should migrate to one of the solutions above. +- **(Deprecated) Submitting custom metrics using the Datadog Lambda library**: The Datadog Lambda library for Python, Node.js and Go support sending custom metrics synchronously from the runtime to Datadog by blocking the invocation when `DD_FLUSH_TO_LOG` is set to `false`. Datadog recommends using the [Datadog Lambda extension](#with-the-datadog-lambda-extension) instead. +- **(Deprecated) Submitting custom metrics from CloudWatch logs**: The method to submit custom metrics by printing a log formatted as `MONITORING|||||#` has been [deprecated](#deprecated-cloudwatch-logs). Datadog recommends using the [Datadog Lambda extension](#with-the-datadog-lambda-extension) instead. - **(Not recommended) Using a third-party library**: Most third-party libraries do not submit metrics as distributions and can lead to under-counted results. ### Understanding distribution metrics @@ -57,28 +58,94 @@ Datadog recommends using the [Datadog Lambda Extension][1] to submit custom metr 1. Follow the general [serverless installation instructions][8] appropriate for your Lambda runtime. 1. If you are not interested in collecting traces from your Lambda function, set the environment variable `DD_TRACE_ENABLED` to `false`. 1. If you are not interested in collecting logs from your Lambda function, set the environment variable `DD_SERVERLESS_LOGS_ENABLED` to `false`. -1. Import and use the helper function from the Datadog Lambda Library, such as `lambda_metric` or `sendDistributionMetric`, to submit your custom metrics following the [sample code](#custom-metrics-sample-code). +1. Follow the sample code or instructions below to submit your custom metric. -If your Lambda function is running in a VPC, ensure that your function can reach Datadog API endpoints either through the public internet, [PrivateLink][9] or a [proxy][10]. +{{< programming-lang-wrapper langs="python,nodeJS,go,ruby,other" >}} +{{< programming-lang lang="python" >}} -## With the Datadog Forwarder +```python +from datadog_lambda.metric import lambda_metric -Datadog recommends using the [Datadog Forwarder Lambda][11] to submit custom metrics from Lambda runtimes that are not yet supported by the Datadog Lambda Extension. +def lambda_handler(event, context): + lambda_metric( + "coffee_house.order_value", # Metric name + 12.45, # Metric value + tags=['product:latte', 'order:online'] # Associated tags + ) +``` +{{< /programming-lang >}} +{{< programming-lang lang="nodeJS" >}} -1. Follow the general [serverless installation instructions][8] to configure your Lambda function, install the Datadog Lambda Library and the Datadog Forwarder Lambda function, and subscribe the Forwarder to your function's log group. -1. If you are not interested in collecting traces from your Lambda function, set the environment variable `DD_TRACE_ENABLED` to `false` on your own Lambda function. -1. If you are not interested in collecting logs from your Lambda function, set the Forwarder's CloudFormation stack parameter `DdForwardLog` to `false`. -1. Import and use the helper function from the Datadog Lambda Library, such as `lambda_metric` or `sendDistributionMetric`, to submit your custom metrics following the [sample code](#custom-metrics-sample-code). +```javascript +const { sendDistributionMetric } = require('datadog-lambda-js'); -If the Datadog Lambda Library is not available for your runtime, you can print metrics to CloudWatch logs in the expected JSON format on your own. Select the "Other" tab from the [sample code](#custom-metrics-sample-code) section. +async function myHandler(event, context) { + sendDistributionMetric( + 'coffee_house.order_value', // Metric name + 12.45, // Metric value + 'product:latte', // First tag + 'order:online' // Second tag + ); +} +``` +{{< /programming-lang >}} +{{< programming-lang lang="go" >}} -## Custom metrics sample code +```go +package main -**Note:** The arguments to the custom metrics reporting methods have the following requirements: +import ( + "github.com/aws/aws-lambda-go/lambda" + "github.com/DataDog/datadog-lambda-go" +) -- `` uniquely identifies your metric and follows the [metric naming policy][12]. -- `` MUST be a number (that is, integer or float). -- `` is optional and formatted, for example: `['owner:Datadog', 'env:demo', 'cooltag']`. +func main() { + lambda.Start(ddlambda.WrapFunction(myHandler, nil)) +} + +func myHandler(ctx context.Context, event MyEvent) (string, error) { + ddlambda.Distribution( + "coffee_house.order_value", // Metric name + 12.45, // Metric value + "product:latte", "order:online" // Associated tags + ) +} +``` + +{{< /programming-lang >}} +{{< programming-lang lang="ruby" >}} + +```ruby +require 'datadog/lambda' + +def handler(event:, context:) + # You only need to wrap your function handler (Not helper functions). + Datadog::Lambda.wrap(event, context) do + Datadog::Lambda.metric( + 'coffee_house.order_value', # Metric name + 12.45, # Metric value + "product":"latte", "order":"online" # Associated tags + ) + end +end +``` + +{{< /programming-lang >}} +{{< programming-lang lang="other" >}} + +[Install][12] the DogStatsD client for your runtime and follow the [sample code][13] to submit your custom metrics. Note: For accurate results, you must use [**distribution**](#understanding-distribution-metrics). + +{{< /programming-lang >}} +{{< /programming-lang-wrapper >}} + +## With the Datadog Forwarder + +Datadog recommends using the [Datadog Forwarder Lambda][9] to submit custom metrics from Lambda runtimes that are not supported by the Datadog Lambda Extension. + +1. Follow the general [serverless installation instructions][8] to instrument your Lambda function using the Datadog Forwarder Lambda function. +1. If you are not interested in collecting traces from your Lambda function, set the environment variable `DD_TRACE_ENABLED` to `false` on your own Lambda function. +1. If you are not interested in collecting logs from your Lambda function, set the Forwarder's CloudFormation stack parameter `DdForwardLog` to `false`. +1. Import and use the helper function from the Datadog Lambda Library, such as `lambda_metric` or `sendDistributionMetric`, to submit your custom metrics following the sample code below. {{< programming-lang-wrapper langs="python,nodeJS,go,ruby,java,other" >}} {{< programming-lang lang="python" >}} @@ -93,8 +160,7 @@ def lambda_handler(event, context): tags=['product:latte', 'order:online'] # Associated tags ) - # Submit a metric with a timestamp that is within the last 20 minutes, - # only supported when using the Forwarder Lambda + # Submit a metric with a timestamp that is within the last 20 minutes lambda_metric( "coffee_house.order_value", # Metric name 12.45, # Metric value @@ -116,8 +182,7 @@ async function myHandler(event, context) { 'order:online' // Second tag ); - // Submit a metric with a timestamp that is within the last 20 minutes, - // only supported when using the Forwarder Lambda + // Submit a metric with a timestamp that is within the last 20 minutes sendDistributionMetricWithDate( 'coffee_house.order_value', // Metric name 12.45, // Metric value @@ -125,10 +190,6 @@ async function myHandler(event, context) { 'order:online' // Second tag new Date(Date.now()), // date ); - return { - statusCode: 200, - body: 'hello, dog!' - }; } ``` {{< /programming-lang >}} @@ -143,14 +204,7 @@ import ( ) func main() { - // You only need to wrap your function handler (Not helper functions). lambda.Start(ddlambda.WrapFunction(myHandler, nil)) - /* OR with manual configuration options - lambda.Start(ddlambda.WrapFunction(myHandler, &ddlambda.Config{ - BatchInterval: time.Second * 15 - APIKey: "my-api-key", - })) - */ } func myHandler(ctx context.Context, event MyEvent) (string, error) { @@ -160,8 +214,7 @@ func myHandler(ctx context.Context, event MyEvent) (string, error) { "product:latte", "order:online" // Associated tags ) - // Submit a metric with a timestamp that is within the last 20 minutes, - // only supported when using the Forwarder Lambda + // Submit a metric with a timestamp that is within the last 20 minutes ddlambda.MetricWithTimestamp( "coffee_house.order_value", // Metric name 12.45, // Metric value @@ -186,15 +239,13 @@ def handler(event:, context:) "product":"latte", "order":"online" # Associated tags ) - # Submit a metric with a timestamp that is within the last 20 minutes, - # only supported when using the Forwarder Lambda + # Submit a metric with a timestamp that is within the last 20 minutes Datadog::Lambda.metric( 'coffee_house.order_value', # Metric name 12.45, # Metric value time: Time.now.utc, # Timestamp "product":"latte", "order":"online" # Associated tags ) - return { statusCode: 200, body: 'Hello World' } end end ``` @@ -253,7 +304,7 @@ For example: **Note**: If you are migrating to one of the recommended solutions, you'll need to start instrumenting your custom metrics under **new metric names** when submitting them to Datadog. The same metric name cannot simultaneously exist as both distribution and non-distribution metric types. -This requires the following AWS permissions in your [Datadog IAM policy][13]. +This requires the following AWS permissions in your [Datadog IAM policy][10]. | AWS Permission | Description | | ------------------------- | ----------------------------------------------------------- | @@ -273,7 +324,7 @@ Where: - `` is in seconds, not milliseconds. - `` MUST be a number (that is, integer or float). - `` is `count`, `gauge`, `histogram`, or `check`. -- `` uniquely identifies your metric and follows the [metric naming policy][12]. +- `` uniquely identifies your metric and follows the [metric naming policy][11]. - `` is optional, comma separated, and must be preceded by `#`. The tag `function_name:` is automatically applied to custom metrics. **Note**: The sum for each timestamp is used for counts and the last value for a given timestamp is used for gauges. It is not recommended to print a log statement every time you increment a metric, as this increases the time it takes to parse your logs. Continually update the value of the metric in your code, and print one log statement for that metric before the function finishes. @@ -286,8 +337,8 @@ Where: [6]: /logs/logs_to_metrics/ [7]: /tracing/generate_metrics/ [8]: /serverless/installation/ -[9]: /agent/guide/private-link/ -[10]: /agent/proxy/ -[11]: /serverless/forwarder/ -[12]: /metrics/ -[13]: /integrations/amazon_web_services/?tab=roledelegation#datadog-aws-iam-policy +[9]: /serverless/forwarder/ +[10]: /integrations/amazon_web_services/?tab=roledelegation#datadog-aws-iam-policy +[11]: /metrics/ +[12]: /developers/dogstatsd/?tab=hostagent#install-the-dogstatsd-client +[13]: /developers/dogstatsd/?tab=hostagent#instantiate-the-dogstatsd-client diff --git a/content/en/serverless/distributed_tracing/_index.md b/content/en/serverless/distributed_tracing/_index.md index 872a65df63d7c..845138be9604a 100644 --- a/content/en/serverless/distributed_tracing/_index.md +++ b/content/en/serverless/distributed_tracing/_index.md @@ -30,17 +30,17 @@ further_reading: By connecting your serverless traces to metrics, Datadog provides a context-rich picture of your application’s performance, allowing you to better troubleshoot performance issues given the distributed nature of serverless applications. -The Datadog Python, Node.js, Ruby, Go, Java, and .NET tracing libraries support distributed tracing for AWS Lambda. For most Lambda runtimes, the easiest way to add tracing to your application is with the [Datadog Lambda Library][1], which includes the Datadog tracing library as a dependency. +The Datadog Python, Node.js, Ruby, Go, Java, and .NET tracing libraries support distributed tracing for AWS Lambda. -## Choose your tracing library +## Choose your tracing solution {{< img src="serverless/serverless_tracing_installation_instructions.png" alt="Architecture diagram for tracing AWS Lambda with Datadog" >}}
New to serverless monitoring? Follow the installation steps here to get started.
-To start using Datadog APM with your serverless application, you can choose between installing Datadog's tracing libraries (`dd-trace`) or AWS X-Ray tracing libraries based on your Lambda runtime and individual requirements. To see all of your traces in Datadog in real-time in the Live Search view, you need to use Datadog's tracing libraries. +To start using Datadog APM with your serverless application, you can choose between generating traces using Datadog's tracing client (`dd-trace`) or pulling X-Ray traces from AWS. -| [Datadog APM with dd-trace][2] | [Datadog APM with AWS X-Ray][3] | +| [Datadog APM with dd-trace][1] | [Datadog APM with AWS X-Ray][2] | |---------------------------------|-------------------------------------------------------------------------| | Uses Datadog APM's integration libraries for end-to-end tracing. | Pulls traces from AWS X-Ray. | | Visualize your traces in Datadog in real-time. | Trace data available in Datadog after a few minutes. | @@ -65,92 +65,88 @@ The Datadog Lambda Library and tracing libraries for Python and Node.js support: - SNS and SQS direct integration - Kinesis - EventBridge -- Tracing dozens of additional out-of-the-box [Python][4] and [Node.js][5] libraries. +- Tracing dozens of additional out-of-the-box [Python][3] and [Node.js][4] libraries. -For Python and Node.js serverless applications, Datadog recommends you [install Datadog's tracing libraries][7]. If your application requires AWS X-Ray active tracing in AWS managed services such as AppSync or Step Functions, Datadog recommends you augment AWS X-Ray traces with Datadog APM by configuring _both_ AWS X-Ray and Datadog APM tracing libraries as described in [Serverless Trace Merging][8]. +For Python and Node.js serverless applications, Datadog recommends you [install Datadog's tracing libraries][5]. If your application requires AWS X-Ray active tracing in AWS managed services such as AppSync or Step Functions, Datadog recommends you augment AWS X-Ray traces with Datadog APM by configuring _both_ AWS X-Ray and Datadog APM tracing libraries as described in [Serverless Trace Merging][6]. -If you are already tracing your serverless functions with X-Ray and want to continue using X-Ray, you can [install the AWS X-Ray integration][3]. +If you are already tracing your serverless functions with X-Ray and want to continue using X-Ray, you can [install the AWS X-Ray integration][2]. -*Looking to trace through serverless resources not listed above? Open a feature request [here][9].* +*Looking to trace through serverless resources not listed above? [Open a feature request][7].* #### Ruby The Datadog Lambda Library and tracing libraries for Ruby support: - Automatic correlation of Lambda logs and traces with trace ID and tag injection. - Tracing HTTP requests invoking downstream Lambda functions or containers. -- Tracing dozens of additional out-of-the-box [Ruby][10] libraries. +- Tracing dozens of additional out-of-the-box [Ruby][8] libraries. -You can trace your serverless functions in Datadog with [Datadog's tracing libraries][7] or by [installing the AWS X-Ray integration][3]. If you are using [Datadog's tracing libraries][7], and need to connect Lambda function traces across AWS managed services, Datadog recommends you augment your traces by configuring _both_ AWS X-Ray and Datadog APM tracing libraries as described [here][8]. +You can trace your serverless functions in Datadog with [Datadog's tracing libraries][5] or by [installing the AWS X-Ray integration][2]. If you are using [Datadog's tracing libraries][5], and need to connect Lambda function traces across AWS managed services, Datadog recommends you augment your traces by configuring _both_ [AWS X-Ray and Datadog APM tracing libraries][6]. -*Looking to trace through serverless resources not listed above? Open a feature request [here][9].* +*Looking to trace through serverless resources not listed above? [Open a feature request][7].* #### Go The Datadog Lambda Library and tracing libraries for Go support: - Manual correlation of Lambda logs and traces with trace ID and tag injection. - Tracing HTTP requests invoking downstream Lambda functions or containers. -- Tracing dozens of additional out-of-the-box [Go][11] libraries. +- Tracing dozens of additional out-of-the-box [Go][9] libraries. -For Go serverless applications, Datadog recommends installing [Datadog's tracing libraries][7]. If your application requires AWS X-Ray active tracing in AWS managed services such as API Gateway or Step Functions, you may want to consider instead using [Datadog APM with AWS X-Ray tracing][3]. +For Go serverless applications, Datadog recommends installing [Datadog's tracing libraries][5]. If your application requires AWS X-Ray active tracing in AWS managed services such as API Gateway or Step Functions, you may want to consider instead using [Datadog APM with AWS X-Ray tracing][2]. -*Looking to trace through serverless resources not listed above? Open a feature request [here][9].* +*Looking to trace through serverless resources not listed above? [Open a feature request][7].* #### Java The Datadog Lambda Library and tracing libraries for Java support: -- Correlation of Lambda logs and traces with trace ID and tag injection. See [Connecting Java logs and traces][12] for more details. +- Correlation of Lambda logs and traces with trace ID and tag injection. See [Connecting Java logs and traces][10] for more details. - Tracing HTTP requests invoking downstream Lambda functions or containers. -- Tracing dozens of additional out-of-the-box [Java][13] libraries. +- Tracing dozens of additional out-of-the-box [Java][11] libraries. -For Java serverless applications, Datadog recommends [installing Datadog's tracing libraries][7]. If your application requires AWS X-Ray active tracing in AWS managed services such as API Gateway or Step Functions, you may want to consider instead using [Datadog APM with AWS X-Ray tracing][3]. +For Java serverless applications, Datadog recommends [installing Datadog's tracing libraries][5]. If your application requires AWS X-Ray active tracing in AWS managed services such as API Gateway or Step Functions, you may want to consider instead using [Datadog APM with AWS X-Ray tracing][2]. -*Have feedback on the Datadog's tracing libraries for Java Lambda functions? Make sure to check out discussions going on in the [#serverless][14] channel in the [Datadog Slack community][15].* +*Have feedback on the Datadog's tracing libraries for Java Lambda functions? Make sure to check out discussions going on in the [#serverless][12] channel in the [Datadog Slack community][13].* #### .NET The tracing library for .NET supports: - Tracing HTTP requests invoking downstream Lambda functions or containers. -- Tracing dozens of additional out-of-the-box [.NET][18] libraries. +- Tracing dozens of additional out-of-the-box [.NET][14] libraries. -For .NET serverless applications, Datadog recommends [installing Datadog's tracing libraries][7]. If your application requires AWS X-Ray active tracing in AWS managed services such as API Gateway or Step Functions, you may want to consider instead using [Datadog APM with AWS X-Ray tracing][3]. +For .NET serverless applications, Datadog recommends [installing Datadog's tracing libraries][5]. If your application requires AWS X-Ray active tracing in AWS managed services such as API Gateway or Step Functions, you may want to consider instead using [Datadog APM with AWS X-Ray tracing][2]. -Learn more about [tracing through .NET Azure serverless applications][16]. +Learn more about [tracing through .NET Azure serverless applications][15]. ### Hybrid environments If you have installed Datadog's tracing libraries (`dd-trace`) on both your Lambda functions and hosts, your traces automatically show you the complete picture of requests that cross infrastructure boundaries, whether it be AWS Lambda, containers, on-prem hosts, or managed services. -If `dd-trace` is installed on your hosts with the Datadog Agent, and your serverless functions are traced with AWS X-Ray, trace merging is required to see a single, connected trace across your infrastructure. Learn more about merging traces from `dd-trace` and AWS X-Ray [here][8]. +If `dd-trace` is installed on your hosts with the Datadog Agent, and your serverless functions are traced with AWS X-Ray, trace merging is required to see a single, connected trace across your infrastructure. See the [Serverless Trace Merging][6] documentation to learn more about merging traces from `dd-trace` and AWS X-Ray. -Datadog's [AWS X-Ray integration][3] only provides traces for Lambda functions. Learn more about tracing in container or host-based environments [here][17]. +Datadog's [AWS X-Ray integration][2] only provides traces for Lambda functions. See the [Datadog APM documentation][16] to learn more about tracing in container or host-based environments. ## Enable Datadog APM {{< img src="tracing/live_search/livesearchmain.mp4" alt="Live Search" video=true >}} -The Datadog Python, Node.js, Ruby, Go, Java, and .NET tracing libraries support distributed tracing for AWS Lambda. To enable tracing on your functions, follow [the installation instructions][7]. - -If you are using the Datadog Forwarder Lambda Function and you want to enable Datadog APM without enabling logging for your functions, ensure the `DdForwarderLog` environment variable is set to `false` on your Datadog Forwarder. +The Datadog Python, Node.js, Ruby, Go, Java, and .NET tracing libraries support distributed tracing for AWS Lambda. To enable tracing on your functions, follow [the installation instructions][5]. ## Further Reading {{< partial name="whats-next/whats-next.html" >}} -[1]: /serverless/datadog_lambda_library/ -[2]: /serverless/distributed_tracing#distributed-tracing-with-datadog-apm -[3]: /integrations/amazon_xray/#overview -[4]: /tracing/setup_overview/compatibility_requirements/python -[5]: /tracing/setup_overview/compatibility_requirements/nodejs -[6]: /serverless/distributed_tracing/serverless_trace_propagation -[7]: /serverless/installation/ -[8]: /serverless/distributed_tracing/serverless_trace_merging -[9]: https://docs.datadoghq.com/help/ -[10]: /tracing/setup_overview/compatibility_requirements/ruby -[11]: /tracing/setup_overview/compatibility_requirements/go -[12]: /tracing/connect_logs_and_traces/java/ -[13]: /tracing/setup_overview/compatibility_requirements/java -[14]: https://datadoghq.slack.com/archives/CFDPB83M4 -[15]: https://chat.datadoghq.com/ -[16]: /serverless/azure_app_services -[17]: /tracing/setup_overview/ -[18]: /tracing/setup_overview/compatibility_requirements/dotnet-core +[1]: /serverless/distributed_tracing#distributed-tracing-with-datadog-apm +[2]: /integrations/amazon_xray/#overview +[3]: /tracing/setup_overview/compatibility_requirements/python +[4]: /tracing/setup_overview/compatibility_requirements/nodejs +[5]: /serverless/installation/ +[6]: /serverless/distributed_tracing/serverless_trace_merging +[7]: https://docs.datadoghq.com/help/ +[8]: /tracing/setup_overview/compatibility_requirements/ruby +[9]: /tracing/setup_overview/compatibility_requirements/go +[10]: /tracing/connect_logs_and_traces/java/ +[11]: /tracing/setup_overview/compatibility_requirements/java +[12]: https://datadoghq.slack.com/archives/CFDPB83M4 +[13]: https://chat.datadoghq.com/ +[14]: /tracing/setup_overview/compatibility_requirements/dotnet-core +[15]: /serverless/azure_app_services +[16]: /tracing/setup_overview/ diff --git a/content/en/serverless/distributed_tracing/collect_lambda_payloads.md b/content/en/serverless/distributed_tracing/collect_lambda_payloads.md deleted file mode 100644 index 4690776e8f8ca..0000000000000 --- a/content/en/serverless/distributed_tracing/collect_lambda_payloads.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: Collect AWS Lambda Payloads -kind: documentation -description: 'Resolve AWS Lambda function failures faster by monitoring invocation payloads' -further_reading: - - link: 'serverless' - text: 'Serverless Monitoring with Datadog' - - link: 'https://www.datadoghq.com/blog/troubleshoot-lambda-function-request-response-payloads/' - text: 'Resolve AWS Lambda function failures faster by monitoring invocation payloads' - tag: 'Blog' ---- - -{{< img src="serverless/serverless_collect_lambda_payloads.png" alt="Collect AWS Lambda Payloads" style="width:100%;" >}} - -## Overview - -You can use Datadog to collect and visualize the JSON request and response payloads of AWS Lambda functions, giving you [deeper insight into your serverless applications and helping troubleshoot Lambda function failures][1]. - -## Configuration - -To instrument your Lambda functions for the first time, follow the [serverless installation instructions][2]. AWS Lambda payload ingestion requires [APM to be configured on your functions][3] and is available for the following Lambda runtimes: -- Python ([v49+][4]) -- Node.js ([v64+][5]) - -Set the `DD_CAPTURE_LAMBDA_PAYLOAD` environment variable to `true` on each of your functions send Lambda request and response payloads to Datadog. - -This functionality is also compatible with AWS X-Ray. Follow the steps in the [Datadog-AWS X-Ray integration][6] to enrich AWS Lambda function X-Ray segments with Datadog's Lambda Libraries. - -## Obfuscating payload contents - -To prevent any sensitive data within request or response JSON objects from being sent to Datadog (like account IDs or addresses), you can to scrub specific parameters from being sent to Datadog. - -To do this, add a new file `datadog.yaml` in the same folder as your Lambda function code. Obfuscation of fields in the Lambda payload is then available through [the replace_tags block][7] within `apm_config` settings in `datadog.yaml`: - -```yaml -apm_config: - replace_tags: - # Replace all the occurrences of "foobar" in any tag with "REDACTED": - - name: "*" - pattern: "foobar" - repl: "REDACTED" - # Remove all headers with key "auth" and replace with an empty string - - name: "function.request.headers.auth" - pattern: "(?s).*" - repl: "" - # Remove "apiToken" from any response payload, and replace with "****" - - name: "function.response.apiToken" - pattern: "(?s).*" - repl: "****" -``` - -As an alternative, you can also populate the `DD_APM_REPLACE_TAGS` environment variable on your Lambda function to obfuscate specific fields: - -```yaml -DD_APM_REPLACE_TAGS=[ - { - "name": "*", - "pattern": "foobar", - "repl": "REDACTED" - }, - { - "name": "function.request.headers.auth", - "pattern": "(?s).*", - "repl": "" - }, - { - "name": "function.response.apiToken", - "pattern": "(?s).*" - "repl": "****" - } -] -``` - -## Further Reading - -{{< partial name="whats-next/whats-next.html" >}} - -[1]: https://www.datadoghq.com/blog/troubleshoot-lambda-function-request-response-payloads -[2]: /serverless/installation -[3]: /serverless/distributed_tracing -[4]: https://github.com/DataDog/datadog-lambda-python/releases/tag/v49 -[5]: https://github.com/DataDog/datadog-lambda-js/releases/tag/v4.64.0 -[6]: https://docs.datadoghq.com/integrations/amazon_xray/?tab=nodejs#enriching-xray-segments-with-datadog-libraries -[7]: /tracing/setup_overview/configure_data_security/?tab=mongodb#replace-rules-for-tag-filtering diff --git a/content/en/serverless/distributed_tracing/serverless_trace_propagation.md b/content/en/serverless/distributed_tracing/serverless_trace_propagation.md index 7ce3cc907cee4..12175a81622e8 100644 --- a/content/en/serverless/distributed_tracing/serverless_trace_propagation.md +++ b/content/en/serverless/distributed_tracing/serverless_trace_propagation.md @@ -91,7 +91,11 @@ exports.handler = async event => { ## Extracting trace context -To extract the above trace context from the consumer Lambda function, you need to define an extractor function that runs captures trace context before the execution of your Lambda function handler. To do this, configure the `DD_TRACE_EXTRACTOR` environment variable to point to the location of your extractor function (format is `.`, for example, `extractors.json` if the `json` extract method is in the `extractors.js` file). Datadog recommends you place your extractor methods all in one file, as extractors can be re-used across multiple Lambda functions. These extractors are completely customizable to fit any use case. +To extract the above trace context from the consumer Lambda function, you need to define an extractor function that captures trace context before the execution of your Lambda function handler. To do this, configure the `DD_TRACE_EXTRACTOR` environment variable to point to the location of your extractor function. The format for this is `.`. For example, `extractors.json` if the `json` extractor is in the `extractors.js` file. Datadog recommends you place your extractor methods all in one file, as extractors can be re-used across multiple Lambda functions. These extractors are completely customizable to fit any use case. + +**Notes**: +- If you are using TypeScript or a bundler like webpack, you must `import` or `require` your Node.js module where the extractors are defined. This ensures the module gets compiled and bundled into your Lambda deployment package. +- If your Node.js Lambda function runs on `arm64`, you must [define the extractor in your function code][6] instead of using the `DD_TRACE_EXTRACTOR` environment variable. ### Sample extractors @@ -126,7 +130,41 @@ exports.json = (payload) => { }; }; ``` - +{{% /tab %}} +{{% tab "Go" %}} +```go +var exampleSQSExtractor = func(ctx context.Context, ev json.RawMessage) map[string]string { + eh := events.SQSEvent{} + + headers := map[string]string{} + + if err := json.Unmarshal(ev, &eh); err != nil { + return headers + } + + // Using SQS as a trigger with a batchSize=1 so it's important we check + // for this as a single SQS message will drive the execution of the handler. + if len(eh.Records) != 1 { + return headers + } + + record := eh.Records[0] + + lowercaseHeaders := map[string]string{} + for k, v := range record.MessageAttributes { + if v.StringValue != nil { + lowercaseHeaders[strings.ToLower(k)] = *v.StringValue + } + } + + return lowercaseHeaders +} + +cfg := &ddlambda.Config{ + TraceContextExtractor: exampleSQSExtractor, +} +ddlambda.WrapFunction(handler, cfg) +``` {{% /tab %}} {{< /tabs >}} @@ -139,3 +177,4 @@ exports.json = (payload) => { [3]: /serverless/datadog_lambda_library [4]: /serverless/distributed_tracing#runtime-recommendations [5]: /tracing/setup_overview/custom_instrumentation/ +[6]: /serverless/guide/handler_wrapper/ diff --git a/content/en/serverless/enhanced_lambda_metrics/_index.md b/content/en/serverless/enhanced_lambda_metrics/_index.md index 2c7097fa9837e..9b2a13c0911a3 100644 --- a/content/en/serverless/enhanced_lambda_metrics/_index.md +++ b/content/en/serverless/enhanced_lambda_metrics/_index.md @@ -10,13 +10,13 @@ kind: documentation ## Overview -[Datadog Lambda library][1] and the [Datadog Lambda Extension][2] or the [Datadog Forwarder][3] together generate enhanced Lambda metrics out-of-the-box with low latency, several second granularity, and detailed metadata for cold starts and custom tags. +Datadog generates enhanced Lambda metrics from your Lambda runtime out-of-the-box with low latency, several second granularity, and detailed metadata for cold starts and custom tags. -Enhanced Lambda metrics give you a view above and beyond the default [Lambda metrics][4] enabled with the AWS Lambda integration. These metrics are distinguished by being in the `aws.lambda.enhanced.*` namespace, and are Datadog’s best practice for setting real-time monitors on your serverless application health. +Enhanced Lambda metrics give you a view above and beyond the default [Lambda metrics][1] enabled with the AWS Lambda integration. These metrics are distinguished by being in the `aws.lambda.enhanced.*` namespace, and are Datadog’s best practice for setting real-time monitors on your serverless application health. ### Real-time enhanced Lambda metrics -The following real-time enhanced Lambda metrics are available, and they are tagged with the `aws_account`, `region`, `functionname`, `cold_start`, `memorysize`, `executedversion`, `resource` and `runtime`. These metrics are [distributions][5], and you can query them using the `count`, `min`, `max`, `sum`, and `avg` aggregations. +The following real-time enhanced Lambda metrics are available, and they are tagged with the `aws_account`, `region`, `functionname`, `cold_start`, `memorysize`, `executedversion`, `resource` and `runtime`. These metrics are [distributions][2], and you can query them using the `count`, `min`, `max`, `sum`, and `avg` aggregations. `aws.lambda.enhanced.invocations` @@ -49,24 +49,17 @@ The following real-time enhanced Lambda metrics are available, and they are tagg `aws.lambda.enhanced.out_of_memory` : Measures the number of times a function runs out of memory. -**Note**: When you aren't using the [Datadog Lambda Extension][2], enhanced metrics are sent to the Datadog Forwarder via CloudWatch Logs, meaning you’ll see an increased volume of logs in CloudWatch. This may affect your AWS bill. To opt-out, set the `DD_ENHANCED_METRICS` environment variable to `false` on your AWS Lambda functions. - ## Enable enhanced Lambda metrics {{< img src="serverless/serverless_custom_metrics.png" alt="Collecting Enhanced Metrics from AWS Lambda" >}} -Follow the [installation instructions][6] to set up instrumentation of your serverless applications, and the enhanced Lambda metrics are enabled by default. - -**Note**: To enable enhanced Lambda metrics via the Datadog Forwarder without sending the logs for your functions to Datadog, set the `DD_FORWARD_LOG` environment variable to `false` on the [Datadog Forwarder][3]. +Follow the [installation instructions][3] to set up instrumentation of your serverless applications. Enhanced Lambda metrics are enabled by default. ## Viewing your dashboard -Once you've enabled Enhanced Lambda Metrics, view your [default dashboard in the Datadog app][7]. +Once you've enabled Enhanced Lambda Metrics, view your [default dashboard in the Datadog app][4]. -[1]: /serverless/datadog_lambda_library -[2]: /serverless/libraries_integrations/extension -[3]: /serverless/forwarder/ -[4]: /integrations/amazon_lambda/#metric-collection -[5]: /metrics/distributions/ -[6]: /serverless/installation/ -[7]: https://app.datadoghq.com/screen/integration/30306 +[1]: /integrations/amazon_lambda/#metric-collection +[2]: /metrics/distributions/ +[3]: /serverless/installation/ +[4]: https://app.datadoghq.com/screen/integration/aws_lambda_enhanced_metrics diff --git a/content/en/serverless/glossary/_index.md b/content/en/serverless/glossary/_index.md index c1531883502ac..8b49c74cf9f1c 100644 --- a/content/en/serverless/glossary/_index.md +++ b/content/en/serverless/glossary/_index.md @@ -65,7 +65,7 @@ AWS Lambda is the FaaS platform provided by Amazon Web Services. See the [AWS La [1]: https://docs.aws.amazon.com/lambda/index.html [2]: https://opencontainers.org/ [3]: /serverless/enhanced_lambda_metrics -[4]: /serverless/libraries_integrations/library/ +[4]: /serverless/libraries_integrations/ [5]: /logs/guide/forwarder/ [6]: /serverless/libraries_integrations/extension/ [7]: https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html diff --git a/content/en/serverless/guide/_index.md b/content/en/serverless/guide/_index.md index 44a6b8ae037ee..0a9d25b547d5a 100644 --- a/content/en/serverless/guide/_index.md +++ b/content/en/serverless/guide/_index.md @@ -3,26 +3,30 @@ title: Serverless Monitoring Guides kind: guide --- -{{< whatsnext desc="Serverless monitoring:" >}} +## Monitor your serverless applications + +{{< whatsnext desc="Best practices for monitoring your serverless applications" >}} {{< nextlink href="/serverless/guide/connect_invoking_resources" >}}Deeper visibility into resources invoking Lambda functions{{< /nextlink >}} {{< nextlink href="/serverless/guide/insights" >}}Serverless Insights{{< /nextlink >}} {{< nextlink href="/serverless/guide/serverless_tagging" >}}Serverless Tagging{{< /nextlink >}} {{< /whatsnext >}} -{{< whatsnext desc="Using the Datadog Forwarder:" >}} - {{< nextlink href="/serverless/guide/datadog_forwarder_node" >}}Installing Serverless with the Datadog Forwarder - Node.js{{< /nextlink >}} - {{< nextlink href="/serverless/guide/datadog_forwarder_python" >}}Installing Serverless with the Datadog Forwarder - Python{{< /nextlink >}} - {{< nextlink href="/serverless/guide/datadog_forwarder_java" >}}Installing Serverless with the Datadog Forwarder - Java{{< /nextlink >}} - {{< nextlink href="/serverless/guide/datadog_forwarder_go" >}}Installing Serverless with the Datadog Forwarder - Go{{< /nextlink >}} -{{< /whatsnext >}} +## Install using the Datadog Forwarder -{{< whatsnext desc="Using the Datadog Lambda Extension:" >}} +{{< whatsnext desc="Installation instructions for applications previously set up to be monitored using the Datadog Forwarder" >}} + {{< nextlink href="/serverless/guide/datadog_forwarder_node" >}}Instrumenting Node.js Serverless Applications Using the Datadog Forwarder{{< /nextlink >}} + {{< nextlink href="/serverless/guide/datadog_forwarder_python" >}}Instrumenting Python Serverless Applications Using the Datadog Forwarder{{< /nextlink >}} + {{< nextlink href="/serverless/guide/datadog_forwarder_java" >}}Instrumenting Java Serverless Applications Using the Datadog Forwarder{{< /nextlink >}} + {{< nextlink href="/serverless/guide/datadog_forwarder_go" >}}Instrumenting Go Serverless Applications Using the Datadog Forwarder{{< /nextlink >}} + {{< nextlink href="/serverless/guide/datadog_forwarder_dotnet" >}}Instrumenting .NET Serverless Applications Using the Datadog Forwarder{{< /nextlink >}} {{< nextlink href="/serverless/guide/extension_motivation" >}}Deciding to migrate to the Datadog Lambda Extension{{< /nextlink >}} - {{< nextlink href="/serverless/guide/forwarder_extension_migration" >}}Migrating from the Datadog Forwarder to the Datadog Lambda Extension{{< /nextlink >}} {{< /whatsnext >}} -{{< whatsnext desc="Troubleshooting:" >}} +## Troubleshoot your installation + +{{< whatsnext desc="Common installation issues and tips for troubleshooting" >}} {{< nextlink href="/serverless/troubleshooting" >}}Troubleshooting Serverless Monitoring{{< /nextlink >}} {{< nextlink href="/serverless/guide/serverless_tracing_and_webpack" >}}Node.js Lambda Tracing and Webpack Compatibility{{< /nextlink >}} {{< nextlink href="/serverless/guide/serverless_package_too_large" >}}Troubleshooting Serverless Package Too Large Errors{{< /nextlink >}} + {{< nextlink href="/serverless/guide/handler_wrapper" >}}Wrap Your Lambda Handler in Code{{< /nextlink >}} {{< /whatsnext >}} \ No newline at end of file diff --git a/content/en/serverless/guide/datadog_forwarder_dotnet.md b/content/en/serverless/guide/datadog_forwarder_dotnet.md new file mode 100644 index 0000000000000..7056a9ef04aad --- /dev/null +++ b/content/en/serverless/guide/datadog_forwarder_dotnet.md @@ -0,0 +1,50 @@ +--- +title: Instrumenting .NET Serverless Applications Using the Datadog Forwarder +kind: guide +--- +## Overview + +
+If you are a new user of Datadog Serverless, follow the instructions to instrument your Lambda functions using the Datadog Lambda Extension instead. If you have already set up Datadog Serverless with the Datadog Forwarder before Lambda offered out-of-the-box functionality, use this guide to maintain your instance. +
+ +## Prerequisites + +The [Datadog Forwarder Lambda function][1] is required to ingest AWS Lambda enhanced metrics, custom metrics, and logs. + +## Enable X-Ray tracing + +1. Enable [AWS X-Ray active tracing][2] for your Lambda function. +2. Install the [AWS X-Ray SDK for .NET][3]. + +## Subscribe the Datadog Forwarder to log groups + +[Subscribe][4] the Datadog Forwarder Lambda function to each of your function's log groups to send metrics, traces, and logs to Datadog. + +## What's next? + +- You can now view metrics, logs, and traces on the [Serverless Homepage][5]. +- See the sample code to [monitor custom business logic](#monitor-custom-business-logic). +- See the [troubleshooting guide][6] if you have trouble collecting the telemetry. + +## Monitor custom business logic + +If you would like to submit a [custom metric][7] using the Datadog Forwarder, see the sample code below: + +```csharp +var myMetric = new Dictionary(); +myMetric.Add("m", "coffee_house.order_value"); +myMetric.Add("v", 12.45); +myMetric.Add("e", (int)(DateTime.UtcNow - new DateTime(1970, 1, 1)).TotalSeconds); +myMetric.Add("t", new string[] {"product:latte", "order:online"}); +LambdaLogger.Log(JsonConvert.SerializeObject(myMetric)); +``` + + +[1]: /serverless/forwarder +[2]: https://docs.aws.amazon.com/xray/latest/devguide/xray-services-lambda.html +[3]: https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-dotnet.html +[4]: https://docs.datadoghq.com/logs/guide/send-aws-services-logs-with-the-datadog-lambda-function/ +[5]: https://app.datadoghq.com/functions +[6]: /serverless/guide/troubleshoot_serverless_monitoring/ +[7]: /serverless/custom_metrics diff --git a/content/en/serverless/guide/datadog_forwarder_go.md b/content/en/serverless/guide/datadog_forwarder_go.md index 42e2563669d8b..da0ae11b560cb 100644 --- a/content/en/serverless/guide/datadog_forwarder_go.md +++ b/content/en/serverless/guide/datadog_forwarder_go.md @@ -1,5 +1,5 @@ --- -title: Using the Datadog Forwarder - Go +title: Instrumenting Go Serverless Applications Using the Datadog Forwarder kind: guide --- ## Overview diff --git a/content/en/serverless/guide/datadog_forwarder_java.md b/content/en/serverless/guide/datadog_forwarder_java.md index 918b5d22108ac..30cebdaf94b29 100644 --- a/content/en/serverless/guide/datadog_forwarder_java.md +++ b/content/en/serverless/guide/datadog_forwarder_java.md @@ -1,5 +1,5 @@ --- -title: Using the Datadog Forwarder - Java +title: Instrumenting Java Serverless Applications Using the Datadog Forwarder kind: guide --- ## Overview diff --git a/content/en/serverless/guide/datadog_forwarder_node.md b/content/en/serverless/guide/datadog_forwarder_node.md index fcdec39c2e01f..2274ade719b9c 100644 --- a/content/en/serverless/guide/datadog_forwarder_node.md +++ b/content/en/serverless/guide/datadog_forwarder_node.md @@ -1,5 +1,5 @@ --- -title: Using the Datadog Forwarder - Node +title: Instrumenting Node.js Serverless Applications Using the Datadog Forwarder kind: guide --- diff --git a/content/en/serverless/guide/datadog_forwarder_python.md b/content/en/serverless/guide/datadog_forwarder_python.md index b800293dad001..ff6938117dbbf 100644 --- a/content/en/serverless/guide/datadog_forwarder_python.md +++ b/content/en/serverless/guide/datadog_forwarder_python.md @@ -1,5 +1,5 @@ --- -title: Using the Datadog Forwarder - Python +title: Instrumenting Python Serverless Applications Using the Datadog Forwarder kind: guide --- ## Overview diff --git a/content/en/serverless/guide/extension_motivation.md b/content/en/serverless/guide/extension_motivation.md index 303e8b4a456fc..3ee4bb0f5993f 100644 --- a/content/en/serverless/guide/extension_motivation.md +++ b/content/en/serverless/guide/extension_motivation.md @@ -1,6 +1,10 @@ --- title: Deciding to migrate to the Datadog Lambda extension kind: guide +further_reading: + - link: '/serverless/configuration/#migrate-to-the-datadog-lambda-extension' + tag: 'Documentation' + text: 'Migrating to the Datadog Lambda Extension' --- ## Should I migrate to the Datadog Lambda extension? @@ -15,34 +19,28 @@ There are some key differences between the Lambda extension and the Forwarder, a {{< img src="serverless/serverless_monitoring_installation_instructions.png" alt="Instrument AWS Serverless Applications" style="width:100%;">}} -The Lambda extension only supports sending Lambda function telemetry for specific runtimes. The Forwarder is required to collect and add metadata to other AWS service logs, including those from API Gateway, AppSync, and Lambda@Edge. - -| Runtime | Extension support | Forwarder support | -| ------- | ----------------- | ----------------- | -| Python | {{< X >}} | {{< X >}} | -| Node.js | {{< X >}} | {{< X >}} | -| Go | {{< X >}} | {{< X >}} | -| Java | {{< X >}} | {{< X >}} | -| .NET | {{< X >}} | | -| Ruby | | {{< X >}} | -| PHP | | | - -The Lambda extension can submit Lambda logs, Lambda traces generated by `dd-trace` (not X-Ray), real-time enhanced Lambda metrics, and custom metrics generated by Lambda functions. +Although the Lambda Extension replaces the Forwarder as the recommended way to collect telemetry from Lambda functions, the Forwarder is required to collect and add metadata to other AWS service logs — including those from API Gateway, AppSync, and Lambda@Edge. ### Advantages The Datadog Lambda Extension offers the following advantages over the Datadog Forwarder: -- **Simple to set up**: The Forwarder requires triggers to be set up for every new Lambda function. The Datadog Lambda extension can be added as a Lambda layer. Unlike with the Forwarder, configuring the Lambda extension does not require permissions to install third-party AWS CloudFormation stacks. Also, the Lambda extension sends telemetry directly to Datadog, so you do not need to manage CloudWatch Log group subscriptions for your Lambda functions. -- **Less infrastructure to manage**: The simpler configuration of the Lambda extension saves time on infrastructure management. For non-Lambda AWS integrations, the Forwarder is still required. -- **Skip CloudWatch Logs**: The Forwarder converts logs to metrics and traces, which are then sent to Datadog. The Datadog Lambda Extension sends traces, metrics, and logs directly to Datadog, enabling you to reduce the cost associated with CloudWatch Logs. +- **Skip CloudWatch Logs**: The Forwarder extracts telemetry from logs, which are then sent to Datadog. The Datadog Lambda Extension sends telemetry directly to Datadog, enabling you to reduce the cost associated with CloudWatch Logs. +- **Simple to set up**: The Datadog Lambda extension can be added as a Lambda layer and sends telemetry directly to Datadog, so you do not need to set up a subscription filter for every new Lambda function's CloudWatch log group. ### Trade-offs The extension [adds overhead to your Lambda functions][4], compared to functions that have zero instrumentation. The added overhead affects your AWS bill and Lambda concurrency, and could cause worse cold starts. The majority of the added duration **does not** affect your function's performance. Based on Datadog's latest benchmarking results, the cost overhead is always lower (or about the same when reporting data from remote regions) when using the Lambda extension versus the Forwarder. +## Migrate to the Datadog Lambda Extension + +To migrate from the the Datadog Forwarder to the Datadog Lambda Extension, see the [Serverless configuration documentation][5]. +## Further Reading + +{{< partial name="whats-next/whats-next.html" >}} [1]: /serverless/libraries_integrations/extension/ [2]: /serverless [3]: /logs/guide/forwarder/ [4]: /serverless/libraries_integrations/extension/#overhead +[5]: /serverless/configuration/#migrate-to-the-datadog-lambda-extension diff --git a/content/en/serverless/guide/forwarder_extension_migration.md b/content/en/serverless/guide/forwarder_extension_migration.md deleted file mode 100644 index 32ee63bc780b1..0000000000000 --- a/content/en/serverless/guide/forwarder_extension_migration.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: Migrating from the Datadog Forwarder to the Datadog Lambda Extension -kind: guide ---- -## Overview - - -This guide explains how to migrate from the [Datadog Forwarder][1] to the Datadog Lambda Extension. - -The [Datadog Lambda Extension][2] is a lightweight version of the Datadog Agent built to run alongside your code with minimal performance overhead. - -Datadog recommends that you set up the Extension **before** removing the Forwarder. This means that for the period during which both the Extension and Forwarder are active, all telemetry is sent twice. The alternative (removing the Forwarder before setting up the Extension) results in a period of zero visibility. Depending on your organization's particular needs, you may prefer one outcome over the other. - -## Setting up the Datadog Lambda Extension {#extension-setup} - -See the [Datadog Lambda Extension documentation][2]. - -## Removing the Datadog Forwarder - -### Prevent the Forwarder from attaching to new functions {#prevent-forwarder} - -When you deploy a new function, the Datadog Forwarder detects an unsubscribed function and automatically creates a new subscription. If you used the automatic configuration for the Forwarder, it will not automatically resubscribe to your function's log groups if the Extension is installed on that function. - -{{< tabs >}} -{{% tab "Serverless Framework" %}} - -Remove the resource name of the Forwarder from your `serverless.yml` file. - -{{% /tab %}} -{{% tab "AWS SAM" %}} - -Remove the resource name of the Forwarder from your `template.yml` file. - -{{% /tab %}} -{{% tab "AWS CDK" %}} - -Remove the resource name of the Forwarder from your CDK stack. - -{{% /tab %}} -{{% tab "Zappa" %}} - -Manually remove the subscription from the AWS console. - -{{% /tab %}} -{{% tab "Chalice" %}} - -Manually remove the subscription from the AWS console. - -{{% /tab %}} -{{% tab "Datadog CLI" %}} - -Manually remove the subscription from the AWS console. - -{{% /tab %}} -{{% tab "Container Image" %}} - -Manually remove the subscription from the AWS console. - -{{% /tab %}} -{{% tab "Custom" %}} - -Manually remove the subscription from the AWS console. - -{{% /tab %}} -{{< /tabs >}} - -For more information, see the [Datadog Forwarder documentation][1]. - -## Hybrid approach - -You may also wish to keep using the Datadog Forwarder for existing functions while using the Datadog Lambda Extension for all new functions. - -1. Ensure that the Forwarder [does not attach automatically](#prevent-forwarder) to new functions. -2. For each new function you deploy, [set up the Extension](#extension-setup) - -[1]: /logs/guide/forwarder/ -[2]: /serverless/libraries_integrations/extension/ diff --git a/content/en/serverless/guide/handler_wrapper.md b/content/en/serverless/guide/handler_wrapper.md new file mode 100644 index 0000000000000..2a6861a5b9540 --- /dev/null +++ b/content/en/serverless/guide/handler_wrapper.md @@ -0,0 +1,39 @@ +--- +title: Wrap Your Lambda Handler in Code +kind: documentation +--- + +For Python and Node.js Lambda functions, in order to instrument individual invocations, the Datadog Lambda library needs to wrap around your Lambda handler function. This is achieved by setting your function's handler to the Datadog handler function, such as `datadog_lambda.handler.handler`, and setting the environment variable `DD_LAMBDA_HANDLER` with your original handler function to be called by the Datadog handler. + +If your Lambda function configuration is incompatible with the Datadog handler redirection, you can apply the Datadog wrapper in your function code instead. + +1. Follow the **Custom** installation instructions for [Python][1] or [Node.js][2] to install the Datadog serverless monitoring. +2. Skip the step to configure the handler function. +3. Skip the step to set the environment variable `DD_LAMBDA_HANDLER`. +4. Apply the Datadog wrapper in your function code: + ```python + # for python + from datadog_lambda.wrapper import datadog_lambda_wrapper + + @datadog_lambda_wrapper + def my_lambda_handle(event, context): + # your function code + ``` + + ```js + // for node.js + const { datadog } = require("datadog-lambda-js"); + const tracer = require("dd-trace").init({ + // optional tracer options + }); + + module.exports.myHandler = datadog(myHandler, { + // my function code + }, { + // optional datadog config, e.g., custom trace context extractor + traceExtractor: () => {}, + }); + ``` + +[1]: /serverless/installation/python?tab=custom +[2]: /serverless/installation/nodejs?tab=custom diff --git a/content/en/serverless/installation/_index.md b/content/en/serverless/installation/_index.md index 1baa7a0175ab4..f09acad0e3f3e 100644 --- a/content/en/serverless/installation/_index.md +++ b/content/en/serverless/installation/_index.md @@ -4,25 +4,40 @@ kind: documentation aliases: - /serverless/installation/installing_the_library/ further_reading: - - link: 'serverless/installation/node' + - link: '/serverless/configuration/' tag: 'Documentation' - text: 'Installing Node.js Serverless Monitoring' - - link: 'serverless/installation/ruby' - tag: 'Documentation' - text: 'Installing Ruby Serverless Monitoring' + text: 'Configure Serverless Monitoring' + - link: "/integrations/amazon_lambda/" + tag: "Documentation" + text: "AWS Lambda Integration" --- ## Quick start -If you are new to Datadog, you can get started by [signing up for a Datadog account][5], then following the instructions for [installing Datadog's Lambda Extension][6]. Completing these steps will configure your Lambda functions to send real-time metrics, logs, and traces to Datadog: +If you are new to Datadog, [sign up for a Datadog account][1], then follow the Datadog Agent installation instructions for [AWS Lambda][2] to instrument your Lambda function for a quick start with Datadog. Completing the steps configures your Lambda functions to send real-time metrics, logs, and traces to Datadog. -{{< img src="serverless/aws-fully-managed-services-serverless-monitoring-hero.png" alt="Datadog Serverless Monitoring" style="width:100%;" >}} +The quick start process configures your Lambda functions on the fly. To instrument Lambda functions permanently, see the detailed installation instructions in the next section. ## Installation instructions -For more detailed installation instructions, select the Lambda runtime below for instructions to instrument your serverless application: +For the detailed installation instructions, select the Lambda runtime below: {{< partial name="serverless/getting-started-languages.html" >}} -[5]: https://app.datadoghq.com/signup/ -[6]: https://app.datadoghq.com/signup/agent#lambda +## Advanced Configurations + +After you're done with installation and you've set up telemetry collection, you can use [advanced configurations][3] to: + +- connect your metrics, traces, and logs using tags +- collect telemetry from AWS resources such as API Gateway, AppSync, and Step Functions +- capture the request and response payloads for individual Lambda invocations +- link errors of your Lambda functions to your source code +- filter or scrub sensitive information from logs or traces + +## Further Reading + +{{< partial name="whats-next/whats-next.html" >}} + +[1]: https://app.datadoghq.com/signup/ +[2]: https://app.datadoghq.com/signup/agent#lambda +[3]: /serverless/configuration/ diff --git a/content/en/serverless/installation/dotnet.md b/content/en/serverless/installation/dotnet.md index 7f4ac70e7aef1..a9846db9ec6ab 100644 --- a/content/en/serverless/installation/dotnet.md +++ b/content/en/serverless/installation/dotnet.md @@ -2,85 +2,87 @@ title: Instrumenting .NET Serverless Applications kind: documentation further_reading: - - link: '/serverless/troubleshooting/serverless_tagging/' + - link: '/serverless/configuration' tag: 'Documentation' - text: 'Tagging Serverless Applications' - - link: 'serverless/distributed_tracing/' + text: 'Configure Serverless Monitoring' + - link: '/serverless/guide/troubleshoot_serverless_monitoring' tag: 'Documentation' - text: 'Tracing Serverless Applications' + text: 'Troubleshoot Serverless Monitoring' - link: 'serverless/custom_metrics/' tag: 'Documentation' text: 'Submitting Custom Metrics from Serverless Applications' - - link: '/serverless/guide/troubleshoot_serverless_monitoring' - tag: 'Documentation' - text: 'Troubleshoot Serverless Monitoring' --- -To instrument your .NET serverless application, you must use **either** the [Datadog Lambda Extension][1] or the [Datadog Forwarder Lambda function][2]. - -If you use the Datadog Lambda Extension, you can use Datadog's native .NET APM tracer to instrument your function. If you use the Datadog Forwarder Lambda function, you can use Datadog's integration with AWS X-Ray tracing. +
The Datadog Lambda Extension only supports the `x86_64` architecture for .NET Lambda functions. If your .NET Lambda function uses the `arm64` architecture, you must instrument using the Datadog Forwarder instead.
-**Note**: The Datadog Lambda Extension only supports the `x86_64` architecture for .NET Lambda functions. If your .NET Lambda function uses the `arm64` architecture, you must use the Datadog Forwarder for instrumentation. +
If your Lambda functions are deployed in VPC without access to the public internet, you can send data either using AWS PrivateLink for the datadoghq.com Datadog site, or using a proxy for all other sites.
-## Instrumentation +## Installation -### Using the Datadog Lambda Extension - -Datadog offers many different ways to enable instrumentation for your serverless applications. Choose a method below that best suits your needs. +Datadog offers many different ways to enable instrumentation for your serverless applications. Choose a method below that best suits your needs. Datadog generally recommends using the Datadog CLI. {{< tabs >}} {{% tab "Datadog CLI" %}} The Datadog CLI modifies existing Lambda functions' configurations to enable instrumentation without requiring a new deployment. It is the quickest way to get started with Datadog's serverless monitoring. -You can also add the [instrumentation command](#instrument) to your CI/CD pipelines to enable instrumentation for all your serverless applications. Run the command _after_ your normal serverless application deployment, so that changes made by the Datadog CLI command are not overridden. +1. Install the Datadog CLI client + + ```sh + npm install -g @datadog/datadog-ci + ``` + +2. If you are new to Datadog serverless monitoring, launch the Datadog CLI in interactive mode to guide your first installation for a quick start, and you can ignore the remaining steps. To permanently install Datadog for your production applications, skip this step and follow the remaining ones to run the Datadog CLI command in your CI/CD pipelines _after_ your normal deployment. + + ```sh + datadog-ci lambda instrument -i + ``` -### Install +3. Configure the AWS credentials -Install the Datadog CLI with NPM: + The Datadog CLI requires access to the AWS Lambda service and depends on the AWS JavaScript SDK to [resolve the credentials][1]. Ensure your AWS credentials are configured using the same method you would use when invoking the AWS CLI. -```sh -npm install -g @datadog/datadog-ci -``` +4. Configure the Datadog site -### Configure credentials + Specify the [Datadog site][2] where the telemetry should be sent to. The default is `datadoghq.com`. -For a quick start, configure Datadog and [AWS credentials][1] using the [instrumentation command](#instrument). For production applications, provide credentials in a more secure manner by using environment variables. For example: + ```sh + export DATADOG_SITE="" # such as datadoghq.com, datadoghq.eu or ddog-gov.com + ``` -```bash -export DATADOG_API_KEY="" -export DATADOG_SITE="" # such as datadoghq.com, datadoghq.eu, us3.datadoghq.com or ddog-gov.com -export AWS_ACCESS_KEY_ID="" -export AWS_SECRET_ACCESS_KEY="" -``` +5. Configure the Datadog API key -### Instrument + Datadog recommends saving the Datadog API key in AWS Secrets Manager for security and easy rotation. The key needs to be stored as a plaintext string (not a JSON blob). Ensure your Lambda functions have the required `secretsmanager:GetSecretValue` IAM permission. -**Note**: Instrument your Lambda functions in a dev or staging environment first. If the instrumentation needs to be reverted, run `uninstrument` with the same arguments that was used for instrumentation. + ```sh + export DATADOG_API_KEY_SECRET_ARN="" + ``` -To instrument your Lambda functions, run the following command: + For quick testing purposes, you can also set the Datadog API key in plaintext: -```sh -datadog-ci lambda instrument -f -f -r -e -``` + ```sh + export DATADOG_API_KEY="" + ``` -To fill in the placeholders: +6. Instrument your Lambda functions -- Replace `` and `` with your Lambda function names. -- Replace `` with the AWS region name. -- Replace `` with the desired version of the Datadog Lambda Extension. The latest version is `{{< latest-lambda-layer-version layer="extension" >}}`. + **Note**: Instrument your Lambda functions in a dev or staging environment first! Should the instrumentation result be unsatisfactory, run `uninstrument` with the same arguments to revert the changes. -For example: + To instrument your Lambda functions, run the following command. -```sh -datadog-ci lambda instrument -f my-function -f another-function -r us-east-1 -e {{< latest-lambda-layer-version layer="extension" >}} -``` + ```sh + datadog-ci lambda instrument -f -f -r -v {{< latest-lambda-layer-version layer="dd-trace-dotnet" >}} -e {{< latest-lambda-layer-version layer="extension" >}} + ``` -More information and additional parameters can be found in [Datadog Serverless CLI][2]. + To fill in the placeholders: + - Replace `` and `` with your Lambda function names. Alternatively, you can use `--functions-regex` to automatically instrument multiple functions whose names match the given regular expression. + - Replace `` with the AWS region name. + Additional parameters can be found in the [CLI documentation][3]. -[1]: https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/net-dg-config-creds.html -[2]: https://docs.datadoghq.com/serverless/serverless_integrations/cli +[1]: https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/setting-credentials-node.html +[2]: https://docs.datadoghq.com/getting_started/site/ +[3]: https://docs.datadoghq.com/serverless/serverless_integrations/cli {{% /tab %}} {{% tab "Serverless Framework" %}} @@ -89,90 +91,34 @@ The [Datadog Serverless Plugin][1] automatically configures your functions to se To install and configure the Datadog Serverless Plugin, follow these steps: 1. Install the Datadog Serverless Plugin: + ```sh - npm install serverless-plugin-datadog --save-dev - ``` -2. In your `serverless.yml`, add the following: - ```yaml - plugins: - - serverless-plugin-datadog + serverless plugin install --name serverless-plugin-datadog ``` -
If you are instead deploying your Serverless Framework app by natively exporting a JSON object from a JavaScript file (for example, by using a serverless.ts file), follow the custom installation instructions.
+2. Update your `serverless.yml`: -3. In your `serverless.yml`, also add the following section: ```yaml custom: - datadog: - apiKey: # Your Datadog API Key goes here. + datadog: + site: + apiKeySecretArn: ``` - Find your Datadog API key on the [API Management page][3]. For additional settings, see the [plugin documentation][1]. + To fill in the placeholders: + - Replace `` with your [Datadog site][3] to send the telemetry to. + - Replace `` with the ARN of the AWS secret where your [Datadog API key][4] is securely stored. The key needs to be stored as a plaintext string (not a JSON blob). The `secretsmanager:GetSecretValue` permission is required. For quick testing, you can instead use `apiKey` and set the Datadog API key in plaintext. + + For more information and additional settings, see the [plugin documentation][1]. [1]: https://docs.datadoghq.com/serverless/serverless_integrations/plugin [2]: https://docs.datadoghq.com/serverless/libraries_integrations/extension -[3]: https://app.datadoghq.com/organization-settings/api-keys -{{% /tab %}} -{{% tab "AWS SAM" %}} - -1. Add the following layers and environment variables to each .NET Lambda function you wish to instrument: - - ```yml - Type: AWS::Serverless::Function - Properties: - Environment: - Variables: - DD_TRACE_ENABLED: true - DD_API_KEY: '' - CORECLR_ENABLE_PROFILING: 1 - CORECLR_PROFILER: '{846F5F1C-F9AE-4B07-969E-05C26BC060D8}' - CORECLR_PROFILER_PATH: '/opt/datadog/Datadog.Trace.ClrProfiler.Native.so' - DD_DOTNET_TRACER_HOME: '/opt/datadog' - Layers: - - arn:aws:lambda::464622532012:layer:Datadog-Extension:{{< latest-lambda-layer-version layer="extension" >}} - - arn:aws:lambda::464622532012:layer:dd-trace-dotnet:{{< latest-lambda-layer-version layer="dd-trace-dotnet" >}} - ``` - - Replace `` with your Datadog API key, found on the [API Management page][1]. - -2. Optionally add `service` and `env` tags with appropriate values to your function. - - -[1]: https://app.datadoghq.com/organization-settings/api-keys -{{% /tab %}} -{{% tab "AWS CDK" %}} - -1. Add the following layers and environment variables to each .NET Lambda function you wish to instrument: - - ```typescript - const fn = new lambda.Function(this, 'MyFunc', { - // ... - environment: { - DD_TRACE_ENABLED: true - DD_API_KEY: '' - CORECLR_ENABLE_PROFILING: 1 - CORECLR_PROFILER: '{846F5F1C-F9AE-4B07-969E-05C26BC060D8}' - CORECLR_PROFILER_PATH: '/opt/datadog/Datadog.Trace.ClrProfiler.Native.so' - DD_DOTNET_TRACER_HOME: '/opt/datadog' - } - }); - - fn.addLayers( - lambda.LayerVersion.fromLayerVersionArn(this, 'extension', 'arn:aws:lambda::464622532012:layer:Datadog-Extension:{{< latest-lambda-layer-version layer="extension" >}}'), - lambda.LayerVersion.fromLayerVersionArn(this, 'dd-trace-dotnet', 'arn:aws:lambda::464622532012:layer:dd-trace-dotnet:{{< latest-lambda-layer-version layer="dd-trace-dotnet" >}}'), - ) - ``` - - Replace `` with your Datadog API key, found on the [API Management page][1]. - -2. Optionally add `service` and `env` tags with appropriate values to your function. - - -[1]: https://app.datadoghq.com/organization-settings/api-keys +[3]: https://docs.datadoghq.com/getting_started/site/ +[4]: https://app.datadoghq.com/organization-settings/api-keys {{% /tab %}} {{% tab "Container image" %}} -1. Add the Datadog Lambda Extension to your container image by adding the following to your Dockerfile: +1. Install the Datadog Lambda Extension ```dockerfile COPY --from=public.ecr.aws/datadog/lambda-extension: /opt/extensions/ /opt/extensions @@ -180,119 +126,73 @@ To install and configure the Datadog Serverless Plugin, follow these steps: Replace `` with either a specific version number (for example, `{{< latest-lambda-layer-version layer="extension" >}}`) or with `latest`. You can see a complete list of possible tags in the [Amazon ECR repository][1]. -2. Add the Datadog .NET APM tracer to your container image and configure it with the required environment variables by adding the following to your Dockerfile: +2. Install the Datadog .NET APM client ```dockerfile RUN yum -y install tar wget gzip RUN wget https://github.com/DataDog/dd-trace-dotnet/releases/download/v/datadog-dotnet-apm-.tar.gz RUN mkdir /opt/datadog RUN tar -C /opt/datadog -xzf datadog-dotnet-apm-.tar.gz - ENV CORECLR_ENABLE_PROFILING=1 - ENV CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8} - ENV CORECLR_PROFILER_PATH=/opt/datadog/Datadog.Trace.ClrProfiler.Native.so - ENV DD_DOTNET_TRACER_HOME=/opt/datadog ``` Replace `` with the version number of `dd-trace-dotnet` you would like to use (for example, `2.3.0`). The minimum supported version is `2.3.0`. You can see the latest versions of `dd-trace-dotnet` in [GitHub][2]. -3. Set the following environment variables in AWS: - - Set `DD_TRACE_ENABLED` to `true`. - - Set `DD_API_KEY` with your Datadog API key, found on the [API Management page][3]. -4. Optionally add `service` and `env` tags with appropriate values to your function. +3. Set the required environment variables + - Set `AWS_LAMBDA_EXEC_WRAPPER` to `/opt/datadog_wrapper`. + - Set the environment variable `DD_SITE` with your [Datadog site][3] to send the telemetry to. + - Set the environment variable `DD_API_KEY_SECRET_ARN` with the ARN of the AWS secret where your [Datadog API key][4] is securely stored. The key needs to be stored as a plaintext string (not a JSON blob). The `secretsmanager:GetSecretValue` permission is required. For quick testing, you can use `DD_API_KEY` instead and set the Datadog API key in plaintext. [1]: https://gallery.ecr.aws/datadog/lambda-extension [2]: https://github.com/DataDog/dd-trace-dotnet/releases -[3]: https://app.datadoghq.com/organization-settings/api-keys +[3]: https://docs.datadoghq.com/getting_started/site/ +[4]: https://app.datadoghq.com/organization-settings/api-keys {{% /tab %}} {{% tab "Custom" %}} -1. Add the [Datadog Lambda Extension][1] layer to your Lambda function: +1. Install the Datadog Lambda Extension + + [Configure the layers][1] for your Lambda function using the ARN in the following format: `arn:aws:lambda::464622532012:layer:Datadog-Extension:{{< latest-lambda-layer-version layer="extension" >}}` - Note that only the `x86_64` version of the Datadog Lambda Extension is supported for .NET Lambda functions. If your .NET Lambda function uses the `arm64` architecture, you must use the Datadog Forwarder for instrumentation. +2. Install the Datadog .NET APM client -2. Add the dd-trace-dotnet layer to your Lambda function: + [Configure the layers][1] for your Lambda function using the ARN in the following format: `arn:aws:lambda::464622532012:layer:dd-trace-dotnet:{{< latest-lambda-layer-version layer="dd-trace-dotnet" >}}` -3. Add your [Datadog API Key][2] to the Lambda function using the environment variable `DD_API_KEY`. - -4. Configure your Lambda function with the following additional environment variables: - - ``` - DD_TRACE_ENABLED = true - CORECLR_ENABLE_PROFILING = 1 - CORECLR_PROFILER = {846F5F1C-F9AE-4B07-969E-05C26BC060D8} - CORECLR_PROFILER_PATH = /opt/datadog/Datadog.Trace.ClrProfiler.Native.so - DD_DOTNET_TRACER_HOME = /opt/datadog - ``` +3. Set the required environment variables + - Set `AWS_LAMBDA_EXEC_WRAPPER` to `/opt/datadog_wrapper`. + - Set `DD_SITE` to your [Datadog site][2] to send the telemetry to. + - Set `DD_API_KEY_SECRET_ARN` to the ARN of the AWS secret where your [Datadog API key][3] is securely stored. The key needs to be stored as a plaintext string (not a JSON blob). The `secretsmanager:GetSecretValue` permission is required. For quick testing, you can use `DD_API_KEY` instead and set the Datadog API key in plaintext. -[1]: /serverless/libraries_integrations/extension/ -[2]: https://app.datadoghq.com/organization-settings/api-keys +[1]: https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html +[2]: https://docs.datadoghq.com/getting_started/site/ +[3]: https://app.datadoghq.com/organization-settings/api-keys {{% /tab %}} {{< /tabs >}} -### Using the Datadog Forwarder - -As an alternative to the [Datadog Lambda Extension][1], you can use the [Datadog Forwarder Lambda function][2]. - -#### Install +## What's next? -1. Enable [AWS X-Ray active tracing][3] for your Lambda function. -2. Install the [AWS X-Ray SDK for .NET][4]. - -#### Subscribe - -Subscribe the Datadog Forwarder Lambda function to each of your function's log groups to send metrics, traces, and logs to Datadog. - -1. [Install the Datadog Forwarder if you haven't][2]. -2. [Subscribe the Datadog Forwarder to your function's log groups][5]. - -#### Monitor custom business logic - -If you would like to submit a custom metric using the Datadog Forwarder, see the sample code below: - -```csharp -var myMetric = new Dictionary(); -myMetric.Add("m", "coffee_house.order_value"); -myMetric.Add("v", 12.45); -myMetric.Add("e", (int)(DateTime.UtcNow - new DateTime(1970, 1, 1)).TotalSeconds); -myMetric.Add("t", new string[] {"product:latte", "order:online"}); -LambdaLogger.Log(JsonConvert.SerializeObject(myMetric)); -``` - -For more information on custom metric submission, see the [Serverless Custom Metrics documentation][6]. - -#### Tagging - -Although it's optional, Datadog recommends tagging your serverless applications with the `env`, `service`, and `version` tags following the [unified service tagging documentation][7]. - -## Collect logs from AWS serverless resources - -Serverless logs generated by managed resources besides AWS Lambda functions can be valuable in helping identify the root cause of issues in your serverless applications. Datadog recommends you forward logs from the following managed resources in your environment: - -- APIs: API Gateway, AppSync, Application Load Balancer (ALB) -- Queues and streams: SQS, SNS, Kinesis -- Data stores: DynamoDB, S3, RDS, etc. - -To collect logs from non-Lambda AWS resources, install and configure the [Datadog Forwarder][2] to subscribe to each of your managed resource CloudWatch log groups. - -## Troubleshooting - -If you have trouble collecting monitoring data after following the instructions above, see the [serverless monitoring troubleshooting guide][8]. +- You can now view metrics, logs, and traces on the [Serverless Homepage][1]. +- Submit a [custom metric][2] or [APM span][3] to monitor your business logic. +- See the [troubleshooting guide][4] if you have trouble collecting the telemetry +- See the [advanced configurations][5] to + - connect your telemetry using tags + - collect telemetry for AWS API Gateway, SQS, etc. + - capture the Lambda request and response payloads + - link errors of your Lambda functions to your source code + - filter or scrub sensitive information from logs or traces ## Further Reading {{< partial name="whats-next/whats-next.html" >}} -[1]: /serverless/libraries_integrations/extension/ -[2]: /serverless/forwarder/ -[3]: https://docs.aws.amazon.com/xray/latest/devguide/xray-services-lambda.html -[4]: https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-dotnet.html -[5]: https://docs.datadoghq.com/logs/guide/send-aws-services-logs-with-the-datadog-lambda-function/ -[6]: /serverless/custom_metrics?tab=otherruntimes -[7]: /serverless/troubleshooting/serverless_tagging/ -[8]: /serverless/guide/troubleshoot_serverless_monitoring/ + +[1]: https://app.datadoghq.com/functions +[2]: https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/ +[3]: /tracing/custom_instrumentation/dotnet/ +[4]: /serverless/guide/troubleshoot_serverless_monitoring/ +[5]: /serverless/configuration/ diff --git a/content/en/serverless/installation/go.md b/content/en/serverless/installation/go.md index ee761dec6eab5..c96d88a205e42 100644 --- a/content/en/serverless/installation/go.md +++ b/content/en/serverless/installation/go.md @@ -2,320 +2,97 @@ title: Instrumenting Go Serverless Applications kind: documentation further_reading: -- link: 'serverless/datadog_lambda_library/go' - tag: 'Documentation' - text: 'Datadog Lambda Library for Go' -- link: 'serverless/distributed_tracing/' - tag: 'Documentation' - text: 'Tracing Serverless Applications' -- link: 'serverless/custom_metrics/' - tag: 'Documentation' - text: 'Submitting Custom Metrics from Serverless Applications' -- link: '/serverless/guide/troubleshoot_serverless_monitoring' - tag: 'Documentation' - text: 'Troubleshoot Serverless Monitoring' + - link: '/serverless/configuration' + tag: 'Documentation' + text: 'Configure Serverless Monitoring' + - link: '/serverless/guide/troubleshoot_serverless_monitoring' + tag: 'Documentation' + text: 'Troubleshoot Serverless Monitoring' + - link: 'serverless/custom_metrics/' + tag: 'Documentation' + text: 'Submitting Custom Metrics from Serverless Applications' aliases: - /serverless/datadog_lambda_library/go/ --- -{{< img src="serverless/go-lambda-tracing.png" alt="Monitor Go Lambda Functions with Datadog" style="width:100%;">}} +
If your Go Lambda functions are still using runtime go1.x and you cannot migrate to the provided.al2 runtime, you must instrument using the Datadog Forwarder instead.
-## Configuration +
If your Lambda functions are deployed in a VPC without access to the public internet, you can send data either using AWS PrivateLink for the datadoghq.com Datadog site, or using a proxy for all other sites.
-If your Go Lambda functions are still using runtime `go1.x`, you must either [migrate][1] to `provided.al2` or use the [Datadog Forwarder][2] instead of the Datadog Lambda Extension. +## Installation {{< tabs >}} -{{% tab "Datadog CLI" %}} - -The Datadog CLI modifies existing Lambda functions' configurations to enable instrumentation without requiring a new deployment. It is the quickest way to get started with Datadog's serverless monitoring. +{{% tab "Serverless Framework" %}} -You can also add the [instrumentation command](#instrument) to your CI/CD pipelines to enable instrumentation for all your serverless applications. Run the command _after_ your normal serverless application deployment, so that changes made by the Datadog CLI command are not overridden. +The [Datadog Serverless Plugin][1] automatically configures your functions to send metrics, traces, and logs to Datadog through the [Datadog Lambda Extension][2]. -### Install +To install and configure the Datadog Serverless Plugin, follow these steps: -Install the Datadog CLI with NPM: +### Install the Datadog Serverless Plugin: ```sh -npm install -g @datadog/datadog-ci +serverless plugin install --name serverless-plugin-datadog ``` -### Configure credentials - -For a quick start, configure Datadog and [AWS credentials][1] using the [instrumentation command](#instrument). For production applications, provide credentials in a more secure manner by using environment variables. For example: +### Update your `serverless.yml`: -```bash -export DATADOG_API_KEY="" -export DATADOG_SITE="" # such as datadoghq.com, datadoghq.eu, us3.datadoghq.com or ddog-gov.com -export AWS_ACCESS_KEY_ID="" -export AWS_SECRET_ACCESS_KEY="" -``` - -### Instrument - -**Note**: Instrument your Lambda functions in a dev or staging environment first. If the instrumentation needs to be reverted, run `uninstrument` with the same arguments that was used for instrumentation. - -To instrument your Lambda functions, run the following command: - -```sh -datadog-ci lambda instrument -f -f -r -e +```yaml +custom: + datadog: + site: + apiKeySecretArn: ``` To fill in the placeholders: +- Replace `` with your [Datadog site][3] to send the telemetry to. +- Replace `` with the ARN of the AWS secret where your [Datadog API key][4] is securely stored. The key needs to be stored as a plaintext string (not a JSON blob). The `secretsmanager:GetSecretValue` permission is required. For quick testing, you can instead use `apiKey` and set the Datadog API key in plaintext. -- Replace `` and `` with your Lambda function names. -- Replace `` with the AWS region name. -- Replace `` with the desired version of the Datadog Lambda Extension. The latest version is `{{< latest-lambda-layer-version layer="extension" >}}`. +For more information and additional settings, see the [plugin documentation][1]. -For example: +[1]: https://docs.datadoghq.com/serverless/serverless_integrations/plugin +[2]: https://docs.datadoghq.com/serverless/libraries_integrations/extension +[3]: https://docs.datadoghq.com/getting_started/site/ +[4]: https://app.datadoghq.com/organization-settings/api-keys +{{% /tab %}} +{{% tab "Custom" %}} +### Install the Datadog Lambda Extension -```sh -datadog-ci lambda instrument -f my-function -f another-function -r us-east-1 -e {{< latest-lambda-layer-version layer="extension" >}} -``` +[Add the Lambda layer][1] of Datadog Lambda Extension to your Lambda functions, using the ARN format based on your AWS region and architecture: -More information and additional parameters can be found in the [Datadog Serverless CLI][2]. +```sh +# Use this format for x86-based Lambda deployed in AWS commercial regions +arn:aws:lambda::464622532012:layer:Datadog-Extension:{{< latest-lambda-layer-version layer="extension" >}} -### Install the Datadog Lambda library +# Use this format for arm64-based Lambda deployed in AWS commercial regions +arn:aws:lambda::464622532012:layer:Datadog-Extension-ARM:{{< latest-lambda-layer-version layer="extension" >}} -Install the [Datadog Lambda library][3] locally by running the following command: +# Use this format for x86-based Lambda deployed in AWS GovCloud regions +arn:aws-us-gov:lambda::002406178527:layer:Datadog-Extension:{{< latest-lambda-layer-version layer="extension" >}} +# Use this format for arm64-based Lambda deployed in AWS GovCloud regions +arn:aws-us-gov:lambda::002406178527:layer:Datadog-Extension-ARM:{{< latest-lambda-layer-version layer="extension" >}} ``` -go get github.com/DataDog/datadog-lambda-go -``` - -### Set up tracing -1. Set the environment variable `DD_TRACE_ENABLED` to `true`. -2. Import the required packages in the file declaring your Lambda function handler. - - ```go - package main - - import ( - "github.com/aws/aws-lambda-go/lambda" - "github.com/DataDog/datadog-lambda-go" - "gopkg.in/DataDog/dd-trace-go.v1/ddtrace/tracer" - httptrace "gopkg.in/DataDog/dd-trace-go.v1/contrib/net/http" - ) - ``` -3. Wrap your Lambda function handler using the wrapper provided by the Datadog Lambda library. - - ```go - func main() { - // Wrap your lambda handler like this - lambda.Start(ddlambda.WrapFunction(myHandler, nil)) - /* OR with manual configuration options - lambda.Start(ddlambda.WrapFunction(myHandler, &ddlambda.Config{ - BatchInterval: time.Second * 15 - APIKey: "my-api-key", - })) - */ - } - ``` -4. Use the included libraries to create additional spans, connect logs and traces, and pass trace context to other services. - ```go - func myHandler(ctx context.Context, event MyEvent) (string, error) { - // Trace an HTTP request - req, _ := http.NewRequestWithContext(ctx, "GET", "https://www.datadoghq.com", nil) - client := http.Client{} - client = *httptrace.WrapClient(&client) - client.Do(req) - - // Connect your Lambda logs and traces - currentSpan, _ := tracer.SpanFromContext(ctx) - log.Printf("my log message %v", currentSpan) - - // Create a custom span - s, _ := tracer.StartSpanFromContext(ctx, "child.span") - time.Sleep(100 * time.Millisecond) - s.Finish() - } - ``` - -[1]: https://aws.github.io/aws-sdk-go-v2/docs/getting-started/#get-your-aws-access-keys -[2]: https://docs.datadoghq.com/serverless/serverless_integrations/cli -[3]: https://github.com/DataDog/datadog-lambda-go -{{% /tab %}} -{{% tab "Serverless Framework" %}} -The [Datadog Serverless Plugin][1] automatically configures your functions to send metrics, traces, and logs to Datadog through the [Datadog Lambda Extension][2]. - -To install and configure the Datadog Serverless Plugin, follow these steps: - -1. Install the Datadog Serverless Plugin: - ```sh - npm install serverless-plugin-datadog --save-dev - ``` -2. In your `serverless.yml`, add the following: - ```yaml - plugins: - - serverless-plugin-datadog - ``` - -
If you are instead deploying your Serverless Framework app by natively exporting a JSON object from a JavaScript file (for example, by using a serverless.ts file), follow the custom installation instructions.
- -3. In your `serverless.yml`, also add the following section: - ```yaml - custom: - datadog: - apiKey: # Your Datadog API Key goes here. - ``` - Find your Datadog API key on the [API Management page][3]. For additional settings, see the [plugin documentation][1]. +Replace `` with a valid AWS region, such as `us-east-1`. -### Install the Datadog Lambda library - -Install the [Datadog Lambda library][4] locally by running the following command: - -``` -go get github.com/DataDog/datadog-lambda-go -``` +### Configure the required environment variables -### Set up tracing -1. Import the required packages in the file declaring your Lambda function handler. - - ```go - package main - - import ( - "github.com/aws/aws-lambda-go/lambda" - "github.com/DataDog/datadog-lambda-go" - "gopkg.in/DataDog/dd-trace-go.v1/ddtrace/tracer" - httptrace "gopkg.in/DataDog/dd-trace-go.v1/contrib/net/http" - ) - ``` -2. Wrap your Lambda function handler using the wrapper provided by the Datadog Lambda library. - - ```go - func main() { - // Wrap your lambda handler like this - lambda.Start(ddlambda.WrapFunction(myHandler, nil)) - /* OR with manual configuration options - lambda.Start(ddlambda.WrapFunction(myHandler, &ddlambda.Config{ - BatchInterval: time.Second * 15 - APIKey: "my-api-key", - })) - */ - } - ``` -3. Use the included libraries to create additional spans, connect logs and traces, and pass trace context to other services. - ```go - func myHandler(ctx context.Context, event MyEvent) (string, error) { - // Trace an HTTP request - req, _ := http.NewRequestWithContext(ctx, "GET", "https://www.datadoghq.com", nil) - client := http.Client{} - client = *httptrace.WrapClient(&client) - client.Do(req) - - // Connect your Lambda logs and traces - currentSpan, _ := tracer.SpanFromContext(ctx) - log.Printf("my log message %v", currentSpan) - - // Create a custom span - s, _ := tracer.StartSpanFromContext(ctx, "child.span") - time.Sleep(100 * time.Millisecond) - s.Finish() - } - ``` +- Set `DD_SITE` to your [Datadog site][2] to send the telemetry to. +- Set `DD_API_KEY_SECRET_ARN` to the ARN of the AWS secret where your [Datadog API key][3] is securely stored. The key needs to be stored as a plaintext string string (not a JSON blob). The `secretsmanager:GetSecretValue` permission is required. For quick testing, you can use `DD_API_KEY` instead and set the Datadog API key in plaintext. -[1]: https://docs.datadoghq.com/serverless/serverless_integrations/plugin -[2]: https://docs.datadoghq.com/serverless/libraries_integrations/extension +[1]: https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html +[2]: https://docs.datadoghq.com/getting_started/site/ [3]: https://app.datadoghq.com/organization-settings/api-keys -[4]: https://github.com/DataDog/datadog-lambda-go {{% /tab %}} -{{% tab "Custom" %}} -### Install the Datadog Lambda Extension - -Add the Datadog Lambda Extension layer for your Lambda function using the ARN in the following format: - -{{< site-region region="us,us3,eu" >}} -``` -// For x86 lambdas -arn:aws:lambda::464622532012:layer:Datadog-Extension: -// For arm64 lambdas -arn:aws:lambda::464622532012:layer:Datadog-Extension-ARM: -``` -{{< /site-region >}} -{{< site-region region="gov" >}} -``` -// For x86 lambdas -arn:aws-us-gov:lambda::002406178527:layer:Datadog-Extension: -// For arm64 lambdas -arn:aws-us-gov:lambda::002406178527:layer:Datadog-Extension-ARM: -``` -{{< /site-region >}} - -The latest `EXTENSION_VERSION` is {{< latest-lambda-layer-version layer="extension" >}}. +{{< /tabs >}} ### Install the Datadog Lambda library -Install the [Datadog Lambda library][1] locally by running the following command: - ``` go get github.com/DataDog/datadog-lambda-go ``` -### Set up tracing -1. Set the environment variable `DD_API_KEY` to your Datadog API key from [API Management][2]. -2. Set the environment variable `DD_TRACE_ENABLED` to `true`. -3. Import the required packages in the file declaring your Lambda function handler. - - ```go - package main - - import ( - "github.com/aws/aws-lambda-go/lambda" - "github.com/DataDog/datadog-lambda-go" - "gopkg.in/DataDog/dd-trace-go.v1/ddtrace/tracer" - httptrace "gopkg.in/DataDog/dd-trace-go.v1/contrib/net/http" - ) - ``` -4. Wrap your Lambda function handler using the wrapper provided by the Datadog Lambda library. - - ```go - func main() { - // Wrap your lambda handler like this - lambda.Start(ddlambda.WrapFunction(myHandler, nil)) - /* OR with manual configuration options - lambda.Start(ddlambda.WrapFunction(myHandler, &ddlambda.Config{ - BatchInterval: time.Second * 15 - APIKey: "my-api-key", - })) - */ - } - ``` -5. Use the included libraries to create additional spans, connect logs and traces, and pass trace context to other services. - ```go - func myHandler(ctx context.Context, event MyEvent) (string, error) { - // Trace an HTTP request - req, _ := http.NewRequestWithContext(ctx, "GET", "https://www.datadoghq.com", nil) - client := http.Client{} - client = *httptrace.WrapClient(&client) - client.Do(req) - - // Connect your Lambda logs and traces - currentSpan, _ := tracer.SpanFromContext(ctx) - log.Printf("my log message %v", currentSpan) - - // Create a custom span - s, _ := tracer.StartSpanFromContext(ctx, "child.span") - time.Sleep(100 * time.Millisecond) - s.Finish() - } - ``` -[1]: https://github.com/DataDog/datadog-lambda-go -[2]: https://app.datadoghq.com/organization-settings/api-keys -{{% /tab %}} -{{< /tabs >}} - -### Unified service tagging - -Datadog recommends tagging your serverless applications with `DD_ENV`, `DD_SERVICE`, `DD_VERSION`, and `DD_TAGS`. See the [Lambda extension documentation][3] for more details. - -## Explore - -After configuring your function following the steps above, view your metrics, logs, and traces on the [Serverless homepage][4]. - -## Monitor custom business logic - -If you would like to submit a custom metric, see the sample code below: +### Update your Lambda function code ```go package main @@ -323,14 +100,22 @@ package main import ( "github.com/aws/aws-lambda-go/lambda" "github.com/DataDog/datadog-lambda-go" + "gopkg.in/DataDog/dd-trace-go.v1/ddtrace/tracer" + httptrace "gopkg.in/DataDog/dd-trace-go.v1/contrib/net/http" ) func main() { - // Wrap your handler function + // Wrap your lambda handler lambda.Start(ddlambda.WrapFunction(myHandler, nil)) } func myHandler(ctx context.Context, event MyEvent) (string, error) { + // Trace an HTTP request + req, _ := http.NewRequestWithContext(ctx, "GET", "https://www.datadoghq.com", nil) + client := http.Client{} + client = *httptrace.WrapClient(&client) + client.Do(req) + // Submit a custom metric ddlambda.Metric( "coffee_house.order_value", // Metric name @@ -338,33 +123,28 @@ func myHandler(ctx context.Context, event MyEvent) (string, error) { "product:latte", "order:online" // Associated tags ) - req, err := http.NewRequest("GET", "http://example.com/status") - - // Add the datadog distributed tracing headers - ddlambda.AddTraceHeaders(ctx, req) - - client := http.Client{} - client.Do(req) + // Create a custom span + s, _ := tracer.StartSpanFromContext(ctx, "child.span") + time.Sleep(100 * time.Millisecond) + s.Finish() } ``` -For more information, see the [Custom Metrics documentation][5]. - -If your Lambda function is running in a VPC, follow these [instructions][6] to ensure that the extension can reach Datadog API endpoints. - - -## Troubleshooting +## What's next? -If you have trouble collecting monitoring data after following the instructions above, see the [serverless monitoring troubleshooting guide][7]. +- Congratulations! You can now view metrics, logs, and traces on the [Serverless Homepage][1]. +- See the [troubleshooting guide][2] if you have trouble collecting the telemetry +- See the [advanced configurations][3] to + - connect your telemetry using tags + - collect telemetry for AWS API Gateway, SQS, etc. + - capture the Lambda request and response payloads + - link errors of your Lambda functions to your source code + - filter or scrub sensitive information from logs or traces ## Further Reading {{< partial name="whats-next/whats-next.html" >}} -[1]: https://aws.amazon.com/blogs/compute/migrating-aws-lambda-functions-to-al2/ -[2]: /serverless/guide/datadog_forwarder_go -[3]: /serverless/libraries_integrations/extension/#tagging -[4]: https://app.datadoghq.com/functions -[5]: /serverless/custom_metrics?tab=go -[6]: /serverless/libraries_integrations/extension/#vpc -[7]: /serverless/guide/troubleshoot_serverless_monitoring/ +[1]: https://app.datadoghq.com/functions +[2]: /serverless/guide/troubleshoot_serverless_monitoring/ +[3]: /serverless/configuration/ diff --git a/content/en/serverless/installation/java.md b/content/en/serverless/installation/java.md index 2cf67c51a99a4..0ee647290eec7 100644 --- a/content/en/serverless/installation/java.md +++ b/content/en/serverless/installation/java.md @@ -2,110 +2,91 @@ title: Instrumenting Java Serverless Applications kind: documentation further_reading: - - link: 'serverless/datadog_lambda_library/java' + - link: '/serverless/configuration' tag: 'Documentation' - text: 'Datadog Lambda Library for Java' - - link: 'serverless/distributed_tracing/' + text: 'Configure Serverless Monitoring' + - link: '/serverless/guide/troubleshoot_serverless_monitoring' tag: 'Documentation' - text: 'Tracing Serverless Applications' + text: 'Troubleshoot Serverless Monitoring' - link: 'serverless/custom_metrics/' tag: 'Documentation' text: 'Submitting Custom Metrics from Serverless Applications' - - link: '/serverless/guide/troubleshoot_serverless_monitoring' - tag: 'Documentation' - text: 'Troubleshoot Serverless Monitoring' aliases: - /serverless/datadog_lambda_library/java/ --- -{{< img src="serverless/java-lambda-tracing.png" alt="Monitor Java Lambda Functions with Datadog" style="width:100%;">}} - -
-There are versions of datadog-lambda-java that import log4j <=2.14.0 as a transitive dependency. Upgrade instructions are below. -
+
To fully instrument your serverless application with distributed tracing, your Java Lambda functions must be using the Java 8 Corretto (java8.al2) or Java 11 (java11) runtimes.
-## Prerequisites +
If your Lambda functions are deployed in a VPC without access to the public internet, you can send data either using AWS PrivateLink for the datadoghq.com Datadog site, or using a proxy for all other sites.
-To fully instrument your serverless application with distributed tracing, your Java Lambda functions must be using the Java 8 Corretto (`java8.al2`) or Java 11 (`java11`) runtimes. +
If you previously set up your Lambda functions using the Datadog Forwarder, see instrumenting using the Datadog Forwarder.
-If your Java Lambda functions were previously set up using the Datadog Forwarder, see the [installation instructions][1]. +## Installation -## Configuration +Datadog offers many different ways to enable instrumentation for your serverless applications. Choose a method below that best suits your needs. Datadog generally recommends using the Datadog CLI. {{< tabs >}} {{% tab "Datadog CLI" %}} -The Datadog CLI modifies existing Lambda functions' configurations to enable instrumentation without requiring a new deployment. It is the quickest way to get started with Datadog's serverless monitoring. - -You can also add the [instrumentation command](#instrument) to your CI/CD pipelines to enable instrumentation for all your serverless applications. Run the command _after_ your normal serverless application deployment, so that changes made by the Datadog CLI command are not overridden. - -### Install -Install the Datadog CLI with NPM: +The Datadog CLI modifies existing Lambda functions' configurations to enable instrumentation without requiring a new deployment. It is the quickest way to get started with Datadog's serverless monitoring. -```sh -npm install -g @datadog/datadog-ci -``` +1. Install the Datadog CLI client -### Configure credentials + ```sh + npm install -g @datadog/datadog-ci + ``` -For a quick start, configure Datadog and [AWS credentials][1] using the following command. For production applications, consider supplying the environment variables or credentials in a more secure manner. +2. If you are new to Datadog serverless monitoring, launch the Datadog CLI in the interactive mode to guide your first installation for a quick start, and you can ignore the remaining steps. To permanently install Datadog for your production applications, skip this step and follow the remaining ones to run the Datadog CLI command in your CI/CD pipelines _after_ your normal deployment. -```bash -export DATADOG_API_KEY="" -export DATADOG_SITE="" # such as datadoghq.com, datadoghq.eu, us3.datadoghq.com or ddog-gov.com -export AWS_ACCESS_KEY_ID="" -export AWS_SECRET_ACCESS_KEY="" -``` + ```sh + datadog-ci lambda instrument -i + ``` -### Instrument +3. Configure the AWS credentials -**Note**: Instrument your Lambda functions in a dev or staging environment first. If the instrumentation needs to be reverted, run `uninstrument` with the same arguments that was used for instrumentation. + Datadog CLI requires access to the AWS Lambda service, and depends on the AWS JavaScript SDK to [resolve the credentials][1]. Ensure your AWS credentials are configured using the same method you would use when invoking the AWS CLI. -To instrument your Lambda functions, run the following command: +4. Configure the Datadog site -```sh -datadog-ci lambda instrument -f -f -r -e -``` + Specify the [Datadog site][2] where the telemetry should be sent to. The default is `datadoghq.com`. -To fill in the placeholders: + ```sh + export DATADOG_SITE="" # such as datadoghq.com, datadoghq.eu or ddog-gov.com + ``` -- Replace `` and `` with your Lambda function names. -- Replace `` with the AWS region name. -- Replace `` with the desired version of the Datadog Lambda Extension. The latest version is `{{< latest-lambda-layer-version layer="extension" >}}`. +5. Configure the Datadog API key -For example: + Datadog recommends saving the Datadog API key in AWS Secrets Manager for security and easy rotation. The key needs to be stored as a plaintext string (not a JSON blob). Ensure your Lambda functions have the required `secretsmanager:GetSecretValue` IAM permission. -```sh -datadog-ci lambda instrument -f my-function -f another-function -r us-east-1 -e {{< latest-lambda-layer-version layer="extension" >}} -``` + ```sh + export DATADOG_API_KEY_SECRET_ARN="" + ``` -More information and additional parameters can be found in the [Datadog Serverless CLI][2]. + For quick testing purposes, you can also set the Datadog API key in plaintext: -### Install the Datadog tracing library + ```sh + export DATADOG_API_KEY="" + ``` -[Configure the layers][3] for your Lambda function using the ARN in the following format: +6. Instrument your Lambda functions -``` -arn:aws:lambda::464622532012:layer:dd-trace-java: -``` + **Note**: Instrument your Lambda functions in a dev or staging environment first. If the instrumentation result is unsatisfactory, run `uninstrument` with the same arguments to revert the changes. -The latest `VERSION` is {{< latest-lambda-layer-version layer="dd-trace-java" >}}. + To instrument your Lambda functions, run the following command. -### Configure environment variables + ```sh + datadog-ci lambda instrument -f -f -r -v {{< latest-lambda-layer-version layer="dd-trace-dotnet" >}} -e {{< latest-lambda-layer-version layer="extension" >}} + ``` -Configure the following environment variables on your function: + To fill in the placeholders: + - Replace `` and `` with your Lambda function names. Alternatively, you can use `--functions-regex` to automatically instrument multiple functions whose names match the given regular expression. + - Replace `` with the AWS region name. -```yaml -DD_API_KEY: # Replace with your Datadog API key -JAVA_TOOL_OPTIONS: -javaagent:"/opt/java/lib/dd-java-agent.jar" -XX:+TieredCompilation -XX:TieredStopAtLevel=1 -DD_LOGS_INJECTION: true -DD_JMXFETCH_ENABLED: false -DD_TRACE_ENABLED: true -``` + Additional parameters can be found in the [CLI documentation][3]. -[1]: https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html -[2]: https://docs.datadoghq.com/serverless/serverless_integrations/cli -[3]: https://docs.aws.amazon.com/lambda/latest/dg/invocation-layers.html +[1]: https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/setting-credentials-node.html +[2]: https://docs.datadoghq.com/getting_started/site/ +[3]: https://docs.datadoghq.com/serverless/serverless_integrations/cli {{% /tab %}} {{% tab "Serverless Framework" %}} @@ -114,238 +95,102 @@ The [Datadog Serverless Plugin][1] automatically configures your functions to se To install and configure the Datadog Serverless Plugin, follow these steps: 1. Install the Datadog Serverless Plugin: + ```sh - npm install serverless-plugin-datadog --save-dev - ``` -2. In your `serverless.yml`, add the following: - ```yaml - plugins: - - serverless-plugin-datadog + serverless plugin install --name serverless-plugin-datadog ``` -
If you are instead deploying your Serverless Framework app by natively exporting a JSON object from a JavaScript file (for example, by using a serverless.ts file), follow the custom installation instructions.
+2. Update your `serverless.yml`: -3. In your `serverless.yml`, also add the following section: ```yaml custom: - datadog: - apiKey: # Your Datadog API Key goes here. + datadog: + site: + apiKeySecretArn: ``` - Find your Datadog API key on the [API Management page][3]. For additional settings, see the [plugin documentation][1]. + To fill in the placeholders: + - Replace `` with your [Datadog site][3] to send the telemetry to. + - Replace `` with the ARN of the AWS secret where your [Datadog API key][4] is securely stored. The key needs to be stored as a plaintext string (not a JSON blob). The `secretsmanager:GetSecretValue` permission is required. For quick testing, you can instead use `apiKey` and set the Datadog API key in plaintext. + + For more information and additional settings, see the [plugin documentation][1]. [1]: https://docs.datadoghq.com/serverless/serverless_integrations/plugin [2]: https://docs.datadoghq.com/serverless/libraries_integrations/extension -[3]: https://app.datadoghq.com/organization-settings/api-keys -{{% /tab %}} -{{% tab "Custom" %}} - -### Install the Datadog Lambda Extension - -[Configure the layers][1] for your Lambda function using the ARN in the following format: - -``` -// For x86 architecture -arn:aws:lambda::464622532012:layer:Datadog-Extension: -// For arm64 architecture -arn:aws:lambda::464622532012:layer:Datadog-Extension-ARM: -``` - -The latest `EXTENSION_VERSION` is {{< latest-lambda-layer-version layer="extension" >}}. - -### Install the Datadog tracing library - -[Configure the layers][2] for your Lambda function using the ARN in the following format: - -``` -arn:aws:lambda::464622532012:layer:dd-trace-java: -``` - -The latest `VERSION` is {{< latest-lambda-layer-version layer="dd-trace-java" >}}. - -### Configure environment variables - -Configure the following environment variables on your function: - -```yaml -DD_API_KEY: # Replace with your Datadog API key -JAVA_TOOL_OPTIONS: -javaagent:"/opt/java/lib/dd-java-agent.jar" -XX:+TieredCompilation -XX:TieredStopAtLevel=1 -DD_LOGS_INJECTION: true -DD_JMXFETCH_ENABLED: false -DD_TRACE_ENABLED: true -``` - -[1]: https://docs.aws.amazon.com/lambda/latest/dg/invocation-layers.html -[2]: https://docs.aws.amazon.com/lambda/latest/dg/invocation-layers.html +[3]: https://docs.datadoghq.com/getting_started/site/ +[4]: https://app.datadoghq.com/organization-settings/api-keys {{% /tab %}} -{{< /tabs >}} +{{% tab "Container image" %}} -### Install the Datadog Lambda library +1. Install the Datadog Lambda Extension -Install the Datadog Lambda Library locally by adding one of the following code blocks into your `pom.xml` or `build.gradle` as appropriate based on your project’s configuration. Replace `VERSION` below with the latest release (omitting the preceeding `v`): ![Maven Cental][4] -{{< tabs >}} -{{% tab "Maven" %}} + ```dockerfile + COPY --from=public.ecr.aws/datadog/lambda-extension: /opt/extensions/ /opt/extensions + ``` -Include the following dependency in your `pom.xml`: + Replace `` with either a specific version number (for example, `{{< latest-lambda-layer-version layer="extension" >}}`) or with `latest`. You can see a complete list of possible tags in the [Amazon ECR repository][1]. -```xml - - com.datadoghq - datadog-lambda-java - VERSION - -``` +2. Install the Datadog Java APM client -{{% /tab %}} -{{% tab "Gradle" %}} + ```dockerfile + RUN yum -y install tar wget gzip + RUN wget -O /opt/dd-java-agent.jar https://dtdg.co/latest-java-tracer + ``` -Include the following in your `build.gradle`: +3. Set the required environment variables -```groovy -dependencies { - implementation 'com.datadoghq:datadog-lambda-java:VERSION' -} -``` + - Set `AWS_LAMBDA_EXEC_WRAPPER` to `/opt/datadog_wrapper`. + - Set `DD_SITE` to your [Datadog site][2] to send the telemetry to. + - Set `DD_API_KEY_SECRET_ARN` to the ARN of the AWS secret where your [Datadog API key][3] is securely stored. The key needs to be stored as a plaintext string (not a JSON blob). The `secretsmanager:GetSecretValue` permission is required. For quick testing, you can use `DD_API_KEY` instead and set the Datadog API key in plaintext. +[1]: https://gallery.ecr.aws/datadog/lambda-extension +[2]: https://docs.datadoghq.com/getting_started/site/ +[3]: https://app.datadoghq.com/organization-settings/api-keys {{% /tab %}} -{{< /tabs >}} - -### Wrap your Lambda handler - -Wrap your Lambda handler function using the wrapper provided by the Datadog Lambda Library: - -```java -public class Handler implements RequestHandler { - public Integer handleRequest(APIGatewayV2ProxyRequestEvent request, Context context){ - DDLambda ddl = new DDLambda(request, context); //Required to initialize the trace - - do_some_stuff(); - make_some_http_requests(); - - ddl.finish(); //Required to finish the active span. - return new ApiGatewayResponse(); - } -} -``` - -### Unified service tagging - -Datadog recommends tagging your serverless applications with `DD_ENV`, `DD_SERVICE`, `DD_VERSION`, and `DD_TAGS`. See the [Lambda extension documentation][2] for more details. - -## Explore - -After configuring your function following the steps above, view your metrics, logs, and traces on the [Serverless homepage][9]. - -### Monitor custom business logic - -If you would like to submit a custom metric, see the sample code below: - -```java -public class Handler implements RequestHandler { - public Integer handleRequest(APIGatewayV2ProxyRequestEvent request, Context context){ - DDLambda ddl = new DDLambda(request, context); - - Map myTags = new HashMap(); - myTags.put("product", "latte"); - myTags.put("order","online"); - - // Submit a custom metric - ddl.metric( - "coffee_house.order_value", // Metric name - 12.45, // Metric value - myTags); // Associated tags - - URL url = new URL("https://example.com"); - HttpURLConnection hc = (HttpURLConnection)url.openConnection(); - hc.connect(); - - ddl.finish(); - } -} -``` - -See the [custom metrics documentation][10] for more information on custom metric submission. - -### Connect logs and traces - -To automatically connect Java Lambda function logs and traces, see [Connecting Java Logs and Traces][11] for instructions. - -
Failing to use the correct Java runtime can result in errors like, "Error opening zip file or JAR manifest missing : /opt/java/lib/dd-java-agent.jar" Make sure to use java8.al2 or java11 as runtime as described above.
- -## Upgrading - -Apache Foundation has announced that log4j, a popular Java logging library, is [vulnerable to remote code execution][12]. -Some versions of `datadog-lambda-java` include a transitive dependency on log4j that may be vulnerable. The vulnerable versions are: - -- `<=0.3.3` -- `1.4.0` - -The latest version of datadog-lambda java is ![Maven Cental][4]. Use this version (omitting the preceeding `v`) when following the upgrading instructions below. - -If you do not wish to upgrade to `1.4.x`, `0.3.x` is updated with the latest log4j security patches as well. -You may find the latest version of `0.3.x` in the [datadog-lambda-java repository][13]. - -The version of the `datadog-lambda-java` dependency in your Lambda function is set in `pom.xml` or `build.gradle` depending on whether you are using Maven or Gradle, respectively. - -{{< tabs >}} -{{% tab "Maven" %}} +{{% tab "Custom" %}} -Your `pom.xml` file contains a section similar to the following: +1. Install the Datadog Lambda Extension -```xml - - com.datadoghq - datadog-lambda-java - VERSION - -``` + [Configure the layers][1] for your Lambda function using the ARN in the following format: -Replace `VERSION` with the latest version of `datadog-lambda-java` (available above). -Then redeploy your lambda function. + `arn:aws:lambda::464622532012:layer:Datadog-Extension:{{< latest-lambda-layer-version layer="extension" >}}` -{{% /tab %}} +2. Install the Datadog Java APM client -{{% tab "Gradle" %}} + [Configure the layers][1] for your Lambda function using the ARN in the following format: -Your `build.gradle` file contains a section similar to the following: + `arn:aws:lambda::464622532012:layer:dd-trace-java:{{< latest-lambda-layer-version layer="dd-trace-java" >}}` -```groovy -dependencies { - implementation 'com.datadoghq:datadog-lambda-java:VERSION' -} -``` +3. Set the required environment variables -Replace `VERSION` with the latest version of `datadog-lambda-java` (available above). -Then redeploy your lambda function. + - Set `AWS_LAMBDA_EXEC_WRAPPER` to `/opt/datadog_wrapper`. + - Set `DD_SITE` to your [Datadog site][2] to send the telemetry to. + - Set `DD_API_KEY_SECRET_ARN` to the ARN of the AWS secret where your [Datadog API key][3] is securely stored. The key needs to be stored as a plaintext string (not a JSON blob). The `secretsmanager:GetSecretValue` permission is required. For quick testing, you can use `DD_API_KEY` instead and set the Datadog API key in plaintext. +[1]: https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html +[2]: https://docs.datadoghq.com/getting_started/site/ +[3]: https://app.datadoghq.com/organization-settings/api-keys {{% /tab %}} -{{< /tabs>}} - -If you are upgrading from 0.3.x to 1.4.x and you wish to use the `dd-trace-java` tracer, find the reference to the `dd-trace-java` lambda layer and change it to: - -``` -arn:aws:lambda::464622532012:layer:dd-trace-java:4 -``` +{{< /tabs >}} -## Troubleshooting +## What's next? -If you have trouble collecting monitoring data after following the instructions above, see the [serverless monitoring troubleshooting guide][14]. +- You can now view metrics, logs, and traces on the [Serverless Homepage][1]. +- Submit a [custom metric][2] or [APM span][3] to monitor your business logic. +- See the [troubleshooting guide][4] if you have trouble collecting the telemetry +- See the [advanced configurations][5] to + - connect your telemetry using tags + - collect telemetry for AWS API Gateway, SQS, etc. + - capture the Lambda request and response payloads + - link errors of your Lambda functions to your source code + - filter or scrub sensitive information from logs or traces ## Further Reading {{< partial name="whats-next/whats-next.html" >}} -[1]: /serverless/guide/datadog_forwarder_java -[2]: /serverless/libraries_integrations/extension/ -[3]: /serverless/enhanced_lambda_metrics -[4]: https://img.shields.io/maven-central/v/com.datadoghq/datadog-lambda-java -[5]: /logs/guide/send-aws-services-logs-with-the-datadog-lambda-function/#collecting-logs-from-cloudwatch-log-group -[6]: /serverless/insights#cold-starts -[7]: /monitors/create/types/metric/?tab=threshold#overview -[8]: /getting_started/tagging/unified_service_tagging/#aws-lambda-functions -[9]: https://app.datadoghq.com/functions -[10]: /serverless/custom_metrics?tab=java -[11]: /tracing/connect_logs_and_traces/java/ -[12]: https://www.datadoghq.com/log4j-vulnerability/ -[13]: https://github.com/DataDog/datadog-lambda-java/releases -[14]: /serverless/guide/troubleshoot_serverless_monitoring/ +[1]: https://app.datadoghq.com/functions +[2]: https://docs.datadoghq.com/metrics/dogstatsd_metrics_submission/ +[3]: /tracing/custom_instrumentation/java/ +[4]: /serverless/guide/troubleshoot_serverless_monitoring/ +[5]: /serverless/configuration/ diff --git a/content/en/serverless/installation/nodejs.md b/content/en/serverless/installation/nodejs.md index 3a394fb8e6c80..19dfffa44a66b 100644 --- a/content/en/serverless/installation/nodejs.md +++ b/content/en/serverless/installation/nodejs.md @@ -2,21 +2,15 @@ title: Instrumenting Node.js Serverless Applications kind: documentation further_reading: - - link: '/serverless/serverless_integrations/plugin/' + - link: '/serverless/configuration' tag: 'Documentation' - text: 'Datadog Serverless Plugin' - - link: '/serverless/serverless_integrations/macro/' + text: 'Configure Serverless Monitoring' + - link: '/serverless/guide/serverless_tracing_and_webpack/' tag: 'Documentation' - text: 'Datadog Serverless Macro' - - link: '/serverless/serverless_integrations/cli/' + text: 'Node.js Lambda Tracing and Webpack Compatibility' + - link: '/serverless/guide/troubleshoot_serverless_monitoring' tag: 'Documentation' - text: 'Datadog Serverless CLI' - - link: 'serverless/serverless_tagging/' - tag: 'Documentation' - text: 'Tagging Serverless Applications' - - link: 'serverless/distributed_tracing/' - tag: 'Documentation' - text: 'Tracing Serverless Applications' + text: 'Troubleshoot Serverless Monitoring' - link: 'serverless/custom_metrics/' tag: 'Documentation' text: 'Submitting Custom Metrics from Serverless Applications' @@ -25,428 +19,324 @@ aliases: - /serverless/guide/nodejs/ --- -
If you previously set up Datadog Serverless using the Datadog Forwarder, see the Datadog Forwarder - Node guide.
+
If you previously set up your Lambda functions using the Datadog Forwarder, see instrumenting using the Datadog Forwarder.
+ +
If your Lambda functions are deployed in VPC without access to the public internet, you can send data either using AWS PrivateLink for the datadoghq.com Datadog site, or using a proxy for all other sites.
-## Configuration +
If you are bundling using webpack or esbuild, you may need to mark the Datadog libraries as external.
-Datadog offers many different ways to enable instrumentation for your serverless applications. Choose a method below that best suits your needs. Datadog generally recommends using the Datadog CLI, which does not require redeploying your whole application. The CLI can also be added to your CI/CD pipelines to enable instrumentation for applications across your entire organization. +## Installation + +Datadog offers many different ways to enable instrumentation for your serverless applications. Choose a method below that best suits your needs. Datadog generally recommends using the Datadog CLI. {{< tabs >}} {{% tab "Datadog CLI" %}} The Datadog CLI modifies existing Lambda functions' configurations to enable instrumentation without requiring a new deployment. It is the quickest way to get started with Datadog's serverless monitoring. -You can also add the command to your CI/CD pipelines to enable instrumentation for all your serverless applications. Run the command _after_ your normal serverless application deployment, so that changes made by the Datadog CLI command are not overridden. +1. Install the Datadog CLI client -### Install + ```sh + npm install -g @datadog/datadog-ci + ``` -Install the Datadog CLI with NPM: +2. If you are new to Datadog serverless monitoring, launch the Datadog CLI in the interactive mode to guide your first installation for a quick start, and you can ignore the remaining steps. To permanently install Datadog for your production applications, skip this step and follow the remaining ones to run the Datadog CLI command in your CI/CD pipelines _after_ your normal deployment. -```sh -npm install -g @datadog/datadog-ci -``` + ```sh + datadog-ci lambda instrument -i + ``` -### Configure credentials +3. Configure the AWS credentials -For a quick start, configure Datadog and [AWS credentials][1] using the [instrumentation command](#instrument). For production applications, provide credentials in a more secure manner by using environment variables. For example: + Datadog CLI requires access to the AWS Lambda service, and depends on the AWS JavaScript SDK to [resolve the credentials][1]. Ensure your AWS credentials are configured using the same method you would use when invoking the AWS CLI. -```bash -export DATADOG_API_KEY="" -export DATADOG_SITE="" # such as datadoghq.com, datadoghq.eu, us3.datadoghq.com or ddog-gov.com -export AWS_ACCESS_KEY_ID="" -export AWS_SECRET_ACCESS_KEY="" -``` +4. Configure the Datadog site + + Specify the [Datadog site][2] where the telemetry should be sent to. The default is `datadoghq.com`. -### Instrument + ```sh + export DATADOG_SITE="" # such as datadoghq.com, datadoghq.eu or ddog-gov.com + ``` -**Note**: Instrument your Lambda functions in a dev or staging environment first. Should the instrumentation result be unsatisfactory, run `uninstrument` with the same arguments to revert the changes. +5. Configure the Datadog API key -To instrument the function, run the following command: + Datadog recommends saving the Datadog API key in AWS Secrets Manager for security and easy rotation. The key needs to be stored as a plaintext string (not a JSON blob). Ensure your Lambda functions have the required `secretsmanager:GetSecretValue` IAM permission. -```sh -datadog-ci lambda instrument -f -f -r -v -e -``` + ```sh + export DATADOG_API_KEY_SECRET_ARN="" + ``` -To fill in the placeholders: + For quick testing purposes, you can also set the Datadog API key in plaintext: -- Replace `` and `` with your Lambda function names. -- Replace `` with the AWS region name. -- Replace `` with the desired version of the Datadog Lambda Library. The latest version is `{{< latest-lambda-layer-version layer="node" >}}`. -- Replace `` with the desired version of the Datadog Lambda Extension. The latest version is `{{< latest-lambda-layer-version layer="extension" >}}`. + ```sh + export DATADOG_API_KEY="" + ``` -For example: +6. Instrument your Lambda functions -```sh -datadog-ci lambda instrument -f my-function -f another-function -r us-east-1 -v {{< latest-lambda-layer-version layer="node" >}} -e {{< latest-lambda-layer-version layer="extension" >}} -``` + **Note**: Instrument your Lambda functions in a dev or staging environment first! Should the instrumentation result be unsatisfactory, run `uninstrument` with the same arguments to revert the changes. + + To instrument your Lambda functions, run the following command. + + ```sh + datadog-ci lambda instrument -f -f -r -v {{< latest-lambda-layer-version layer="node" >}} -e {{< latest-lambda-layer-version layer="extension" >}} + ``` + + To fill in the placeholders: + - Replace `` and `` with your Lambda function names. Alternatively, you can use `--functions-regex` to automatically instrument multiple functions whose names match the given regular expression. + - Replace `` with the AWS region name. -More information and additional parameters can be found in the [CLI documentation][2]. + Additional parameters can be found in the [CLI documentation][3]. [1]: https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/setting-credentials-node.html -[2]: https://docs.datadoghq.com/serverless/serverless_integrations/cli +[2]: https://docs.datadoghq.com/getting_started/site/ +[3]: https://docs.datadoghq.com/serverless/serverless_integrations/cli {{% /tab %}} {{% tab "Serverless Framework" %}} -The [Datadog Serverless Plugin][1] automatically adds the Datadog Lambda Library to your functions using Lambda Layers, and configures your functions to send metrics, traces, and logs to Datadog through the [Datadog Lambda Extension][2]. +
If you are instead deploying your Serverless Framework app by natively exporting a JSON object from a JavaScript file (for example, by using a serverless.ts file), follow the custom installation instructions.
+ +The [Datadog Serverless Plugin][1] automatically configures your functions to send metrics, traces, and logs to Datadog through the [Datadog Lambda Extension][2]. To install and configure the Datadog Serverless Plugin, follow these steps: 1. Install the Datadog Serverless Plugin: - ``` - npm install serverless-plugin-datadog --save-dev - ``` -2. In your `serverless.yml`, add the following: - ``` - plugins: - - serverless-plugin-datadog - ``` -
If you are instead deploying your Serverless Framework app by natively exporting a JSON object from a Javascript file (for example, by using a serverless.ts file), follow the custom installation instructions.
-3. In your `serverless.yml`, also add the following section: + ```sh + serverless plugin install --name serverless-plugin-datadog ``` + +2. Update your `serverless.yml`: + + ```yaml custom: datadog: - apiKey: # Your Datadog API Key goes here. + site: + apiKeySecretArn: ``` - Find your Datadog API key on the [API Management page][3]. For additional settings, see the [plugin documentation][1]. -If you encounter the "Code uncompressed size is greater than max allowed size of 272629760" error after adding `serverless-plugin-datadog`, see this [troubleshooting guide][4]. + To fill in the placeholders: + - Replace `` with your [Datadog site][3] to send the telemetry to. + - Replace `` with the ARN of the AWS secret where your [Datadog API key][4] is securely stored. The key needs to be stored as a plaintext string (not a JSON blob). The `secretsmanager:GetSecretValue` permission is required. For quick testing, you can instead use `apiKey` and set the Datadog API key in plaintext. + For more information and additional settings, see the [plugin documentation][1]. [1]: https://docs.datadoghq.com/serverless/serverless_integrations/plugin -[2]: /serverless/libraries_integrations/extension -[3]: https://app.datadoghq.com/organization-settings/api-keys -[4]: /serverless/guide/serverless_package_too_large +[2]: https://docs.datadoghq.com/serverless/libraries_integrations/extension +[3]: https://docs.datadoghq.com/getting_started/site/ +[4]: https://app.datadoghq.com/organization-settings/api-keys {{% /tab %}} {{% tab "AWS SAM" %}} -The [Datadog CloudFormation macro][1] automatically transforms your SAM application template to add the Datadog Lambda library to your functions using layers, and configures your functions to send metrics, traces, and logs to Datadog through the [Datadog Lambda Extension][2]. +The [Datadog CloudFormation macro][1] automatically transforms your SAM application template to install Datadog on your functions using Lambda layers, and configures your functions to send metrics, traces, and logs to Datadog through the [Datadog Lambda Extension][2]. -### Install +1. Install the Datadog CloudFormation macro -Run the following command with your [AWS credentials][3] to deploy a CloudFormation stack that installs the macro AWS resource. You only need to install the macro once for a given region in your account. Replace `create-stack` with `update-stack` to update the macro to the latest version. + Run the following command with your [AWS credentials][3] to deploy a CloudFormation stack that installs the macro AWS resource. You only need to install the macro **once** for a given region in your account. Replace `create-stack` with `update-stack` to update the macro to the latest version. -```sh -aws cloudformation create-stack \ - --stack-name datadog-serverless-macro \ - --template-url https://datadog-cloudformation-template.s3.amazonaws.com/aws/serverless-macro/latest.yml \ - --capabilities CAPABILITY_AUTO_EXPAND CAPABILITY_IAM -``` - -The macro is now deployed and ready to use. + ```sh + aws cloudformation create-stack \ + --stack-name datadog-serverless-macro \ + --template-url https://datadog-cloudformation-template.s3.amazonaws.com/aws/serverless-macro/latest.yml \ + --capabilities CAPABILITY_AUTO_EXPAND CAPABILITY_IAM + ``` -### Instrument + The macro is now deployed and ready to use. -In your `template.yml`, add the following under the `Transform` section, **after** the `AWS::Serverless` transform for SAM. +2. Instrument your Lambda functions -```yaml -Transform: - - AWS::Serverless-2016-10-31 - - Name: DatadogServerless - Parameters: - stackName: !Ref 'AWS::StackName' - apiKey: - nodeLayerVersion: { { < latest-lambda-layer-version layer="node" > } } - extensionLayerVersion: { { < latest-lambda-layer-version layer="extension" > } } - service: '' # Optional - env: '' # Optional -``` + Add the `DatadogServerless` transform **after** the `AWS::Serverless` transform under the `Transform` section in your for SAM `template.yml`. -To fill in the placeholders: + ```yaml + Transform: + - AWS::Serverless-2016-10-31 + - Name: DatadogServerless + Parameters: + stackName: !Ref "AWS::StackName" + nodeLayerVersion: {{< latest-lambda-layer-version layer="node" >}} + extensionLayerVersion: {{< latest-lambda-layer-version layer="extension" >}} + site: "" + apiKeySecretArn: "" + ``` -- Replace `` with your Datadog API key from the [API Management page][4]. -- Replace `` and `` with appropriate values. + To fill in the placeholders: + - Replace `` with your [Datadog site][4] to send the telemetry to. + - Replace `` with the ARN of the AWS secret where your [Datadog API key][5] is securely stored. The key needs to be stored as a plaintext string (not a JSON blob). The `secretsmanager:GetSecretValue` permission is required. For quick testing, you can use `apiKey` instead and set the Datadog API key in plaintext. -More information and additional parameters can be found in the [macro documentation][1]. + More information and additional parameters can be found in the [macro documentation][1]. [1]: https://docs.datadoghq.com/serverless/serverless_integrations/macro -[2]: /serverless/libraries_integrations/extension +[2]: https://docs.datadoghq.com/serverless/libraries_integrations/extension [3]: https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html -[4]: https://app.datadoghq.com/organization-settings/api-keys +[4]: https://docs.datadoghq.com/getting_started/site/ +[5]: https://app.datadoghq.com/organization-settings/api-keys {{% /tab %}} {{% tab "AWS CDK" %}} -The [Datadog CDK Construct][1] automatically adds the Datadog Lambda Library to your functions using Lambda Layers, and configures your functions to send metrics, traces, and logs to Datadog through the [Datadog Lambda Extension][2]. +The [Datadog CDK Construct][1] automatically installs Datadog on your functions using Lambda Layers, and configures your functions to send metrics, traces, and logs to Datadog through the Datadog Lambda Extension. -### Install the Datadog CDK constructs library +1. Install the Datadog CDK constructs library -Run the following NPM command in your CDK project to install the Datadog CDK constructs library: + ```sh + # For AWS CDK v1 + npm install datadog-cdk-constructs --save-dev -```sh -npm install datadog-cdk-constructs --save-dev -``` - -### Instrument the function + # For AWS CDK v2 + npm install datadog-cdk-constructs-v2 --save-dev + ``` -Import the `datadog-cdk-construct` module in your AWS CDK app and add the following configurations: +2. Instrument your Lambda functions -```typescript -import * as cdk from "@aws-cdk/core"; -import { Datadog } from "datadog-cdk-constructs"; + ```javascript + // For AWS CDK v1 + import { Datadog } from "datadog-cdk-constructs"; -class CdkStack extends cdk.Stack { - constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) { - super(scope, id, props); + // For AWS CDK v2 + import { Datadog } from "datadog-cdk-constructs-v2"; const datadog = new Datadog(this, "Datadog", { - nodeLayerVersion: {{< latest-lambda-layer-version layer="node" >}}, + nodeLayerVersion: {{< latest-lambda-layer-version layer="python" >}}, extensionLayerVersion: {{< latest-lambda-layer-version layer="extension" >}}, - apiKey: + site: "", + apiKeySecretArn: "" }); - datadog.addLambdaFunctions([]); - } -} -``` - -Replace `` with your Datadog API key from the [API Management page][3]. + datadog.addLambdaFunctions([]) + ``` -More information and additional parameters can be found in the [Datadog CDK NPM page][1]. + To fill in the placeholders: + - Replace `` with your [Datadog site][2] to send the telemetry to. + - Replace `` with the ARN of the AWS secret where your [Datadog API key][3] is securely stored. The key needs to be stored as a plaintext string (not a JSON blob).The `secretsmanager:GetSecretValue` permission is required. For quick testing, you can use `apiKey` instead and set the Datadog API key in plaintext. + More information and additional parameters can be found on the [Datadog CDK documentation][1]. -[1]: https://www.npmjs.com/package/datadog-cdk-constructs -[2]: https://github.com/DataDog/datadog-lambda-js/releases +[1]: https://github.com/DataDog/datadog-cdk-constructs +[2]: https://docs.datadoghq.com/getting_started/site/ [3]: https://app.datadoghq.com/organization-settings/api-keys {{% /tab %}} {{% tab "Container Image" %}} -### Install +1. Install the Datadog Lambda Library -If you are deploying your Lambda function as a container image, you cannot use the Datadog Lambda Library as a layer. Instead, you must install the Datadog Lambda Library as a dependency of your function within the image. If you are using Datadog tracing, you must also install `dd-trace`. + If you are deploying your Lambda function as a container image, you cannot use the Datadog Lambda library as a Lambda Layer. Instead, you must package the Datadog Lambda and tracing libraries within the image. -**NPM**: - -```sh -npm install datadog-lambda-js dd-trace -``` + ```sh + npm install datadog-lambda-js dd-trace + ``` -**Note**: The minor version of the `datadog-lambda-js` package always matches the layer version. For example, `datadog-lambda-js v0.5.0` matches the content of layer version 5. + Note that the minor version of the `datadog-lambda-js` package always matches the layer version. For example, `datadog-lambda-js v0.5.0` matches the content of layer version 5. -### Configure +2. Install the Datadog Lambda Extension -### Install the Datadog Lambda Extension + Add the Datadog Lambda Extension to your container image by adding the following to your Dockerfile: -Add the Datadog Lambda Extension to your container image by adding the following to your Dockerfile: + ```dockerfile + COPY --from=public.ecr.aws/datadog/lambda-extension: /opt/extensions/ /opt/extensions + ``` -``` -COPY --from=public.ecr.aws/datadog/lambda-extension: /opt/extensions/ /opt/extensions -``` + Replace `` with either a specific version number (for example, `{{< latest-lambda-layer-version layer="extension" >}}`) or with `latest`. You can see a complete list of possible tags in the [Amazon ECR repository][1]. -Replace `` with either a specific version number (for example, `{{< latest-lambda-layer-version layer="extension" >}}`) or with `latest`. You can see a complete list of possible tags in the [Amazon ECR repository][1]. +3. Redirect the handler function -### Configure the function + - Set your image's `CMD` value to `node_modules/datadog-lambda-js/dist/handler.handler`. You can set this in AWS or directly in your Dockerfile. Note that the value set in AWS overrides the value in the Dockerfile if you set both. + - Set the environment variable `DD_LAMBDA_HANDLER` to your original handler, for example, `myfunc.handler`. -1. Set your image's `CMD` value to `node_modules/datadog-lambda-js/dist/handler.handler`. You can set this in AWS or directly in your Dockerfile. **Note**: The value set in AWS overrides the value in the Dockerfile if you set both. -2. Set the following environment variables in AWS: + **Note**: If your Lambda function runs on `arm64`, you must either build your container image in an arm64-based Amazon Linux environment or [apply the Datadog wrapper in your function code][2] instead. You may also need to do that if you are using a third-party security or monitoring tool that is incompatible with the Datadog handler redirection. -- Set `DD_LAMBDA_HANDLER` to your original handler, for example, `myfunc.handler`. -- Set `DD_TRACE_ENABLED` to `true`. -- Set `DD_API_KEY` with your Datadog API key from the [API Management page][2]. +4. Configure the Datadog site and API key -3. Optionally add `service` and `env` tags with appropriate values to your function. + - Set the environment variable `DD_SITE` with your [Datadog site][3] to send the telemetry to. + - Set the environment variable `DD_API_KEY_SECRET_ARN` with the ARN of the AWS secret where your [Datadog API key][4] is securely stored. The key needs to be stored as a plaintext string (not a JSON blob). The `secretsmanager:GetSecretValue` permission is required. For quick testing, you can use `DD_API_KEY` instead and set the Datadog API key in plaintext. [1]: https://gallery.ecr.aws/datadog/lambda-extension -[2]: https://app.datadoghq.com/organization-settings/api-keys -{{% /tab %}} -{{% tab "Terraform" %}} - -### Update configurations - -1. Add the following configurations to the `aws_lambda_function` resources in your .tf files: - -{{< site-region region="us,us3,us5,eu" >}} - -```hcl -variable "dd_api_key" { - type = string - description = "Datadog API key" -} -resource "aws_lambda_function" "my_func" { - function_name = "my_func" - handler = "/opt/nodejs/node_modules/datadog-lambda-js/handler.handler" - layers = [ - "arn:aws:lambda::464622532012:layer:Datadog-:", - "arn:aws:lambda::464622532012:layer:Datadog-Extension:", - ] - environment { - variables = { - DD_LAMBDA_HANDLER = "my_func.handler" - DD_TRACE_ENABLED = true - DD_API_KEY = var.dd_api_key - } - } -} -``` - -{{< /site-region >}} -{{< site-region region="gov" >}} - -```hcl -variable "dd_api_key" { - type = string - description = "Datadog API key" -} -resource "aws_lambda_function" "my_func" { - function_name = "my_func" - handler = "/opt/nodejs/node_modules/datadog-lambda-js/handler.handler" - layers = [ - "arn:aws-us-gov:lambda::002406178527:layer:Datadog-:", - "arn:aws-us-gov:lambda::002406178527:layer:Datadog-Extension:", - ] - environment { - variables = { - DD_LAMBDA_HANDLER = "my_func.handler" - DD_TRACE_ENABLED = true - DD_API_KEY = var.dd_api_key - } - } -} -``` - -{{< /site-region >}} - -2. Replace the following placeholders with appropriate values: - - - Replace `` with the AWS region to which your Lambda functions are deployed. - - Replace `` with the appropriate Node.js runtime. The available `RUNTIME` options are `Node10-x`, `Node12-x`, and `Node14-x`. - - Replace `` with the desired version of the Datadog Lambda Library. The latest version is `{{< latest-lambda-layer-version layer="node" >}}`. - - Replace `` with the desired version of the Datadog Lambda Extension. The latest version is `{{< latest-lambda-layer-version layer="extension" >}}`. - -3. Apply the Terraform configuration with your Datadog API key that can be found on the [API Management page][1]: - - ```bash - terraform apply -var "dd_api_key=" - ``` - - -[1]: https://app.datadoghq.com/organization-settings/api-keys +[2]: https://docs.datadoghq.com/serverless/guide/handler_wrapper +[3]: https://docs.datadoghq.com/getting_started/site/ +[4]: https://app.datadoghq.com/organization-settings/api-keys {{% /tab %}} {{% tab "Custom" %}} -
If you are not using a serverless development tool that Datadog supports, such as the Serverless Framework or AWS CDK, Datadog strongly encourages you instrument your serverless applications with the Datadog CLI.
- -### Install the Datadog Lambda library - -The Datadog Lambda Library can be imported either as a layer (recommended) _OR_ as a JavaScript package. - -The minor version of the `datadog-lambda-js` package always matches the layer version. For example, datadog-lambda-js v0.5.0 matches the content of layer version 5. - -#### Using the layer - -[Configure the layers][1] for your Lambda function using the ARN in the following format: - -{{< site-region region="us,us3,us5,eu" >}} - -``` -arn:aws:lambda::464622532012:layer:Datadog-: -``` - -{{< /site-region >}} -{{< site-region region="gov" >}} - -``` -arn:aws-us-gov:lambda::002406178527:layer:Datadog-: -``` - -{{< /site-region >}} +
If you are not using a serverless development tool that Datadog supports, such as the Serverless Framework or AWS CDK, Datadog strongly encourages you instrument your serverless applications with the Datadog CLI.
-The available `RUNTIME` options are `Node10-x`, `Node12-x`, and `Node14-x`. The latest `VERSION` is `{{< latest-lambda-layer-version layer="node" >}}`. For example: +1. Install the Datadog Lambda library -{{< site-region region="us,us3,us5,eu" >}} + The Datadog Lambda Library can be imported either as a layer (recommended) _OR_ as a JavaScript package. -``` -arn:aws:lambda:us-east-1:464622532012:layer:Datadog-Node14-x:{{< latest-lambda-layer-version layer="node" >}} -``` - -{{< /site-region >}} -{{< site-region region="gov" >}} - -``` -arn:aws-us-gov:lambda:us-gov-east-1:002406178527::layer:Datadog-Node14-x:{{< latest-lambda-layer-version layer="node" >}} -``` + The minor version of the `datadog-lambda-js` package always matches the layer version. For example, datadog-lambda-js v0.5.0 matches the content of layer version 5. -{{< /site-region >}} + - Option A: [Configure the layers][1] for your Lambda function using the ARN in the following format: -#### Using the package + ```sh + # Use this format for AWS commercial regions + arn:aws:lambda::464622532012:layer:Datadog-:{{< latest-lambda-layer-version layer="node" >}} -If you cannot use the prebuilt Datadog Lambda layer, alternatively you can install the packages `datadog-lambda-js` and `dd-trace` using your favorite package manager. + # Use this format for AWS GovCloud regions + arn:aws-us-gov:lambda::002406178527:layer:Datadog-:{{< latest-lambda-layer-version layer="node" >}} + ``` -**NPM**: + Replace `` with a valid AWS region, such as `us-east-1`. The available `RUNTIME` options are `Node12-x`, and `Node14-x`. -``` -npm install datadog-lambda-js dd-trace -``` - -See the [latest release][2]. + - Option B: If you cannot use the prebuilt Datadog Lambda layer, alternatively you can install the packages `datadog-lambda-js` and `dd-trace` using your favorite package manager. -### Install the Datadog Lambda Extension + ``` + npm install datadog-lambda-js dd-trace + ``` -[Configure the layers][1] for your Lambda function using the ARN in the following format: +2. Install the Datadog Lambda Extension -{{< site-region region="us,us3,us5,eu" >}} + [Configure the layers][1] for your Lambda function using the ARN in the following format: -``` -// For x86 lambdas -arn:aws:lambda::464622532012:layer:Datadog-Extension: -// For arm64 lambdas -arn:aws:lambda::464622532012:layer:Datadog-Extension-ARM: + ```sh + # Use this format for x86-based Lambda deployed in AWS commercial regions + arn:aws:lambda::464622532012:layer:Datadog-Extension:{{< latest-lambda-layer-version layer="extension" >}} -``` + # Use this format for arm64-based Lambda deployed in AWS commercial regions + arn:aws:lambda::464622532012:layer:Datadog-Extension-ARM:{{< latest-lambda-layer-version layer="extension" >}} -{{< /site-region >}} -{{< site-region region="gov" >}} + # Use this format for x86-based Lambda deployed in AWS GovCloud regions + arn:aws-us-gov:lambda::002406178527:layer:Datadog-Extension:{{< latest-lambda-layer-version layer="extension" >}} -``` -// For x86 lambdas -arn:aws-us-gov:lambda::002406178527:layer:Datadog-Extension: -// For arm64 lambdas -arn:aws-us-gov:lambda::002406178527:layer:Datadog-Extension-ARM: -``` + # Use this format for arm64-based Lambda deployed in AWS GovCloud regions + arn:aws-us-gov:lambda::002406178527:layer:Datadog-Extension-ARM:{{< latest-lambda-layer-version layer="extension" >}} + ``` -{{< /site-region >}} + Replace `` with a valid AWS region, such as `us-east-1`. -The latest `EXTENSION_VERSION` is `{{< latest-lambda-layer-version layer="extension" >}}`. +3. Redirect the handler function -### Configure + - Set your function's handler to `/opt/nodejs/node_modules/datadog-lambda-js/handler.handler` if using the layer, or `node_modules/datadog-lambda-js/dist/handler.handler` if using the package. + - Set the environment variable `DD_LAMBDA_HANDLER` to your original handler, for example, `myfunc.handler`. -Follow these steps to configure the function: + **Note**: If your Lambda function runs on `arm64` and the `datadog-lambda-js` library is installed as a NPM package (option B of step 1), you must [apply the Datadog wrapper in your function code][2] instead. You may also need to do that if you are using a third-party security or monitoring tool that is incompatible with the Datadog handler redirection. -1. Set your function's handler to `/opt/nodejs/node_modules/datadog-lambda-js/handler.handler` if using the layer, or `node_modules/datadog-lambda-js/dist/handler.handler` if using the package. -2. Set the environment variable `DD_LAMBDA_HANDLER` to your original handler, for example, `myfunc.handler`. -3. Set the environment variable `DD_TRACE_ENABLED` to `true`. -4. Set the environment variable `DD_API_KEY` to your Datadog API key from the [API Management page][3]. -5. Optionally add a `service` and `env` tag with appropriate values to your function. +4. Configure Datadog site and API key + - Set the environment variable `DD_SITE` with your [Datadog site][3] to send the telemetry to. + - Set the environment variable `DD_API_KEY_SECRET_ARN` with the ARN of the AWS secret where your [Datadog API key][4] is securely stored. The key needs to be stored as a plaintext string (not a JSON blob). The `secretsmanager:GetSecretValue` permission is required. For quick testing, you can use `DD_API_KEY` instead and set the Datadog API key in plaintext. [1]: https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html -[2]: https://www.npmjs.com/package/datadog-lambda-js -[3]: https://app.datadoghq.com/organization-settings/api-keys +[2]: https://docs.datadoghq.com/serverless/guide/handler_wrapper +[3]: https://docs.datadoghq.com/getting_started/site/ +[4]: https://app.datadoghq.com/organization-settings/api-keys {{% /tab %}} {{< /tabs >}} -## Explore Datadog serverless monitoring - -After you have configured your function following the steps above, you can view metrics, logs and traces on the [Serverless Homepage][1]. - -### Unified service tagging +## What's next? -Datadog recommends tagging your serverless applications with `DD_ENV`, `DD_SERVICE`, `DD_VERSION`, and `DD_TAGS`. See the [Lambda extension documentation][2] for more details. - -### Collect logs from AWS serverless resources - -Serverless logs generated by managed resources besides AWS Lambda functions can be hugely valuable in helping identify the root cause of issues in your serverless applications. Datadog recommends you forward logs from the following managed resources in your environment: - -- API's: API Gateway, AppSync, ALB -- Queues & Streams: SQS, SNS, Kinesis -- Data Stores: DynamoDB, S3, RDS, etc. - -To collect logs from non-Lambda AWS resources, install and configure the [Datadog Forwarder][3] to subscribe to each of your managed resource CloudWatch log groups. +- Congratulations! You can now view metrics, logs, and traces on the [Serverless Homepage][1]. +- See the sample code to [monitor custom business logic](#monitor-custom-business-logic) +- See the [troubleshooting guide][2] if you have trouble collecting the telemetry +- See the [advanced configurations][3] to + - connect your telemetry using tags + - collect telemetry for AWS API Gateway, SQS, etc. + - capture the Lambda request and response payloads + - link errors of your Lambda functions to your source code + - filter or scrub sensitive information from logs or traces ### Monitor custom business logic -If you would like to submit a custom metric or span, see the sample code below: +To monitor your custom business logic, submit a custom metric or span using the sample code below. For additional options, see [custom metric submission for serverless applications][4] and the APM guide for [custom instrumentation][5]. ```javascript const { sendDistributionMetric, sendDistributionMetricWithDate } = require('datadog-lambda-js'); @@ -486,17 +376,12 @@ exports.handler = async (event) => { }; ``` -For more information on custom metric submission, see [here][4]. For additional details on custom instrumentation, see the Datadog APM documentation for [custom instrumentation][5]. - -If your Lambda function is running in a VPC, follow the [Datadog Lambda Extension AWS PrivateLink Setup][6] guide to ensure that the extension can reach Datadog API endpoints. - ## Further Reading {{< partial name="whats-next/whats-next.html" >}} [1]: https://app.datadoghq.com/functions -[2]: /serverless/libraries_integrations/extension/#tagging -[3]: /logs/guide/forwarder/ +[2]: /serverless/guide/troubleshoot_serverless_monitoring/ +[3]: /serverless/configuration/ [4]: /serverless/custom_metrics?tab=nodejs [5]: /tracing/custom_instrumentation/nodejs/ -[6]: /serverless/guide/extension_private_link/ diff --git a/content/en/serverless/installation/python.md b/content/en/serverless/installation/python.md index 24ed39b5c68b0..bc33dab2ab982 100644 --- a/content/en/serverless/installation/python.md +++ b/content/en/serverless/installation/python.md @@ -2,560 +2,340 @@ title: Instrumenting Python Serverless Applications kind: documentation further_reading: - - link: 'serverless/datadog_lambda_library/python' + - link: '/serverless/configuration' tag: 'Documentation' - text: 'Datadog Lambda Library for Python' - - link: 'serverless/distributed_tracing/' + text: 'Configure Serverless Monitoring' + - link: '/serverless/guide/troubleshoot_serverless_monitoring' tag: 'Documentation' - text: 'Tracing Serverless Applications' + text: 'Troubleshoot Serverless Monitoring' - link: 'serverless/custom_metrics/' tag: 'Documentation' text: 'Submitting Custom Metrics from Serverless Applications' - - link: '/serverless/guide/troubleshoot_serverless_monitoring' - tag: 'Documentation' - text: 'Troubleshoot Serverless Monitoring' aliases: - /serverless/datadog_lambda_library/python/ - /serverless/guide/python/ --- -
If your Python Lambda functions are written in Python 3.6 or less, or you previously set up Datadog Serverless using the Datadog Forwarder, see the Using the Datadog Forwarder - Python guide.
+
If your Python Lambda functions are written in Python 3.6 or less, or you previously set up your Lambda functions using the Datadog Forwarder, see instrumenting using the Datadog Forwarder.
+ +
If your Lambda functions are deployed in VPC without access to the public internet, you can send data either using AWS PrivateLink for the datadoghq.com Datadog site, or using a proxy for all other sites.
-## Configuration +## Installation -Datadog offers many different ways to enable instrumentation for your serverless applications. Choose a method below that best suits your needs. Datadog generally recommends using the Datadog CLI, which does not require redeploying your whole application. The CLI can also be added to your CI/CD pipelines to enable instrumentation for applications across your entire organization. +Datadog offers many different ways to enable instrumentation for your serverless applications. Choose a method below that best suits your needs. Datadog generally recommends using the Datadog CLI. {{< tabs >}} {{% tab "Datadog CLI" %}} The Datadog CLI modifies existing Lambda functions' configurations to enable instrumentation without requiring a new deployment. It is the quickest way to get started with Datadog's serverless monitoring. -You can also add the command to your CI/CD pipelines to enable instrumentation for all your serverless applications. Run the command _after_ your normal serverless application deployment, so that changes made by the Datadog CLI command are not overridden. +1. Install the Datadog CLI client + + ```sh + npm install -g @datadog/datadog-ci + ``` -### Install +2. If you are new to Datadog serverless monitoring, launch the Datadog CLI in the interactive mode to guide your first installation for a quick start, and you can ignore the remaining steps. To permanently install Datadog for your production applications, skip this step and follow the remaining ones to run the Datadog CLI command in your CI/CD pipelines _after_ your normal deployment. -Install the Datadog CLI with NPM: + ```sh + datadog-ci lambda instrument -i + ``` -```sh -npm install -g @datadog/datadog-ci -``` +3. Configure the AWS credentials -### Configure credentials + Datadog CLI requires access to the AWS Lambda service, and depends on the AWS JavaScript SDK to [resolve the credentials][1]. Ensure your AWS credentials are configured using the same method you would use when invoking the AWS CLI. -For a quick start, configure Datadog and [AWS credentials][1] using the [instrumentation command](#instrument). For production applications, provide credentials in a more secure manner by using environment variables. For example: +4. Configure the Datadog site -```bash -export DATADOG_API_KEY="" -export DATADOG_SITE="" # such as datadoghq.com, datadoghq.eu, us3.datadoghq.com or ddog-gov.com -export AWS_ACCESS_KEY_ID="" -export AWS_SECRET_ACCESS_KEY="" -``` + Specify the [Datadog site][2] where the telemetry should be sent to. The default is `datadoghq.com`. -### Instrument + ```sh + export DATADOG_SITE="" # such as datadoghq.com, datadoghq.eu or ddog-gov.com + ``` -**Note**: Instrument your Lambda functions in a dev or staging environment first! Should the instrumentation result be unsatisfactory, run `uninstrument` with the same arguments to revert the changes. +5. Configure the Datadog API key -To instrument your Lambda functions, run the following command: + Datadog recommends saving the Datadog API key in AWS Secrets Manager for security and easy rotation. The key needs to be stored as a plaintext string (not a JSON blob). Ensure your Lambda functions have the required `secretsmanager:GetSecretValue` IAM permission. -```sh -datadog-ci lambda instrument -f -f -r -v -e -``` + ```sh + export DATADOG_API_KEY_SECRET_ARN="" + ``` + + For quick testing purposes, you can also set the Datadog API key in plaintext: + + ```sh + export DATADOG_API_KEY="" + ``` -To fill in the placeholders: +6. Instrument your Lambda functions -- Replace `` and `` with your Lambda function names. -- Replace `` with the AWS region name. -- Replace `` with the desired version of the Datadog Lambda Library. The latest version is `{{< latest-lambda-layer-version layer="python" >}}`. -- Replace `` with the desired version of the Datadog Lambda Extension. The latest version is `{{< latest-lambda-layer-version layer="extension" >}}`. + **Note**: Instrument your Lambda functions in a dev or staging environment first. If the instrumentation result is unsatisfactory, run `uninstrument` with the same arguments to revert the changes. -For example: + To instrument your Lambda functions, run the following command. -```sh -datadog-ci lambda instrument -f my-function -f another-function -r us-east-1 -v {{< latest-lambda-layer-version layer="python" >}} -e {{< latest-lambda-layer-version layer="extension" >}} -``` + ```sh + datadog-ci lambda instrument -f -f -r -v {{< latest-lambda-layer-version layer="python" >}} -e {{< latest-lambda-layer-version layer="extension" >}} + ``` + + To fill in the placeholders: + - Replace `` and `` with your Lambda function names. Alternatively, you can use `--functions-regex` to automatically instrument multiple functions whose names match the given regular expression. + - Replace `` with the AWS region name. -More information and additional parameters can be found in the [CLI documentation][2]. + Additional parameters can be found in the [CLI documentation][3]. [1]: https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/setting-credentials-node.html -[2]: https://docs.datadoghq.com/serverless/serverless_integrations/cli +[2]: https://docs.datadoghq.com/getting_started/site/ +[3]: https://docs.datadoghq.com/serverless/serverless_integrations/cli {{% /tab %}} {{% tab "Serverless Framework" %}} -The [Datadog Serverless Plugin][1] automatically adds the Datadog Lambda Library to your functions using Lambda Layers, and configures your functions to send metrics, traces, and logs to Datadog through the [Datadog Lambda Extension][2]. +The [Datadog Serverless Plugin][1] automatically configures your functions to send metrics, traces, and logs to Datadog through the [Datadog Lambda Extension][2]. To install and configure the Datadog Serverless Plugin, follow these steps: 1. Install the Datadog Serverless Plugin: + ```sh - npm install serverless-plugin-datadog --save-dev - ``` -2. In your `serverless.yml`, add the following: - ```yaml - plugins: - - serverless-plugin-datadog + serverless plugin install --name serverless-plugin-datadog ``` -
If you are instead deploying your Serverless Framework app by natively exporting a JSON object from a JavaScript file (for example, by using a serverless.ts file), follow the custom installation instructions.
+2. Update your `serverless.yml`: -3. In your `serverless.yml`, also add the following section: ```yaml custom: - datadog: - apiKey: # Your Datadog API Key goes here. + datadog: + site: + apiKeySecretArn: ``` - Find your Datadog API key on the [API Management page][3]. For additional settings, see the [plugin documentation][1]. + To fill in the placeholders: + - Replace `` with your [Datadog site][3] to send the telemetry to. + - Replace `` with the ARN of the AWS secret where your [Datadog API key][4] is securely stored. The key needs to be stored as a plaintext string (not a JSON blob). The `secretsmanager:GetSecretValue` permission is required. For quick testing, you can instead use `apiKey` and set the Datadog API key in plaintext. + + For more information and additional settings, see the [plugin documentation][1]. [1]: https://docs.datadoghq.com/serverless/serverless_integrations/plugin [2]: https://docs.datadoghq.com/serverless/libraries_integrations/extension -[3]: https://app.datadoghq.com/organization-settings/api-keys +[3]: https://docs.datadoghq.com/getting_started/site/ +[4]: https://app.datadoghq.com/organization-settings/api-keys {{% /tab %}} {{% tab "AWS SAM" %}} -The [Datadog CloudFormation macro][1] automatically transforms your SAM application template to add the Datadog Lambda library to your functions using layers, and configures your functions to send metrics, traces, and logs to Datadog through the [Datadog Lambda Extension][2]. +The [Datadog CloudFormation macro][1] automatically transforms your SAM application template to install Datadog on your functions using Lambda layers, and configures your functions to send metrics, traces, and logs to Datadog through the [Datadog Lambda Extension][2]. -### Install +1. Install the Datadog CloudFormation macro -Run the following command with your [AWS credentials][3] to deploy a CloudFormation stack that installs the macro AWS resource. You only need to install the macro **once** for a given region in your account. Replace `create-stack` with `update-stack` to update the macro to the latest version. + Run the following command with your [AWS credentials][3] to deploy a CloudFormation stack that installs the macro AWS resource. You only need to install the macro **once** for a given region in your account. Replace `create-stack` with `update-stack` to update the macro to the latest version. -```sh -aws cloudformation create-stack \ - --stack-name datadog-serverless-macro \ - --template-url https://datadog-cloudformation-template.s3.amazonaws.com/aws/serverless-macro/latest.yml \ - --capabilities CAPABILITY_AUTO_EXPAND CAPABILITY_IAM -``` - -The macro is now deployed and ready to use. + ```sh + aws cloudformation create-stack \ + --stack-name datadog-serverless-macro \ + --template-url https://datadog-cloudformation-template.s3.amazonaws.com/aws/serverless-macro/latest.yml \ + --capabilities CAPABILITY_AUTO_EXPAND CAPABILITY_IAM + ``` -### Instrument + The macro is now deployed and ready to use. -To instrument your function, add the following to `template.yml` under the `Transform` section, **after** the `AWS::Serverless` transform for SAM. +2. Instrument your Lambda functions -```yaml -Transform: - - AWS::Serverless-2016-10-31 - - Name: DatadogServerless - Parameters: - stackName: !Ref 'AWS::StackName' - apiKey: - pythonLayerVersion: { { < latest-lambda-layer-version layer="python" > } } - extensionLayerVersion: { { < latest-lambda-layer-version layer="extension" > } } - service: '' # Optional - env: '' # Optional -``` + Add the `DatadogServerless` transform **after** the `AWS::Serverless` transform under the `Transform` section in your for SAM `template.yml`. -To fill in the placeholders: + ```yaml + Transform: + - AWS::Serverless-2016-10-31 + - Name: DatadogServerless + Parameters: + stackName: !Ref "AWS::StackName" + pythonLayerVersion: {{< latest-lambda-layer-version layer="python" >}} + extensionLayerVersion: {{< latest-lambda-layer-version layer="extension" >}} + site: "" + apiKeySecretArn: "" + ``` -- Replace `` with your Datadog API key from the [API Management page][4]. -- Replace `` and `` with appropriate values. + To fill in the placeholders: + - Replace `` with your [Datadog site][4] to send the telemetry to. + - Replace `` with the ARN of the AWS secret where your [Datadog API key][5] is securely stored. The key needs to be stored as a plaintext string (not a JSON blob). The `secretsmanager:GetSecretValue` permission is required. For quick testing, you can use `apiKey` instead and set the Datadog API key in plaintext. -More information and additional parameters can be found in the [macro documentation][1]. + More information and additional parameters can be found in the [macro documentation][1]. [1]: https://docs.datadoghq.com/serverless/serverless_integrations/macro [2]: https://docs.datadoghq.com/serverless/libraries_integrations/extension [3]: https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html -[4]: https://app.datadoghq.com/organization-settings/api-keys +[4]: https://docs.datadoghq.com/getting_started/site/ +[5]: https://app.datadoghq.com/organization-settings/api-keys {{% /tab %}} {{% tab "AWS CDK" %}} -The [Datadog CDK Construct][1] automatically adds the Datadog Lambda Library to your functions using Lambda Layers, and configures your functions to send metrics, traces, and logs to Datadog through the [Datadog Lambda Extension][2]. +The [Datadog CDK Construct][1] automatically installs Datadog on your functions using Lambda Layers, and configures your functions to send metrics, traces, and logs to Datadog through the Datadog Lambda Extension. -### Install the Datadog CDK constructs library - -Run the following command in your CDK project: - -```sh -#PyPI -pip install datadog-cdk-constructs -``` - -### Instrument the function - -Import the `datadog-cdk-construct` module in your AWS CDK app and add the following configuration: - -```python -from datadog_cdk_constructs import Datadog - -datadog = Datadog(self, "Datadog", - python_layer_version={{< latest-lambda-layer-version layer="python" >}}, - extension_layer_version={{< latest-lambda-layer-version layer="extension" >}}, - api_key= -) -datadog.add_lambda_functions([]) -``` +1. Install the Datadog CDK constructs library -Replace `` with your Datadog API key on the [API Management page][1]. - -More information and additional parameters can be found on the [Datadog CDK NPM page][2]. - - -[1]: https://app.datadoghq.com/organization-settings/api-keys -[2]: https://www.npmjs.com/package/datadog-cdk-constructs -{{% /tab %}} -{{% tab "Zappa" %}} - -### Update settings - -1. Add the following settings to your `zappa_settings.json`: - -{{< site-region region="us,us3,us5,eu" >}} - -```json -{ - "dev": { - "layers": [ - "arn:aws:lambda::464622532012:layer:Datadog-:", - "arn:aws:lambda::464622532012:layer:Datadog-Extension:" - ], - "lambda_handler": "datadog_lambda.handler.handler", - "aws_environment_variables": { - "DD_LAMBDA_HANDLER": "handler.lambda_handler", - "DD_TRACE_ENABLED": "true", - "DD_API_KEY": "" - } - } -} -``` - -{{< /site-region >}} -{{< site-region region="gov" >}} - -```json -{ - "dev": { - "layers": [ - "arn:aws-us-gov:lambda::002406178527:layer:Datadog-:", "arn:aws-us-gov:lambda::002406178527:layer:Datadog-Extension:" - ], - "lambda_handler": "datadog_lambda.handler.handler", - "aws_environment_variables": { - "DD_LAMBDA_HANDLER": "handler.lambda_handler", - "DD_TRACE_ENABLED": "true", - "DD_API_KEY": "" - }, - } - } - ``` -{{< /site-region >}} -2. Replace the following placeholders with appropriate values: - -- Replace `` with the AWS region to which your Lambda functions are deployed. -- Replace `` with the appropriate Python runtime. The available `RUNTIME` options are `Python27`, `Python36`, `Python37`, and `Python38`. -- Replace `` with the desired version of the Datadog Lambda Library. The latest version is `{{< latest-lambda-layer-version layer="python" >}}`. -- Replace `` with the desired version of the Datadog Lambda Extension. The latest version is `{{< latest-lambda-layer-version layer="extension" >}}`. -- Replace `` with your Datadog API key on the [API Management page][1]. -- If the lambda is using the arm64 architecture, add -ARM to the layer name. - -For example: - -{{< site-region region="us,us3,us5,eu" >}} -``` - -// For x86 architecture -arn:aws:lambda:us-east-1:464622532012:layer:Datadog-Python38:{{< latest-lambda-layer-version layer="python" >}} -arn:aws:lambda:us-east-1:464622532012:layer:Datadog-Extension:{{< latest-lambda-layer-version layer="extension" >}} -// For arm64 architecture -arn:aws:lambda:us-east-1:464622532012:layer:Datadog-Python38-ARM:{{< latest-lambda-layer-version layer="python" >}} -arn:aws:lambda:us-east-1:464622532012:layer:Datadog-Extension-ARM:{{< latest-lambda-layer-version layer="extension" >}} - -``` -{{< /site-region >}} -{{< site-region region="gov" >}} -``` - -// For x86 architecture -arn:aws-us-gov:lambda:us-gov-east-1:002406178527:layer:Datadog-Python38:{{< latest-lambda-layer-version layer="python" >}} -arn:aws-us-gov:lambda:us-gov-east-1:002406178527:layer:Datadog-Extension:{{< latest-lambda-layer-version layer="extension" >}} -// For arm64 architecture -arn:aws-us-gov:lambda:us-gov-east-1:002406178527:layer:Datadog-Python38-ARM:{{< latest-lambda-layer-version layer="python" >}} -arn:aws-us-gov:lambda:us-gov-east-1:002406178527:layer:Datadog-Extension-ARM:{{< latest-lambda-layer-version layer="extension" >}} - -``` -{{< /site-region >}} - -[1]: https://app.datadoghq.com/organization-settings/api-keys -{{% /tab %}} -{{% tab "Chalice" %}} - -### Update the project - -1. Add the [Datadog Lambda Extension][1] and the following environment variables in your `config.json`: - {{< site-region region="us,us3,us5,eu" >}} - ```json - { - "version": "2.0", - "app_name": "hello-chalice", - "stages": { - "dev": { - "api_gateway_stage": "api", - "environment_variables": { - "DD_TRACE_ENABLED": "true", - "DD_API_KEY": "", - }, - "layers": ["arn:aws:lambda::464622532012:layer:Datadog-Extension:"], - } - } - } -``` - -{{< /site-region >}} -{{< site-region region="gov" >}} - -```json -{ - "version": "2.0", - "app_name": "hello-chalice", - "stages": { - "dev": { - "api_gateway_stage": "api", - "environment_variables": { - "DD_TRACE_ENABLED": "true", - "DD_API_KEY": "", - }, - "layers": ["arn:aws-us-gov:lambda::002406178527:layer:Datadog-Extension:"], - } - } - ``` - {{< /site-region >}} + ```sh + # For AWS CDK v1 + pip install datadog-cdk-constructs - **Note**: For security, you may wish to store your Datadog API key in AWS Secrets Manager. In this case, set the environment variable `DD_API_KEY_SECRET_ARN` with the ARN of the Secrets Manager secret containing your Datadog API key. In other words, you can replace the line `"DD_API_KEY": ""` in the configuration above with `"DD_API_KEY_SECRET_ARN": ""`. Accessing this key during a cold start adds extra latency. + # For AWS CDK v2 + pip install datadog-cdk-constructs-v2 + ``` -2. Replace the following placeholders with appropriate values: +2. Instrument your Lambda functions -- Replace `` with the AWS region to which your Lambda functions are deployed. -- Replace `` with the desired version of the Datadog Lambda Extension. The latest version is `{{< latest-lambda-layer-version layer="extension" >}}`. -- If the lambda is using the arm64 architecture, add -ARM to the layer name. + ```python + # For AWS CDK v1 + from datadog_cdk_constructs import Datadog -3. Add `datadog_lambda` to your `requirements.txt`. -4. Register `datadog_lambda_wrapper` as a [middleware][2] in your `app.py`: - ```python - from chalice import Chalice, ConvertToMiddleware - from datadog_lambda.wrapper import datadog_lambda_wrapper + # For AWS CDK v2 + from datadog_cdk_constructs_v2 import Datadog - app = Chalice(app_name='hello-chalice') + datadog = Datadog(self, "Datadog", + python_layer_version={{< latest-lambda-layer-version layer="python" >}}, + extension_layer_version={{< latest-lambda-layer-version layer="extension" >}}, + site="", + apiKeySecretArn="", + ) + datadog.add_lambda_functions([]) + ``` - app.register_middleware(ConvertToMiddleware(datadog_lambda_wrapper)) + To fill in the placeholders: + - Replace `` with your [Datadog site][2] to send the telemetry to. + - Replace `` with the ARN of the AWS secret where your [Datadog API key][3] is securely stored. The key needs to be stored as a plaintext string (not a JSON blob). The `secretsmanager:GetSecretValue` permission is required. For quick testing, you can use `apiKey` instead and set the Datadog API key in plaintext. - @app.route('/') - def index(): - return {'hello': 'world'} - ``` + More information and additional parameters can be found on the [Datadog CDK documentation][1]. -[1]: /serverless/libraries_integrations/extension/ -[2]: https://aws.github.io/chalice/topics/middleware.html?highlight=handler#registering-middleware +[1]: https://github.com/DataDog/datadog-cdk-constructs +[2]: https://docs.datadoghq.com/getting_started/site/ +[3]: https://app.datadoghq.com/organization-settings/api-keys {{% /tab %}} -{{% tab "Terraform" %}} - -### Update configurations - -1. Add the following configurations to the `aws_lambda_function` resources in your .tf files: - -{{< site-region region="us,us3,us5,eu" >}} -```hcl -variable "dd_api_key" { -type = string -description = "Datadog API key" -} -resource "aws_lambda_function" "my_func" { -function_name = "my_func" -handler = "datadog_lambda.handler.handler" -layers = [ - "arn:aws:lambda::464622532012:layer:Datadog-:", - "arn:aws:lambda::464622532012:layer:Datadog-Extension:", -] -environment { - variables = { - DD_LAMBDA_HANDLER = "my_func.handler" - DD_TRACE_ENABLED = true - DD_API_KEY = var.dd_api_key - } -} -} -``` - -{{< /site-region >}} -{{< site-region region="gov" >}} - -```hcl -variable "dd_api_key" { - type = string - description = "Datadog API key" -} -resource "aws_lambda_function" "my_func" { - function_name = "my_func" - handler = "datadog_lambda.handler.handler" - layers = [ - "arn:aws-us-gov:lambda::002406178527:layer:Datadog-:", - "arn:aws-us-gov:lambda::002406178527:layer:Datadog-Extension:", - ] - environment { - variables = { - DD_LAMBDA_HANDLER = "my_func.handler" - DD_TRACE_ENABLED = true - DD_API_KEY = var.dd_api_key - } - } -} -``` - -{{< /site-region >}} - -2. Replace the following placeholders with appropriate values: +{{% tab "Container Image" %}} - - Replace `` with the AWS region to which your Lambda functions are deployed. - - Replace `` with the appropriate Python runtime. The available `RUNTIME` options are `Python27`, `Python36`, `Python37`, and `Python38`. - - Replace `` with the desired version of the Datadog Lambda Library. The latest version is `{{< latest-lambda-layer-version layer="python" >}}`. - - Replace `` with the desired version of the Datadog Lambda Extension. The latest version is `{{< latest-lambda-layer-version layer="extension" >}}`. +1. Install the Datadog Lambda Library -3. Apply the Terraform configuration with your Datadog API key that can be found on the [API Management page][1]: + If you are deploying your Lambda function as a container image, you cannot use the Datadog Lambda library as a Lambda Layer. Instead, you must install the Datadog Lambda library as a dependency of your function within the image. - ```bash - terraform apply -var "dd_api_key=" + ```sh + pip install datadog-lambda ``` + Note that the minor version of the `datadog-lambda` package always matches the layer version. For example, `datadog-lambda v0.5.0` matches the content of layer version 5. -[1]: https://app.datadoghq.com/organization-settings/api-keys -{{% /tab %}} -{{% tab "Container Image" %}} +2. Install the Datadog Lambda Extension -### Install + Add the Datadog Lambda Extension to your container image by adding the following to your Dockerfile: -If you are deploying your Lambda function as a container image, you cannot use the Datadog Lambda Library as a Lambda Layer. Instead, you must install the Datadog Lambda library as a dependency of your function within the image. - -```sh -pip install datadog-lambda -``` - -Note that the minor version of the `datadog-lambda` package always matches the layer version. For example, `datadog-lambda v0.5.0` matches the content of layer version 5. - -### Install the Datadog Lambda Extension - -Add the Datadog Lambda Extension to your container image by adding the following to your Dockerfile: + ```dockerfile + COPY --from=public.ecr.aws/datadog/lambda-extension: /opt/extensions/ /opt/extensions + ``` -```dockerfile -COPY --from=public.ecr.aws/datadog/lambda-extension: /opt/extensions/ /opt/extensions -``` + Replace `` with either a specific version number (for example, `{{< latest-lambda-layer-version layer="extension" >}}`) or with `latest`. You can see a complete list of possible tags in the [Amazon ECR repository][1]. -Replace `` with either a specific version number (for example, `{{< latest-lambda-layer-version layer="extension" >}}`) or with `latest`. You can see a complete list of possible tags in the [Amazon ECR repository][1]. +3. Redirect the handler function -### Configure the function + - Set your image's `CMD` value to `datadog_lambda.handler.handler`. You can set this in AWS or directly in your Dockerfile. Note that the value set in AWS overrides the value in the Dockerfile if you set both. + - Set the environment variable `DD_LAMBDA_HANDLER` to your original handler, for example, `myfunc.handler`. -1. Set your image's `CMD` value to `datadog_lambda.handler.handler`. You can set this in AWS or directly in your Dockerfile. Note that the value set in AWS overrides the value in the Dockerfile if you set both. -2. Set the following environment variables in AWS: + **Note**: If you are using a third-party security or monitoring tool that is incompatible with the Datadog handler redirection, you can [apply the Datadog wrapper in your function code][2] instead. -- Set `DD_LAMBDA_HANDLER` to your original handler, for example, `myfunc.handler`. -- Set `DD_TRACE_ENABLED` to `true`. -- Set `DD_API_KEY` with your Datadog API key on the [API Management page][2]. +4. Configure the Datadog site, API key, and tracing -3. Optionally add `service` and `env` tags with appropriate values to your function. + - Set the environment variable `DD_SITE` with your [Datadog site][3] to send the telemetry to. + - Set the environment variable `DD_API_KEY_SECRET_ARN` with the ARN of the AWS secret where your [Datadog API key][4] is securely stored. The key needs to be stored as a plaintext string (not a JSON blob). The `secretsmanager:GetSecretValue` permission is required. For quick testing, you can use `DD_API_KEY` instead and set the Datadog API key in plaintext. + - Set the environment variable `DD_TRACE_ENABLED` to `true`. [1]: https://gallery.ecr.aws/datadog/lambda-extension -[2]: https://app.datadoghq.com/organization-settings/api-keys +[2]: https://docs.datadoghq.com/serverless/guide/handler_wrapper +[3]: https://docs.datadoghq.com/getting_started/site/ +[4]: https://app.datadoghq.com/organization-settings/api-keys {{% /tab %}} {{% tab "Custom" %}} -
If you are not using a serverless development tool that Datadog supports, such as the Serverless Framework or AWS CDK, Datadog strongly encourages you instrument your serverless applications with the Datadog CLI.
+
If you are not using a serverless development tool that Datadog supports, such as the Serverless Framework or AWS CDK, Datadog strongly encourages you instrument your serverless applications with the Datadog CLI.
-### Install the Datadog Lambda library +1. Install the Datadog Lambda library -The Datadog Lambda Library can be imported either as a layer (recommended) _OR_ as a Python package. + The Datadog Lambda Library can be imported either as a layer (recommended) _OR_ as a Python package. -The minor version of the `datadog-lambda` package always matches the layer version. For example, datadog-lambda v0.5.0 matches the content of layer version 5. + The minor version of the `datadog-lambda` package always matches the layer version. For example, datadog-lambda v0.5.0 matches the content of layer version 5. -#### Using the layer + - Option A: [Configure the layers][1] for your Lambda function using the ARN in the following format: -[Configure the layers][1] for your Lambda function using the ARN in the following format: + ```sh + # Use this format for x86-based Lambda deployed in AWS commercial regions + arn:aws:lambda::464622532012:layer:Datadog-:{{< latest-lambda-layer-version layer="python" >}} -{{< site-region region="us,us3,us5,eu" >}} + # Use this format for arm64-based Lambda deployed in AWS commercial regions + arn:aws:lambda::464622532012:layer:Datadog--ARM:{{< latest-lambda-layer-version layer="python" >}} -``` -arn:aws:lambda::464622532012:layer:Datadog-: -``` + # Use this format for x86-based Lambda deployed in AWS GovCloud regions + arn:aws-us-gov:lambda::002406178527:layer:Datadog-:{{< latest-lambda-layer-version layer="python" >}} -{{< /site-region >}} -{{< site-region region="gov" >}} + # Use this format for arm64-based Lambda deployed in AWS GovCloud regions + arn:aws-us-gov:lambda::002406178527:layer:Datadog--ARM:{{< latest-lambda-layer-version layer="python" >}} + ``` -``` -arn:aws-us-gov:lambda::002406178527:layer:Datadog-: -``` + Replace `` with a valid AWS region, such as `us-east-1`. The available `RUNTIME` options are `Python37`, `Python38` and `Python39`. -{{< /site-region >}} + - Option B: If you cannot use the prebuilt Datadog Lambda layer, alternatively install the `datadog-lambda` package and its dependencies locally to your function project folder using your favorite Python package manager, such as `pip`. -The available `RUNTIME` options are `Python27`, `Python36`, `Python37`, and `Python38`. The latest `VERSION` is `{{< latest-lambda-layer-version layer="python" >}}`. For example: + ```sh + pip install datadog-lambda -t ./ + ``` -{{< site-region region="us,us3,us5,eu" >}} + **Note**: `datadog-lambda` depends on `ddtrace`, which uses native extensions; therefore it must be installed and compiled in a Linux environment on the right architecture (`x86_64` or `arm64`). For example, you can use [dockerizePip][2] for the Serverless Framework and [--use-container][3] for AWS SAM. For more details, see [how to add dependencies to your function deployment package][4]. -``` -// If using x86 architecture -arn:aws:lambda:us-east-1:464622532012:layer:Datadog-Python37:{{< latest-lambda-layer-version layer="python" >}} + See the [latest release][5]. -// If using arm64 architecture -arn:aws:lambda:us-east-1:464622532012:layer:Datadog-Python37-ARM:{{< latest-lambda-layer-version layer="python" >}} -``` +2. Install the Datadog Lambda Extension -{{< /site-region >}} -{{< site-region region="gov" >}} + [Configure the layers][1] for your Lambda function using the ARN in the following format: -``` -// If using x86 architecture -arn:aws-us-gov:lambda:us-gov-east-1:002406178527:layer:Datadog-Python37:{{< latest-lambda-layer-version layer="python" >}} -// If using arm64 architecture -arn:aws-us-gov:lambda:us-gov-east-1:002406178527:layer:Datadog-Python37-ARM:{{< latest-lambda-layer-version layer="python" >}} + ```sh + # Use this format for x86-based Lambda deployed in AWS commercial regions + arn:aws:lambda::464622532012:layer:Datadog-Extension:{{< latest-lambda-layer-version layer="extension" >}} -``` + # Use this format for arm64-based Lambda deployed in AWS commercial regions + arn:aws:lambda::464622532012:layer:Datadog-Extension-ARM:{{< latest-lambda-layer-version layer="extension" >}} -{{< /site-region >}} + # Use this format for x86-based Lambda deployed in AWS GovCloud regions + arn:aws-us-gov:lambda::002406178527:layer:Datadog-Extension:{{< latest-lambda-layer-version layer="extension" >}} -#### Using the package + # Use this format for arm64-based Lambda deployed in AWS GovCloud regions + arn:aws-us-gov:lambda::002406178527:layer:Datadog-Extension-ARM:{{< latest-lambda-layer-version layer="extension" >}} + ``` -If you cannot use the prebuilt Datadog Lambda layer for some reason, alternatively install the `datadog-lambda` package and its dependencies locally to your function project folder using your favorite Python package manager, such as `pip`. + Replace `` with a valid AWS region, such as `us-east-1`. -```sh -pip install datadog-lambda -t ./ -``` +3. Redirect the handler function -**Note**: `datadog-lambda` depends on `ddtrace`, which uses native extensions; therefore they must be installed and compiled in a Linux environment on the right architecture (`x86_64` or `arm64`). For example, you can use [dockerizePip][2] for the Serverless Framework and [--use-container][3] for AWS SAM. For more details, see [how to add dependencies to your function deployment package][4]. + - Set your function's handler to `datadog_lambda.handler.handler`. + - Set the environment variable `DD_LAMBDA_HANDLER` to your original handler, for example, `myfunc.handler`. -See the [latest release][5]. + **Note**: If you are using a third-party security or monitoring tool that is incompatible with the Datadog handler redirection, you can [apply the Datadog wrapper in your function code][6] instead. -### Install the Datadog Lambda Extension +4. Configure the Datadog site, API key, and tracing -[Configure the layers][1] for your Lambda function using the ARN in the following format: + - Set the environment variable `DD_SITE` with your [Datadog site][7] to send the telemetry to. + - Set the environment variable `DD_API_KEY_SECRET_ARN` with the ARN of the AWS secret where your [Datadog API key][8] is securely stored. The key needs to be stored as a plaintext string, instead of being inside a json blob. The `secretsmanager:GetSecretValue` permission is required. For quick testings, you can use `DD_API_KEY` instead and set the Datadog API key in plaintext. + - Set the environment variable `DD_TRACE_ENABLED` to `true`. -{{< site-region region="us,us3,us5,eu" >}} +5. (AWS Chalice only) Register the middleware -``` -// For x86 architecture -arn:aws:lambda::464622532012:layer:Datadog-Extension: -// For arm64 architecture -arn:aws:lambda::464622532012:layer:Datadog-Extension-ARM: -``` + If you are using [AWS Chalice][9], you must install `datadog-lambda` using `pip`, and register `datadog_lambda_wrapper` as a [middleware][10] in your `app.py`: + + ```python + from chalice import Chalice, ConvertToMiddleware + from datadog_lambda.wrapper import datadog_lambda_wrapper -{{< /site-region >}} -{{< site-region region="gov" >}} + app = Chalice(app_name='hello-chalice') -``` -// For x86 architecture -arn:aws-us-gov:lambda::002406178527:layer:Datadog-Extension: -// For arm64 architecture -arn:aws-us-gov:lambda::002406178527:layer:Datadog-Extension-ARM: -``` + app.register_middleware(ConvertToMiddleware(datadog_lambda_wrapper)) -{{< /site-region >}} - -The latest `EXTENSION_VERSION` is {{< latest-lambda-layer-version layer="extension" >}}. - -### Configure - -Follow these steps to configure the function: - -1. Set your function's handler to `datadog_lambda.handler.handler`. -2. Set the environment variable `DD_LAMBDA_HANDLER` to your original handler, for example, `myfunc.handler`. -3. Set the environment variable `DD_TRACE_ENABLED` to `true`. -4. Set the environment variable `DD_API_KEY` to your Datadog API key on the [API Management page][6]. -5. Optionally add a `service` and `env` tag with appropriate values to your function. + @app.route('/') + def index(): + return {'hello': 'world'} + ``` [1]: https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html @@ -563,31 +343,29 @@ Follow these steps to configure the function: [3]: https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-build.html [4]: https://docs.aws.amazon.com/lambda/latest/dg/python-package.html#python-package-dependencies [5]: https://pypi.org/project/datadog-lambda/ -[6]: https://app.datadoghq.com/organization-settings/api-keys +[6]: https://docs.datadoghq.com/serverless/guide/handler_wrapper +[7]: https://docs.datadoghq.com/getting_started/site/ +[8]: https://app.datadoghq.com/organization-settings/api-keys +[9]: https://aws.github.io/chalice/ +[10]: https://aws.github.io/chalice/topics/middleware.html {{% /tab %}} {{< /tabs >}} -## Explore Datadog serverless monitoring - -After you have configured your function following the steps above, you can view metrics, logs and traces on the [Serverless Homepage][1]. - -### Unified service tagging - -Datadog recommends tagging your serverless applications with `DD_ENV`, `DD_SERVICE`, `DD_VERSION`, and `DD_TAGS`. See the [Lambda extension documentation][2] for more details. +## What's next? -### Collect logs from AWS serverless resources - -Serverless logs generated by managed resources besides AWS Lambda functions can be hugely valuable in helping identify the root cause of issues in your serverless applications. Datadog recommends you forward logs from the following managed resources in your environment: - -- APIs: API Gateway, AppSync, ALB -- Queues & Streams: SQS, SNS, Kinesis -- Data Stores: DynamoDB, S3, RDS, etc. - -To collect logs from non-Lambda AWS resources, install and configure the [Datadog Forwarder][3] to subscribe to each of your managed resource CloudWatch log groups. +- You can now view metrics, logs, and traces on the [Serverless Homepage][1]. +- See the sample code to [monitor custom business logic](#monitor-custom-business-logic) +- See the [troubleshooting guide][2] if you have trouble collecting the telemetry +- See the [advanced configurations][3] to + - connect your telemetry using tags + - collect telemetry for AWS API Gateway, SQS, etc. + - capture the Lambda request and response payloads + - link errors of your Lambda functions to your source code + - filter or scrub sensitive information from logs or traces ### Monitor custom business logic -If you would like to submit a custom metric or span, see the sample code below: +To monitor your custom business logic, submit a custom metric or span using the sample code below. For additional options, see [custom metric submission for serverless applications][4] and the APM guide for [custom instrumentation][5]. ```python import time @@ -623,22 +401,12 @@ def get_message(): return 'Hello from serverless!' ``` -For more information on custom metric submission, see [here][4]. For additional details on custom instrumentation, see the Datadog APM documentation for [custom instrumentation][5]. - -If your Lambda function is running in a VPC, follow these [instructions][6] to ensure that the extension can reach Datadog API endpoints. - -## Troubleshooting - -If you have trouble collecting monitoring data after following the instructions above, see the [serverless monitoring troubleshooting guide][7]. - ## Further Reading {{< partial name="whats-next/whats-next.html" >}} [1]: https://app.datadoghq.com/functions -[2]: /serverless/libraries_integrations/extension/#tagging -[3]: /logs/guide/forwarder/ +[2]: /serverless/guide/troubleshoot_serverless_monitoring/ +[3]: /serverless/configuration/ [4]: /serverless/custom_metrics?tab=python [5]: /tracing/custom_instrumentation/python/ -[6]: /serverless/libraries_integrations/extension/#vpc -[7]: /serverless/guide/troubleshoot_serverless_monitoring/ diff --git a/content/en/serverless/installation/ruby.md b/content/en/serverless/installation/ruby.md index 60678276c0e78..31eb80cffbf2b 100644 --- a/content/en/serverless/installation/ruby.md +++ b/content/en/serverless/installation/ruby.md @@ -22,288 +22,86 @@ aliases: The [Datadog Forwarder Lambda function][1] is required to ingest AWS Lambda traces, enhanced metrics, custom metrics, and logs. -## Configuration +## Installation -{{< tabs >}} -{{% tab "Datadog CLI" %}} +1. Install the Datadog Lambda Library -The Datadog CLI modifies existing Lambda functions' configurations to enable instrumentation without requiring a new deployment. It is the quickest way to get started with Datadog's serverless monitoring. + The Datadog Lambda Library can be installed as a layer or a gem. For most functions, Datadog recommends installing the library as a layer. If your Lambda function is deployed as a container image, you must install the library as a gem. -You can also add the [instrumentation command](#instrument) to your CI/CD pipelines to enable instrumentation for all your serverless applications. Run the command _after_ your normal serverless application deployment, so that changes made by the Datadog CLI command are not overridden. + The minor version of the `datadog-lambda` gem always matches the layer version. For example, datadog-lambda v0.5.0 matches the content of layer version 5. -### Install + - Option A: [Configure the layers][2] for your Lambda function using the ARN in the following format. -Install the Datadog CLI with NPM: + ``` + # For regular regions + arn:aws:lambda::464622532012:layer:Datadog-Ruby2-7:{{< latest-lambda-layer-version layer="ruby" >}} -```sh -npm install -g @datadog/datadog-ci -``` - -### Configure credentials - -For a quick start, configure Datadog and [AWS credentials][1] using the [instrumentation command](#instrument). For production applications, provide credentials in a more secure manner by using environment variables. For example: - -```bash -export DATADOG_API_KEY="" -export DATADOG_SITE="" # such as datadoghq.com, datadoghq.eu, us3.datadoghq.com or ddog-gov.com -export AWS_ACCESS_KEY_ID="" -export AWS_SECRET_ACCESS_KEY="" -``` - -### Instrument - -**Note**: Instrument your Lambda functions in a dev or staging environment first. If the instrumentation needs to be reverted, run `uninstrument` with the same arguments that was used for instrumentation. - -To instrument your Lambda functions, run the following command: - -```sh -datadog-ci lambda instrument -f -f -r -e -``` - -To fill in the placeholders: - -- Replace `` and `` with your Lambda function names. -- Replace `` with the AWS region name. -- Replace `` with the desired version of the Datadog Lambda Extension. The latest version is `{{< latest-lambda-layer-version layer="extension" >}}`. - -For example: - -```sh -datadog-ci lambda instrument -f my-function -f another-function -r us-east-1 -e {{< latest-lambda-layer-version layer="extension" >}} -``` - -More information and additional parameters can be found in the [CLI documentation][2]. - -### Install the Lambda Library - -The Datadog Lambda Library can be installed as a layer or a gem. For most functions, Datadog recommends installing the library as a layer. If your Lambda function is deployed as a container image, you must install the library as a gem. - -The minor version of the `datadog-lambda` gem always matches the layer version. For example, datadog-lambda v0.5.0 matches the content of layer version 5. - -#### Using the layer - -[Configure the layers][3] for your Lambda function using the ARN in the following format. - -``` -# For commercial regions -arn:aws:lambda::464622532012:layer:Datadog-Ruby2-7:{{< latest-lambda-layer-version layer="ruby" >}} - -# For us-gov regions -arn:aws-us-gov:lambda::002406178527:layer:Datadog-Ruby2-7:{{< latest-lambda-layer-version layer="ruby" >}} -``` - -For example: + # For us-gov regions + arn:aws-us-gov:lambda::002406178527:layer:Datadog-Ruby2-7:{{< latest-lambda-layer-version layer="ruby" >}} + ``` -``` -arn:aws:lambda:us-east-1:464622532012:layer:Datadog-Ruby2-7:{{< latest-lambda-layer-version layer="ruby" >}} -``` - -If your Lambda function is configured to use code signing, you must add Datadog's Signing Profile ARN (`arn:aws:signer:us-east-1:464622532012:/signing-profiles/DatadogLambdaSigningProfile/9vMI9ZAGLc`) to your function's [Code Signing Configuration][4] before you can add the Datadog Lambda library as a layer. -#### Using the gem - -Add the following to your Gemfile: - -```Gemfile -gem 'datadog-lambda' -``` - -To use Datadog APM, you must also add `ddtrace` as a second dependency in your Gemfile. - -```Gemfile -gem 'datadog-lambda' -gem 'ddtrace' -``` - -`ddtrace` contains native extensions that must be compiled for Amazon Linux to work with AWS Lambda. Datadog therefore recommends that you build and deploy your Lambda as a container image. If your function cannot be deployed as a container image and you would like to use Datadog APM, Datadog recommends installing the Lambda Library as a layer instead of as a gem. - -Install `gcc`, `gmp-devel`, and `make` prior to running `bundle install` in your function’s Dockerfile to ensure that the native extensions can be successfully compiled. - -```dockerfile -FROM - -# assemble your container image + Replace `` with a valid AWS region, such as `us-east-1`. -RUN yum -y install gcc gmp-devel make -RUN bundle config set path 'vendor/bundle' -RUN bundle install -``` + - Option B: If you cannot use the prebuilt Datadog Lambda layer, you can add the following to your Gemfile as an alternative: -[1]: https://docs.aws.amazon.com/sdk-for-ruby/v3/developer-guide/setup-config.html -[2]: https://docs.datadoghq.com/serverless/serverless_integrations/cli -[3]: https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html -[4]: https://docs.aws.amazon.com/lambda/latest/dg/configuration-codesigning.html#config-codesigning-config-update -{{% /tab %}} -{{% tab "Serverless Framework" %}} + ```Gemfile + gem 'datadog-lambda' + gem 'ddtrace' + ``` -The [Datadog Serverless Plugin][1] automatically configures your functions to send metrics, traces, and logs to Datadog through the [Datadog Lambda Extension][2]. + `ddtrace` contains native extensions that must be compiled for Amazon Linux to work with AWS Lambda. Datadog therefore recommends that you build and deploy your Lambda as a container image. If your function cannot be deployed as a container image and you would like to use Datadog APM, Datadog recommends installing the Lambda Library as a layer instead of as a gem. -To install and configure the Datadog Serverless Plugin, follow these steps: + Install `gcc`, `gmp-devel`, and `make` prior to running `bundle install` in your function’s Dockerfile to ensure that the native extensions can be successfully compiled. -1. Install the Datadog Serverless Plugin: - ```sh - npm install serverless-plugin-datadog --save-dev - ``` -2. In your `serverless.yml`, add the following: - ```yaml - plugins: - - serverless-plugin-datadog - ``` + ```dockerfile + FROM -
If you are instead deploying your Serverless Framework app by natively exporting a JSON object from a JavaScript file (for example, by using a serverless.ts file), follow the custom installation instructions.
+ # assemble your container image -3. In your `serverless.yml`, also add the following section: - ```yaml - custom: - datadog: - apiKey: # Your Datadog API Key goes here. - ``` - Find your Datadog API key on the [API Management page][3]. For additional settings, see the [plugin documentation][1]. + RUN yum -y install gcc gmp-devel make + RUN bundle config set path 'vendor/bundle' + RUN bundle install + ``` -#### Using the layer - -[Configure the layers][4] for your Lambda function using the ARN in the following format. - -``` -# For commercial regions -arn:aws:lambda::464622532012:layer:Datadog-:{{< latest-lambda-layer-version layer="ruby" >}} - -# For us-gov regions -arn:aws-us-gov:lambda::002406178527:layer:Datadog-:{{< latest-lambda-layer-version layer="ruby" >}} -``` - -The available `RUNTIME` is `Ruby2-7`. For example: - -``` -arn:aws:lambda:us-east-1:464622532012:layer:Datadog-Ruby2-7:{{< latest-lambda-layer-version layer="ruby" >}} -``` +2. Configure your Lambda functions -If your Lambda function is configured to use code signing, you must add Datadog's Signing Profile ARN (`arn:aws:signer:us-east-1:464622532012:/signing-profiles/DatadogLambdaSigningProfile/9vMI9ZAGLc`) to your function's [Code Signing Configuration][5] before you can add the Datadog Lambda library as a layer.`` + Enable Datadog APM and wrap your Lambda handler function using the wrapper provided by the Datadog Lambda library. -In your `serverless.yml`, add your layer for each function: - ```yaml - my-function: - layers: - - # Your lambda layer goes here. - ``` + ```ruby + require 'datadog/lambda' -[1]: https://docs.datadoghq.com/serverless/serverless_integrations/plugin -[2]: https://docs.datadoghq.com/serverless/libraries_integrations/extension -[3]: https://app.datadoghq.com/organization-settings/api-keys -[4]: https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html -[5]: https://docs.aws.amazon.com/lambda/latest/dg/configuration-codesigning.html#config-codesigning-config-update -{{% /tab %}} -{{% tab "Custom" %}} -### Install the Datadog Lambda Extension - -Add the Datadog Lambda Extension layer for your Lambda function using the ARN in the following format: - -{{< site-region region="us,us3,eu" >}} -``` -// For x86 lambdas -arn:aws:lambda::464622532012:layer:Datadog-Extension: -``` -{{< /site-region >}} -{{< site-region region="gov" >}} -``` -// For x86 lambdas -arn:aws-us-gov:lambda::002406178527:layer:Datadog-Extension: -``` -{{< /site-region >}} - -The latest `EXTENSION_VERSION` is {{< latest-lambda-layer-version layer="extension" >}}. - -### Install the Lambda Library - -The Datadog Lambda Library can be installed as a layer or a gem. For most functions, Datadog recommends installing the library as a layer. If your Lambda function is deployed as a container image, you must install the library as a gem. - -The minor version of the `datadog-lambda` gem always matches the layer version. For example, datadog-lambda v0.5.0 matches the content of layer version 5. - -#### Using the layer - -[Configure the layers][1] for your Lambda function using the ARN in the following format. - -``` -# For commercial regions -arn:aws:lambda::464622532012:layer:Datadog-Ruby2-7:{{< latest-lambda-layer-version layer="ruby" >}} - -# For us-gov regions -arn:aws-us-gov:lambda::002406178527:layer:Datadog-Ruby2-7:{{< latest-lambda-layer-version layer="ruby" >}} -``` - -For example: - -``` -arn:aws:lambda:us-east-1:464622532012:layer:Datadog-Ruby2-7:{{< latest-lambda-layer-version layer="ruby" >}} -``` - -If your Lambda function is configured to use code signing, you must add Datadog's Signing Profile ARN (`arn:aws:signer:us-east-1:464622532012:/signing-profiles/DatadogLambdaSigningProfile/9vMI9ZAGLc`) to your function's [Code Signing Configuration][2] before you can add the Datadog Lambda library as a layer. -#### Using the gem - -Add the following to your Gemfile: - -```Gemfile -gem 'datadog-lambda' -``` - -To use Datadog APM, you must also add `ddtrace` as a second dependency in your Gemfile. - -```Gemfile -gem 'datadog-lambda' -gem 'ddtrace' -``` - -`ddtrace` contains native extensions that must be compiled for Amazon Linux to work with AWS Lambda. Datadog therefore recommends that you build and deploy your Lambda as a container image. If your function cannot be deployed as a container image and you would like to use Datadog APM, Datadog recommends installing the Lambda Library as a layer instead of as a gem. - -Install `gcc`, `gmp-devel`, and `make` prior to running `bundle install` in your function’s Dockerfile to ensure that the native extensions can be successfully compiled. - -```dockerfile -FROM - -# assemble your container image - -RUN yum -y install gcc gmp-devel make -RUN bundle config set path 'vendor/bundle' -RUN bundle install -``` -[1]: https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html -[2]: https://docs.aws.amazon.com/lambda/latest/dg/configuration-codesigning.html#config-codesigning-config-update -{{% /tab %}} -{{< /tabs >}} - -### Configure the function - -Enable Datadog APM and wrap your Lambda handler function using the wrapper provided by the Datadog Lambda library. - -```ruby -require 'datadog/lambda' - -Datadog::Lambda.configure_apm do |c| -# Enable the instrumentation -end - -def handler(event:, context:) - Datadog::Lambda.wrap(event, context) do - return { statusCode: 200, body: 'Hello World' } + Datadog::Lambda.configure_apm do |c| + # Enable the instrumentation end -end -``` -### Subscribe + def handler(event:, context:) + Datadog::Lambda.wrap(event, context) do + return { statusCode: 200, body: 'Hello World' } + end + end + ``` -Subscribe the Datadog Forwarder Lambda function to each of your function’s log groups to send metrics, traces and logs to Datadog. +3. Subscribe the Datadog Forwarder to log groups -1. [Install the Datadog Forwarder if you haven't][1]. -2. [Subscribe the Datadog Forwarder to your function's log groups][2]. + Subscribe the Datadog Forwarder Lambda function to each of your function’s log groups to send metrics, traces and logs to Datadog. -### Tag + 1. [Install the Datadog Forwarder if you haven't][1]. + 2. [Subscribe the Datadog Forwarder to your function's log groups][3]. -Although it's optional, Datadog recommends tagging you serverless applications with the `env`, `service`, and `version` tags following the [unified service tagging documentation][3]. -## Explore +## What's next? -After configuring your function following the steps above, view your metrics, logs, and traces on the [Serverless homepage][4]. +- You can now view metrics, logs, and traces on the [Serverless Homepage][4]. +- See the sample code to [monitor custom business logic](#monitor-custom-business-logic) +- See the [troubleshooting guide][5] if you have trouble collecting the telemetry +- See the [advanced configurations][6] to + - connect your telemetry using tags + - collect telemetry for AWS API Gateway, SQS, etc. + - capture the Lambda request and response payloads + - link errors of your Lambda functions to your source code + - filter or scrub sensitive information from logs or traces -## Monitor custom business logic +### Monitor custom business logic If you would like to submit a custom metric or span, see the sample code below: @@ -348,20 +146,17 @@ def some_operation() end ``` -For more information on custom metric submission, see [here][5]. For additional details on custom instrumentation, see the Datadog APM documentation for [custom instrumentation][6]. - -## Troubleshooting - -If you have trouble collecting monitoring data after following the instructions above, see the [serverless monitoring troubleshooting guide][7]. +For more information on custom metric submission, see [Serverless Custom Metrics][7]. For additional details on custom instrumentation, see the Datadog APM documentation for [custom instrumentation][8]. ## Further Reading {{< partial name="whats-next/whats-next.html" >}} [1]: /serverless/forwarder/ -[2]: /logs/guide/send-aws-services-logs-with-the-datadog-lambda-function/#collecting-logs-from-cloudwatch-log-group -[3]: /getting_started/tagging/unified_service_tagging/#aws-lambda-functions +[2]: https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html +[3]: /logs/guide/send-aws-services-logs-with-the-datadog-lambda-function/#collecting-logs-from-cloudwatch-log-group [4]: https://app.datadoghq.com/functions -[5]: /serverless/custom_metrics?tab=ruby -[6]: /tracing/custom_instrumentation/ruby/ -[7]: /serverless/guide/troubleshoot_serverless_monitoring/ +[5]: /serverless/guide/troubleshoot_serverless_monitoring/ +[6]: /serverless/configuration +[7]: /serverless/custom_metrics?tab=ruby +[8]: /tracing/custom_instrumentation/ruby/ diff --git a/content/en/serverless/libraries_integrations/_index.md b/content/en/serverless/libraries_integrations/_index.md index 72e7c8c74f204..1d316e4a29347 100644 --- a/content/en/serverless/libraries_integrations/_index.md +++ b/content/en/serverless/libraries_integrations/_index.md @@ -1,73 +1,44 @@ --- title: Serverless Libraries and Integrations kind: documentation -further_reading: -- link: "/serverless/serverless_integrations/plugin/" - tag: "Datadog Serverless Plugin" - text: "Documentation" -- link: "/serverless/serverless_integrations/macro/" - tag: "Documentation" - text: "Datadog Serverless Macro" -- link: "/serverless/serverless_integrations/cli/" - tag: "Documentation" - text: "Datadog Serverless CLI" aliases: -- /serverless/serverless_integrations + - /serverless/serverless_integrations + - /serverless/datadog_lambda_library/ + - /serverless/libraries_integrations/library/ --- -{{< whatsnext desc="Serverless Libraries & Integrations:" >}} - {{< nextlink href="/serverless/libraries_integrations/extension/" >}}Datadog Lambda Extension{{< /nextlink >}} - {{< nextlink href="/serverless/libraries_integrations/library/" >}}Datadog Lambda Library{{< /nextlink >}} - {{< nextlink href="/serverless/libraries_integrations/plugin/" >}}Datadog Lambda Plugin{{< /nextlink >}} - {{< nextlink href="/serverless/libraries_integrations/macro/" >}}Datadog Lambda Macro{{< /nextlink >}} +## Serverless Development Tool Integrations + +{{< whatsnext desc="Datadog integrates with popular serverless development tools to install the Datadog Lambda extension and library to your applications automatically." >}} + {{< nextlink href="/serverless/libraries_integrations/plugin/" >}}Datadog Plugin for Serverless Framework{{< /nextlink >}} {{< nextlink href="/serverless/libraries_integrations/cli/" >}}Datadog Lambda CLI{{< /nextlink >}} - {{< nextlink href="/serverless/libraries_integrations/lambda_code_signing/" >}}Lambda Code Signing{{< /nextlink >}} + {{< nextlink href="/serverless/libraries_integrations/cdk/" >}}Datadog Construct for AWS CDK{{< /nextlink >}} + {{< nextlink href="/serverless/libraries_integrations/macro/" >}}Datadog Serverless Macro for AWS SAM{{< /nextlink >}} {{< /whatsnext >}} -## AWS Step Functions - -Enable the [AWS Step Functions integration][1] to automatically get additional tags on your Lambda metrics to identify which state machines a particular function belongs to. Use these tags to get an aggregated view of your Lambda metrics and logs per Step Function on the [Serverless view][2]. - -1. Install the [AWS Step Functions integration][1]. -2. Add the following permissions to your [Datadog IAM policy][3] to add additional tags to your Lambda metrics. - - | AWS Permission | Description | - | ------------------ | -------------------------------------------- | - | `states:ListStateMachines` | List active Step Functions. | - | `states:DescribeStateMachine` | Get Step Function metadata, and tags. | -3. Configure [distributed tracing and logging][1] for AWS Step Functions. -4. Once done, go to the [Serverless Homepage][4] and filter your Lambda functions by `statemachinename`, `statemachinearn` or `stepname`. - -{{< img src="serverless/step-function-trace.jpeg" alt="AWS Step Function Tracing" >}} - -## Amazon EFS for Lambda - -Enable [Amazon EFS for Lambda][5] to automatically get additional tags on your Lambda metrics to identify which EFS a particular function belongs to. Use these tags to get an aggregated view of your Lambda metrics and logs per EFS on the [Serverless view][6]. +## Datadog Lambda Extension and Forwarder -1. Install the [Amazon EFS integration][7]. -2. Add the following permissions to your [Datadog IAM policy][3] to collect EFS metrics from Lambda. - - | AWS Permission | Description | - | ------------------ | -------------------------------------------- | - | `elasticfilesystem:DescribeAccessPoints` | Lists active EFS connected to Lambda functions. | - -3. Once done, go to the [Serverless view][2] to use the new `filesystemid` tag on your Lambda functions. - -{{< img src="integrations/amazon_lambda/efs_for_lambda.mp4" alt="Amazon EFS for Lambda" video=true >}} - -## Lambda@Edge - -Use the `at_edge`, `edge_master_name`, and `edge_master_arn` tags to get an aggregated view of your Lambda function metrics and logs as they run in Edge locations. +{{< whatsnext desc="You need either the Lambda extension or the Forwarder to send telemetry from your Lambda functions. You may also need the Forwarder to collect logs for non-Lambda serverless resources, such as AWS API Gateway." >}} + {{< nextlink href="/serverless/libraries_integrations/extension/" >}}Datadog Lambda Extension{{< /nextlink >}} + {{< nextlink href="https://github.com/DataDog/datadog-serverless-functions/tree/master/aws/logs_monitoring" >}}Datadog Forwarder Lambda Function{{< /nextlink >}} +{{< /whatsnext >}} -## Further Reading +## Datadog Lambda Libraries -{{< partial name="whats-next/whats-next.html" >}} +{{< whatsnext desc="Certain runtime requires the Datadog Lambda library in addition to the Datadog Lambda extension to collect the telemetry." >}} + {{< nextlink href="https://github.com/DataDog/datadog-lambda-python" >}}Datadog Lambda Library for Python{{< /nextlink >}} + {{< nextlink href="https://github.com/DataDog/datadog-lambda-js" >}}Datadog Lambda Library for Node.js{{< /nextlink >}} + {{< nextlink href="https://github.com/DataDog/datadog-lambda-go" >}}Datadog Lambda Library for Go{{< /nextlink >}} + {{< nextlink href="https://github.com/DataDog/datadog-lambda-rb" >}}Datadog Lambda Library for Ruby{{< /nextlink >}} +{{< /whatsnext >}} +## Datadog AWS Integration -[1]: /integrations/amazon_step_functions/ -[2]: https://app.datadoghq.com/functions -[3]: /integrations/amazon_web_services/#installation -[4]: /serverless/serverless_integrations/macro/ -[5]: /integrations/amazon_efs/#amazon-efs-for-lambda -[6]: /serverless/serverless_integrations/plugin/ -[7]: /integrations/amazon_efs/ +{{< whatsnext desc="In addition to collecting telemetry directly from your Lambda functions, Datadog can also collect telemetry through the Datadog AWS integration for resources utilized by your serverless application." >}} + {{< nextlink href="/integrations/amazon_lambda/" >}}AWS Lambda Integration{{< /nextlink >}} + {{< nextlink href="/integrations/amazon_step_functions/" >}}AWS Step Functions Integration{{< /nextlink >}} + {{< nextlink href="/integrations/amazon_appsync/" >}}AWS AppSync Integration{{< /nextlink >}} + {{< nextlink href="/integrations/amazon_api_gateway/" >}}AWS API Gateway Integration{{< /nextlink >}} + {{< nextlink href="/integrations/amazon_sqs/" >}}AWS SQS Integration{{< /nextlink >}} + {{< nextlink href="/integrations/amazon_sns/" >}}AWS SNS Integration{{< /nextlink >}} +{{< /whatsnext >}} \ No newline at end of file diff --git a/content/en/serverless/libraries_integrations/extension.md b/content/en/serverless/libraries_integrations/extension.md deleted file mode 100644 index c65997e8dd3ef..0000000000000 --- a/content/en/serverless/libraries_integrations/extension.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: Datadog Lambda Extension -kind: documentation -further_reading: - - link: 'serverless/custom_metrics' - tag: 'Documentation' - text: 'Submitting Custom Metrics from AWS Lambda' - - link: 'https://www.datadoghq.com/blog/aws-graviton2-lambda-monitoring/' - tag: 'Blog' - text: 'AWS Lambda Functions running on AWS Graviton2 processors' -aliases: - - /serverless/datadog_lambda_library/extension/ - - /serverless/guide/extension_private_link/ ---- - -## Overview - -AWS Lambda extensions are companion processes that augment your Lambda functions. They run within the Lambda execution environment, alongside your Lambda function code. The Datadog extension is a lightweight version of the Datadog Agent built to run alongside your code with minimal performance overhead. - -{{< img src="serverless/serverless_monitoring_installation_instructions.png" alt="Instrument AWS Serverless Applications" style="width:100%;">}} - -The Datadog Lambda Extension is responsible for: -- Pushing real-time [enhanced Lambda metrics][1], [custom metrics][2], and [traces][3] from the Datadog Lambda Library to Datadog. -- Forwarding logs from your Lambda function to Datadog. - -The Datadog extension submits custom metrics, enhanced metrics, traces, and logs [asynchronously][4]. Submitting Lambda logs with the extension is supported in all Lambda runtimes. Submitting custom metrics, enhanced metrics and traces is supported in Node.js, Python, Go, and .NET Lambda runtimes. - -## Installation - -To install the Datadog Lambda Extension, instrument your AWS serverless applications, and review supported runtimes, see the [serverless installation instructions][5]. - -## Log collection - -To disable submission of your AWS Lambda logs to Datadog using the extension, set the environment variable `DD_SERVERLESS_LOGS_ENABLED` to `false` in your Lambda function. - -To exclude the `START` and `END` logs, set the environment variable `DD_LOGS_CONFIG_PROCESSING_RULES` to `[{"type": "exclude_at_match", "name": "exclude_start_and_end_logs", "pattern": "(START|END) RequestId"}]`. Alternatively, you can add a `datadog.yaml` file in your project root directory with the following content: - -```yaml -logs_config: - processing_rules: - - type: exclude_at_match - name: exclude_start_and_end_logs - pattern: (START|END) RequestId -``` - -Datadog recommends keeping the `REPORT` logs, as they are used to populate the invocations list in the serverless function views. - -To scrub or filter other logs before sending them to Datadog, see [Advanced Log Collection][6]. - - -## Trace collection - -To disable submission of your AWS Lambda traces to Datadog using the extension, set the environment variable `DD_TRACE_ENABLED` to `false` in your Lambda function. - -To filter traces before sending them to Datadog, see [Ignoring Unwanted Resources in APM][7]. - -To scrub trace attributes for data security, see [Configure the Datadog Agent or Tracer for Data Security][8]. - -## Tagging - -When using the Extension, Datadog recommends you apply tags by adding the following environment variables to your Lambda functions: - -- `DD_ENV`: This sets the `env` tag in Datadog. Use it to separate out your staging, development, and production environments. -- `DD_SERVICE`: This sets the `service` tag in Datadog. Use it to group related Lambda functions into a service. -- `DD_VERSION`: This sets the `version` tag in Datadog. Use it to enable [Deployment Tracking][9]. -- `DD_TAGS`: This sets custom tags in Datadog. Must be a list of `:` separated by commas such as: `layer:api,team:intake`. - -If you have the Datadog AWS integration enabled, any AWS resource tag applied to your AWS Lambda function also gets applied in Datadog automatically. - -## VPC - -The Datadog Lambda Extension needs access to public internet to send data to Datadog. If your Lambda functions are deployed in a VPC private subnet without access to public internet, see the options below. - -### Using AWS PrivateLink - -If you are sending data to the Datadog site US1, then you can [send data over AWS PrivateLink][10]. See [Datadog Sites][11] if you are unsure about your Datadog site. - -### Using a proxy - -If you are sending data to a Datadog site that is _NOT_ hosted on AWS, such as EU1, then you need to [send data over a proxy][12]. - -## Overhead - -The Datadog Lambda Extension introduces a small amount of overhead to your Lambda function's cold starts (that is, the higher init duration), as the Extension needs to initialize. Datadog is continuously optimizing the Lambda extension performance and recommend always using the latest release. - -You may notice an increase of your Lambda function's reported duration. This is because the Datadog Lambda Extension needs to flush data back to the Datadog API. Although the time spent by the extension flushing data is reported as part of the duration, it's done *after* AWS returns your function's response back to the client. In other words, the added duration does not slow down your Lambda function. See this [AWS blog post][13] for more technical information. To monitor your function's actual performance and exclude the duration added by the Datadog extension, use the metric `aws.lambda.enhanced.runtime_duration`. - -By default, the Extension sends data back to Datadog at the end of each invocation. This avoids delays of data arrival for sporadic invocations from low-traffic applications, cron jobs, and manual tests. Once the Extension detects a steady and frequent invocation pattern (more than once per minute), it batches data from multiple invocations and flushes periodically at the beginning of the invocation when it's due. This means that *the busier your function is, the lower the average duration overhead per invocation*. - -For Lambda functions deployed in a region that is far from the Datadog site, for example, a Lambda function deployed in eu-west-1 reporting data to the US1 Datadog site, can observe a higher duration overhead due to the network latency. - - -## Further Reading - -{{< partial name="whats-next/whats-next.html" >}} - -[1]: /serverless/enhanced_lambda_metrics -[2]: /serverless/custom_metrics -[3]: /serverless/distributed_tracing -[4]: /serverless/custom_metrics?tab=python#synchronous-vs-asynchronous-custom-metrics -[5]: /serverless/installation -[6]: /agent/logs/advanced_log_collection/ -[7]: /tracing/guide/ignoring_apm_resources/ -[8]: /tracing/setup_overview/configure_data_security/ -[9]: /tracing/deployment_tracking/ -[10]: /agent/guide/private-link/ -[11]: /getting_started/site/ -[12]: /agent/proxy/ -[13]: https://aws.amazon.com/blogs/compute/performance-and-functionality-improvements-for-aws-lambda-extensions/ diff --git a/content/en/serverless/libraries_integrations/lambda_code_signing.md b/content/en/serverless/libraries_integrations/lambda_code_signing.md deleted file mode 100644 index 55375fb786de3..0000000000000 --- a/content/en/serverless/libraries_integrations/lambda_code_signing.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Lambda Code Signing -kind: documentation ---- - -[Code signing for AWS Lambda][1] helps to ensure that only trusted code is deployed from your Lambda functions to AWS. When you enable code signing on your functions, AWS validates that all of the code in your deployments is signed by a trusted source, which you define from your [Code Signing Configuration][2]. - -# Configuration - -If your Lambda functions are configured to use code signing, you must add Datadog's Signing Profile ARN (`arn:aws:signer:us-east-1:464622532012:/signing-profiles/DatadogLambdaSigningProfile/9vMI9ZAGLc`) to your function's [Code Signing Configuration][2] before you can deploy Lambda functions using Lambda Layers published by Datadog. The following libraries & integrations add Lambda Layers to your functions: -- [Datadog Lambda Library][3] -- [Datadog Lambda Extension][4] -- [Datadog Serverless Plugin][5] -- [Datadog CloudFormation Macro][6] -- [Datadog CLI][7] -- [Datadog CDK Construct Library][8] - -[1]: https://docs.aws.amazon.com/lambda/latest/dg/configuration-codesigning.html -[2]: https://docs.aws.amazon.com/lambda/latest/dg/configuration-codesigning.html#config-codesigning-config-updates -[3]: /serverless/libraries_integrations/library -[4]: /serverless/libraries_integrations/extension -[5]: /serverless/libraries_integrations/plugin -[6]: /serverless/libraries_integrations/macro -[7]: /serverless/libraries_integrations/cli -[8]: https://www.npmjs.com/package/datadog-cdk-constructs diff --git a/content/en/serverless/libraries_integrations/library.md b/content/en/serverless/libraries_integrations/library.md deleted file mode 100644 index b23498239334d..0000000000000 --- a/content/en/serverless/libraries_integrations/library.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: Datadog Lambda Library -kind: documentation -further_reading: -- link: "/serverless/libraries_integrations/extension/" - tag: "Documentation" - text: "Datadog Lambda Extension" -- link: "https://github.com/DataDog/datadog-lambda-python/blob/master/README.md" - tag: "Github" - text: "Datadog Lambda Library for Python" -- link: "https://github.com/DataDog/datadog-lambda-js/blob/master/README.md" - tag: "Github" - text: "Datadog Lambda Library for Node.js" -- link: "https://github.com/DataDog/datadog-lambda-rb/blob/master/README.md" - tag: "Github" - text: "Datadog Lambda Library for Ruby" -- link: "https://github.com/DataDog/datadog-lambda-go/blob/master/README.md" - tag: "Github" - text: "Datadog Lambda Library for Go" -- link: "https://github.com/DataDog/datadog-lambda-java/blob/master/README.md" - tag: "Github" - text: "Datadog Lambda Library for Java" -- link: "https://www.datadoghq.com/blog/function-urls-monitoring/" - tag: "Blog" - text: "Monitoring AWS Lambda Function URLs with Datadog" -aliases: - - /serverless/datadog_lambda_library/ ---- - -{{< img src="serverless/datadog_lambda_library.png" alt="Datadog Lambda Library" style="width:100%;">}} - -The Datadog Lambda Library is responsible for: - -- Generating real-time [enhanced Lambda metrics][1] for invocations, errors, cold starts, estimated costs, etc. -- Submitting [custom metrics][2] (synchronously and asynchronously). -- Enabling [Datadog APM and Distributed Tracing][3] for Node.js, Python, and Ruby. - -If you are using the Datadog Lambda library for **Ruby**, you **must** also install and configure the Datadog Forwarder to ingest traces, enhanced Lambda metrics, or custom metrics (asynchronously) from your Lambda functions. -If you are using the Datadog Lambda library for **Python**, **Node**, **Go**, **Java**, or **.NET**, you may use the [Datadog Lambda Extension][4] to ingest traces, enhanced Lambda metrics, or custom metrics. Alternatively, you may continue to use the Datadog Forwarder. - -The Datadog Lambda Library is **NOT** responsible for collecting: - -- Lambda metrics from CloudWatch (see [AWS Lambda Integration][5]) -- Lambda traces from X-Ray (see [AWS X-Ray integration][6]) -- Lambda logs from CloudWatch (see [Datadog Forwarder][7]) - -Datadog distributes the Lambda library as a package for Python, Node.js, Ruby, Go, and Java. Packages are installed through the common package managers, such as pip, npm, gem, maven, etc. - -The Datadog Lambda library is also available as a [Lambda layer][8] for Python, Node.js, and Ruby. - -To install the Datadog Lambda library and instrument your serverless applications, see the [installation instructions][9]. - -## Further Reading - -{{< partial name="whats-next/whats-next.html" >}} - - -[1]: /serverless/enhanced_lambda_metrics/ -[2]: /serverless/custom_metrics/ -[3]: /tracing/ -[4]: /serverless/libraries_integrations/extension/ -[5]: /integrations/amazon_lambda/ -[6]: /integrations/amazon_xray/ -[7]: /serverless/forwarder/ -[8]: https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html -[9]: /serverless/installation/ diff --git a/content/en/serverless/troubleshooting/_index.md b/content/en/serverless/troubleshooting/_index.md index ce5243ddb1194..0cd8bf7ab8cab 100644 --- a/content/en/serverless/troubleshooting/_index.md +++ b/content/en/serverless/troubleshooting/_index.md @@ -5,40 +5,40 @@ further_reading: - link: '/serverless/installation/' tag: 'Documentation' text: 'Installing Serverless Monitoring' -- link: '/serverless/guide/' +- link: '/serverless/guide/#troubleshoot-your-installation' tag: 'Documentation' text: 'Troubleshoot Common Issues' aliases: - /serverless/guide/troubleshoot_serverless_monitoring --- -This guide helps you troubleshoot general data collection issues for serverless monitoring, such as missing metrics, traces, logs, or tags. Check out more [troubleshooting guides][1] for issues such as the function code size is too large or about webpack compatibility. +
Check out the additional troubleshooting guides for common issues such as the function code size is too large or webpack compatibility. This guide helps you troubleshoot general telemetry collection issues.
## Understand the basics -To better understand the instructions from this guide, familiarize yourself with the [key concepts][2] first. A better understanding on how things work helps you identify the missing pieces and narrow down probable causes. +To better understand the instructions from this guide, familiarize yourself with the [key concepts][1] first. A better understanding on how things work helps you identify the missing pieces and narrow down probable causes. ## Use the Datadog Lambda Extension instead of the Forwarder -If you are still using the [Datadog Forwarder Lambda function][3] for data collection, consider adopting the [Datadog Lambda Extension][4] instead. Because the technical limitations of the Forwarder Lambda cause a number of known issues, migrating to the Lambda Extension can resolve them automatically. +If you are still using the [Datadog Forwarder Lambda function][2] for data collection, consider adopting the [Datadog Lambda Extension][3] instead. Because the technical limitations of the Forwarder Lambda cause a number of known issues, migrating to the Lambda Extension can resolve them automatically. -* If you are unsure whether your Lambda is using the Extension, check your Lambda function's [layer configurations][5] and see if any Lambda layer is named `Datadog-Extension`. +* If you are unsure whether your Lambda is using the Extension, check your Lambda function's [layer configurations][4] and see if any Lambda layer is named `Datadog-Extension`. -* If you are unsure whether your Lambda is using the Forwarder, check the [subscription filters][6] of your Lambda function's log group, and see if the log group is subscribed by a Lambda named `Datadog Forwarder` or something similar. +* If you are unsure whether your Lambda is using the Forwarder, check the [subscription filters][5] of your Lambda function's log group, and see if the log group is subscribed by a Lambda named `Datadog Forwarder` or something similar. -See this [comparison guide][7] to understand the benefits of using the Extension and this [migration guide][8] for the general migration steps. Test your changes in a dev or staging environment first! +See this [comparison guide][6] to understand the benefits of using the Extension and this [migration guide][7] for the general migration steps. Test your changes in a dev or staging environment first! -To continue using the Forwarder, see this [Forwarder troubleshooting guide][9] for more help. +To continue using the Forwarder, see this [Forwarder troubleshooting guide][8] for more help. ## Ensure the configurations are up-to-date and expected -Check out the [installation guides][10] with up-to-date instructions about applications you may have configured for Datadog monitoring in the past. +Check out the [installation guides][9] with up-to-date instructions about applications you may have configured for Datadog monitoring in the past. To ensure the actual changes made to your Lambda functions are expected, try setting up another testing function and configuring it following the instructions for _Datadog CLI_ or _Custom_. Compare the changes (such as handler, layers, environment variables, and tags) made on your real Lambda functions against the testing one. ## Collect debugging logs -Enable verbose debugging logs by setting the environment variable `DD_LOG_LEVEL` to `debug` on your Lambda functions. If you are using the [Datadog Forwarder Lambda function][3] for data forwarding from logs, also set `DD_LOG_LEVEL` to `debug` on the Forwarder Lambda function. +Enable verbose debugging logs by setting the environment variable `DD_LOG_LEVEL` to `debug` on your Lambda functions. If you are using the [Datadog Forwarder Lambda function][2] for data forwarding from logs, also set `DD_LOG_LEVEL` to `debug` on the Forwarder Lambda function. If you have issues with tracing, set the environment variable `DD_TRACE_DEBUG` to `true` for extra debugging logs from the Datadog Tracer. @@ -46,19 +46,19 @@ To avoid unnecessary costs, disable the debugging logs after you collect enough ## Check the AWS integration -Datadog can collect metrics and resource tags from AWS through an [integration with AWS][11] (optional). If you are missing certain metrics from CloudWatch and Lambda resource tags, ensure that the AWS integration is properly configured. +Datadog can collect metrics and resource tags from AWS through an [integration with AWS][10] (optional). If you are missing certain metrics from CloudWatch and Lambda resource tags, ensure that the AWS integration is properly configured. ## Ensure the tags are configured If you have trouble applying the Datadog standard `service`, `env`, and `version` tags to the collected data, make sure the environment variables `DD_SERVICE`, `DD_ENV`, and `DD_VERSION` are configured on your Lambda functions. For custom tags, ensure `DD_TAGS` is configured. -If you want to enrich the data collected with your AWS Lambda resource tags, make sure the [Datadog integration for AWS][11] is properly configured. +If you want to enrich the data collected with your AWS Lambda resource tags, make sure the [Datadog integration for AWS][10] is properly configured. ## Get help -For quick questions, post in the _#serverless_ channel of the [Datadog Slack community][12]. +For quick questions, post in the _#serverless_ channel of the [Datadog Slack community][11]. -If you have followed all the troubleshooting steps above and want help from [Datadog Support][13], include the following information in your ticket: +If you have followed all the troubleshooting steps above and want help from [Datadog Support][12], include the following information in your ticket: 1. Basic information about your Lambda function:ARN, runtime, handler, layers, environment variables, and tags. Focus on one function first if you have the same issue with many. 1. If the Lambda function is configured to send data through logs using the Datadog Forwarder Lambda function, include basic information about the Forwarder Lambda function, as well as the subscription filters configured on your Lambda function's log group. @@ -72,16 +72,15 @@ If you have followed all the troubleshooting steps above and want help from [Dat {{< partial name="whats-next/whats-next.html" >}} -[1]: /serverless/guide/ -[2]: /serverless/glossary/#datadog-serverless-for-aws-lambda-concepts -[3]: /logs/guide/forwarder/ -[4]: /serverless/libraries_integrations/extension/ -[5]: https://docs.aws.amazon.com/lambda/latest/dg/invocation-layers.html -[6]: https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/SubscriptionFilters.html -[7]: /serverless/guide/extension_motivation/ -[8]: /serverless/guide/forwarder_extension_migration/ -[9]: /logs/guide/lambda-logs-collection-troubleshooting-guide/ -[10]: /serverless/installation/ -[11]: /integrations/amazon_web_services/ -[12]: https://chat.datadoghq.com/ -[13]: https://www.datadoghq.com/support/ +[1]: /serverless/glossary/#datadog-serverless-for-aws-lambda-concepts +[2]: /logs/guide/forwarder/ +[3]: /serverless/libraries_integrations/extension/ +[4]: https://docs.aws.amazon.com/lambda/latest/dg/invocation-layers.html +[5]: https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/SubscriptionFilters.html +[6]: /serverless/guide/extension_motivation/ +[7]: /serverless/configuration/#migrate-to-the-datadog-lambda-extension +[8]: /logs/guide/lambda-logs-collection-troubleshooting-guide/ +[9]: /serverless/installation/ +[10]: /integrations/amazon_web_services/ +[11]: https://chat.datadoghq.com/ +[12]: https://www.datadoghq.com/support/ diff --git a/content/en/tracing/setup_overview/setup/python.md b/content/en/tracing/setup_overview/setup/python.md index 6615aa7f26c6c..1f4bcdd5b9a0c 100644 --- a/content/en/tracing/setup_overview/setup/python.md +++ b/content/en/tracing/setup_overview/setup/python.md @@ -32,7 +32,7 @@ The Python library supports CPython versions 2.7 and 3.5-3.10 on Linux, MacOS an ### Follow the in-app documentation (recommended) -Follow the [Quickstart instructions][3] within the Datadog app for the best experience, including: +Follow the [Quickstart instructions][2] within the Datadog app for the best experience, including: - Step-by-step instructions scoped to your deployment configuration (hosts, Docker, Kubernetes, or Amazon ECS). - Dynamically set `service`, `env`, and `version` tags. @@ -60,7 +60,7 @@ ddtrace-run python app.py ### Upgrading to v1 -If you are upgrading to ddtrace v1, review the [upgrade guide][9] and the [release notes][10] in the library documentation for full details. +If you are upgrading to ddtrace v1, review the [upgrade guide][3] and the [release notes][4] in the library documentation for full details. ### Configure the Datadog Agent for APM @@ -157,11 +157,11 @@ For other environments, please refer to the [Integrations][5] documentation for Once you've finished setup and are running the tracer with your application, you can run `ddtrace-run --info` to check that configurations are working as expected. Note that the output from this command does not reflect configuration changes made during runtime in code. -For more advanced usage, configuration, and fine-grain control, see Datadog's [API documentation][3]. +For more advanced usage, configuration, and fine-grain control, see Datadog's [API documentation][2]. ## Configuration -When using **ddtrace-run**, the following [environment variable options][4] can be used: +When using **ddtrace-run**, the following [environment variable options][5] can be used: `DD_TRACE_DEBUG` : **Default**: `false`
@@ -170,13 +170,13 @@ Enable debug logging in the tracer. `DD_PATCH_MODULES` : Override the modules patched for this application execution. Follow the format: `DD_PATCH_MODULES=module:patch,module:patch...` -It is recommended to use `DD_ENV`, `DD_SERVICE`, and `DD_VERSION` to set `env`, `service`, and `version` for your services. Refer to the [Unified Service Tagging][5] documentation for recommendations on how to configure these environment variables. +It is recommended to use `DD_ENV`, `DD_SERVICE`, and `DD_VERSION` to set `env`, `service`, and `version` for your services. Refer to the [Unified Service Tagging][6] documentation for recommendations on how to configure these environment variables. `DD_ENV` -: Set the application’s environment, for example: `prod`, `pre-prod`, `staging`. Learn more about [how to setup your environment][6]. Available in version 0.38+. +: Set the application’s environment, for example: `prod`, `pre-prod`, `staging`. Learn more about [how to setup your environment][7]. Available in version 0.38+. `DD_SERVICE` -: The service name to be used for this application. The value is passed through when setting up middleware for web framework integrations like Pylons, Flask, or Django. For tracing without a web integration, it is recommended that you set the service name in code ([for example, see these Django docs][7]). Available in version 0.38+. +: The service name to be used for this application. The value is passed through when setting up middleware for web framework integrations like Pylons, Flask, or Django. For tracing without a web integration, it is recommended that you set the service name in code ([for example, see these Django docs][8]). Available in version 0.38+. `DD_SERVICE_MAPPING` : Define service name mappings to allow renaming services in traces, for example: `postgres:postgresql,defaultdb:postgresql`. Available in version 0.47+. @@ -221,7 +221,7 @@ Override the port that the default tracer submits DogStatsD metrics to. `DD_LOGS_INJECTION` : **Default**: `false`
-Enable [connecting logs and trace injection][8]. +Enable [connecting logs and trace injection][9]. ## Further Reading @@ -229,12 +229,11 @@ Enable [connecting logs and trace injection][8]. {{< partial name="whats-next/whats-next.html" >}} [1]: /tracing/compatibility_requirements/python -[2]: /tracing/profiler/enabling/?tab=python -[3]: https://app.datadoghq.com/apm/docs -[4]: https://ddtrace.readthedocs.io/en/stable/advanced_usage.html#ddtracerun -[5]: /getting_started/tagging/unified_service_tagging -[6]: /tracing/guide/setting_primary_tags_to_scope/ -[7]: https://ddtrace.readthedocs.io/en/stable/integrations.html#django -[8]: /tracing/connect_logs_and_traces/python/ -[9]: https://ddtrace.readthedocs.io/en/stable/upgrading.html#upgrade-0-x -[10]: https://ddtrace.readthedocs.io/en/stable/release_notes.html#v1-0-0 +[2]: https://app.datadoghq.com/apm/docs +[3]: https://ddtrace.readthedocs.io/en/stable/upgrading.html#upgrade-0-x +[4]: https://ddtrace.readthedocs.io/en/stable/release_notes.html#v1-0-0 +[5]: https://ddtrace.readthedocs.io/en/stable/advanced_usage.html#ddtracerun +[6]: /getting_started/tagging/unified_service_tagging +[7]: /tracing/guide/setting_primary_tags_to_scope/ +[8]: https://ddtrace.readthedocs.io/en/stable/integrations.html#django +[9]: /tracing/connect_logs_and_traces/python/ diff --git a/content/en/tracing/visualization/service.md b/content/en/tracing/visualization/service.md index 287ba3498d407..f1f36a5886153 100644 --- a/content/en/tracing/visualization/service.md +++ b/content/en/tracing/visualization/service.md @@ -136,7 +136,7 @@ You can add columns to or remove columns from this overview table and your selec {{< img src="tracing/visualization/service/deployments.png" alt="Deployments" style="width:90%;">}} -Read more about Deployments on the service page [here][12]. +Read more about Deployments [on the service page][12]. ### Error Tracking View issues on your service, which are similar errors aggregated together to turn a noisy stream of errors into manageable issues and help you assess the impact of your service’s errors. Read more about issues in [Error Tracking][4]) @@ -160,7 +160,7 @@ If runtime metrics are enabled in the tracing client, you’ll see a Runtime met {{< img src="tracing/visualization/service/runtime_metrics.png" alt="Runtime Metrics" style="width:90%;">}} ### Profiling -You'll see a Profiling tab if the [Continuous Profiler][14] is set up for your service. Summary details like versions available and runtime language are at the top. Below are out-of-the-box profiling metrics by version, endpoint, and method to help you identify and debug resource-intensive methods. Click on any graph to view related traces, logs, and other data, or open a flame graph to inspect the code profile. Learn more about APM and the Continuous Profiler [here][15]. +You'll see a Profiling tab if the [Continuous Profiler][14] is set up for your service. Summary details like versions available and runtime language are at the top. Below are out-of-the-box profiling metrics by version, endpoint, and method to help you identify and debug resource-intensive methods. Click on any graph to view related traces, logs, and other data, or open a flame graph to inspect the code profile. [Learn more about APM and the Continuous Profiler][14]. {{< img src="tracing/visualization/service/profiler.jpg" alt="Profiling" style="width:90%;">}} diff --git a/content/fr/serverless/libraries_integrations/extension.md b/content/fr/serverless/libraries_integrations/extension.md index d0f15ad9ef416..938a258aef2f8 100644 --- a/content/fr/serverless/libraries_integrations/extension.md +++ b/content/fr/serverless/libraries_integrations/extension.md @@ -9,7 +9,7 @@ further_reading: tag: Blog text: Fonctions AWS Lambda exécutées sur des processeurs AWS Graviton2 aliases: - - /fr/serverless/datadog_lambda_library/extension/ + - /fr/serverless/libraries_integrations/extension/ --- ## Présentation diff --git a/content/fr/serverless/libraries_integrations/macro.md b/content/fr/serverless/libraries_integrations/macro.md index 7abc374ddacc7..86f94de1990e5 100644 --- a/content/fr/serverless/libraries_integrations/macro.md +++ b/content/fr/serverless/libraries_integrations/macro.md @@ -153,4 +153,4 @@ Si vous avez des commentaires ou des questions concernant les fonctionnalités, [5]: https://github.com/DataDog/datadog-lambda-python/releases [6]: https://github.com/DataDog/datadog-lambda-js/releases [7]: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-logs-subscriptionfilter.html -[8]: https://docs.datadoghq.com/fr/serverless/datadog_lambda_library/extension/ \ No newline at end of file +[8]: https://docs.datadoghq.com/fr/serverless/libraries_integrations/extension/ \ No newline at end of file diff --git a/content/fr/serverless/libraries_integrations/plugin.md b/content/fr/serverless/libraries_integrations/plugin.md index 17b3dda057113..f72a90cb5c070 100644 --- a/content/fr/serverless/libraries_integrations/plugin.md +++ b/content/fr/serverless/libraries_integrations/plugin.md @@ -268,4 +268,4 @@ Ce produit inclut un logiciel développé chez Datadog (https://www.datadoghq.co [5]: https://www.npmjs.com/package/datadog-lambda-js [6]: https://webpack.js.org/configuration/externals/ [7]: https://docs.datadoghq.com/fr/serverless/forwarder/ -[8]: https://docs.datadoghq.com/fr/serverless/datadog_lambda_library/extension/ +[8]: https://docs.datadoghq.com/fr/serverless/libraries_integrations/extension/ diff --git a/content/ja/serverless/datadog_lambda_library/_index.md b/content/ja/serverless/datadog_lambda_library/_index.md index 7ee951dc653b1..16e114588e5ec 100644 --- a/content/ja/serverless/datadog_lambda_library/_index.md +++ b/content/ja/serverless/datadog_lambda_library/_index.md @@ -2,7 +2,7 @@ title: Datadog Lambda ライブラリ kind: ドキュメント further_reading: - - link: /serverless/datadog_lambda_library/extension + - link: /serverless/libraries_integrations/extension tag: Documentation text: Datadog Lambda 拡張機能 (プレビュー) - link: /serverless/datadog_lambda_library/python diff --git a/content/ja/serverless/libraries_integrations/cli.md b/content/ja/serverless/libraries_integrations/cli.md index 49bf026bbf963..ed5a9faf5dfd0 100644 --- a/content/ja/serverless/libraries_integrations/cli.md +++ b/content/ja/serverless/libraries_integrations/cli.md @@ -102,5 +102,5 @@ datadog-ci lambda instrument -f functionname -r us-east-1 -v 10 --dry [2]: https://github.com/DataDog/datadog-ci [3]: https://github.com/DataDog/datadog-lambda-layer-js/releases [4]: https://github.com/DataDog/datadog-lambda-layer-python/releases -[5]: https://docs.datadoghq.com/ja/serverless/datadog_lambda_library/extension +[5]: https://docs.datadoghq.com/ja/serverless/libraries_integrations/extension [6]: https://docs.datadoghq.com/ja/account_management/api-app-keys/#api-keys \ No newline at end of file diff --git a/content/ja/serverless/libraries_integrations/extension.md b/content/ja/serverless/libraries_integrations/extension.md index aa0bd88fc99ac..6ea94bcd1d05f 100644 --- a/content/ja/serverless/libraries_integrations/extension.md +++ b/content/ja/serverless/libraries_integrations/extension.md @@ -6,7 +6,7 @@ further_reading: tag: ドキュメント text: AWS Lambda からのカスタムメトリクスの送信 aliases: - - /ja/serverless/datadog_lambda_library/extension/ + - /ja/serverless/libraries_integrations/extension/ --- ## 概要 diff --git a/content/ja/serverless/libraries_integrations/macro.md b/content/ja/serverless/libraries_integrations/macro.md index cb2ef5bb02d27..7c8d3c5544527 100644 --- a/content/ja/serverless/libraries_integrations/macro.md +++ b/content/ja/serverless/libraries_integrations/macro.md @@ -151,4 +151,4 @@ Resources: [5]: https://github.com/DataDog/datadog-lambda-python/releases [6]: https://github.com/DataDog/datadog-lambda-js/releases [7]: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-logs-subscriptionfilter.html -[8]: https://docs.datadoghq.com/ja/serverless/datadog_lambda_library/extension/ \ No newline at end of file +[8]: https://docs.datadoghq.com/ja/serverless/libraries_integrations/extension/ \ No newline at end of file diff --git a/content/ja/serverless/libraries_integrations/plugin.md b/content/ja/serverless/libraries_integrations/plugin.md index 2608c4ad417a7..c89ac4000406b 100644 --- a/content/ja/serverless/libraries_integrations/plugin.md +++ b/content/ja/serverless/libraries_integrations/plugin.md @@ -267,4 +267,4 @@ custom: [5]: https://www.npmjs.com/package/datadog-lambda-js [6]: https://webpack.js.org/configuration/externals/ [7]: https://docs.datadoghq.com/ja/serverless/forwarder/ -[8]: https://docs.datadoghq.com/ja/serverless/datadog_lambda_library/extension/ +[8]: https://docs.datadoghq.com/ja/serverless/libraries_integrations/extension/ diff --git a/content/ja/serverless/serverless_integrations/plugin.md b/content/ja/serverless/serverless_integrations/plugin.md index 121408652cc97..5276536c194b8 100644 --- a/content/ja/serverless/serverless_integrations/plugin.md +++ b/content/ja/serverless/serverless_integrations/plugin.md @@ -163,4 +163,4 @@ custom: [5]: https://www.npmjs.com/package/datadog-lambda-js [6]: https://webpack.js.org/configuration/externals/ [7]: https://docs.datadoghq.com/ja/serverless/forwarder/ -[8]: https://docs.datadoghq.com/ja/serverless/datadog_lambda_library/extension/ +[8]: https://docs.datadoghq.com/ja/serverless/libraries_integrations/extension/ diff --git a/local/bin/py/build/configurations/pull_config.yaml b/local/bin/py/build/configurations/pull_config.yaml index b7e509abd3193..83dd11088cf06 100644 --- a/local/bin/py/build/configurations/pull_config.yaml +++ b/local/bin/py/build/configurations/pull_config.yaml @@ -273,6 +273,37 @@ - /serverless/datadog_lambda_library/ - /serverless/serverless_integrations/cli/ + - repo_name: datadog-cdk-constructs + contents: + - action: pull-and-push-file + branch: main + globs: + - 'README.md' + options: + dest_path: '/serverless/libraries_integrations/' + file_name: 'cdk.md' + front_matters: + dependencies: ["https://github.com/DataDog/datadog-cdk-constructs/blob/main/README.md"] + title: Datadog CDK Construct + kind: documentation + + - repo_name: datadog-lambda-extension + contents: + - action: pull-and-push-file + branch: main + globs: + - 'README.md' + options: + dest_path: '/serverless/libraries_integrations/' + file_name: 'extension.md' + front_matters: + dependencies: ["https://github.com/DataDog/datadog-lambda-extension/blob/main/README.md"] + title: Datadog Lambda Extension + kind: documentation + aliases: + - /serverless/datadog_lambda_library/extension + - /serverless/libraries_integrations/extension + - repo_name: synthetics-ci-github-action contents: - action: pull-and-push-file diff --git a/local/bin/py/build/configurations/pull_config_preview.yaml b/local/bin/py/build/configurations/pull_config_preview.yaml index 331a60e57b17d..6302b6bdde9a2 100644 --- a/local/bin/py/build/configurations/pull_config_preview.yaml +++ b/local/bin/py/build/configurations/pull_config_preview.yaml @@ -274,6 +274,37 @@ - /serverless/datadog_lambda_library/ - /serverless/serverless_integrations/cli/ + - repo_name: datadog-cdk-constructs + contents: + - action: pull-and-push-file + branch: main + globs: + - 'README.md' + options: + dest_path: '/serverless/libraries_integrations/' + file_name: 'cdk.md' + front_matters: + dependencies: ["https://github.com/DataDog/datadog-cdk-constructs/blob/main/README.md"] + title: Datadog CDK Construct + kind: documentation + + - repo_name: datadog-lambda-extension + contents: + - action: pull-and-push-file + branch: main + globs: + - 'README.md' + options: + dest_path: '/serverless/libraries_integrations/' + file_name: 'extension.md' + front_matters: + dependencies: ["https://github.com/DataDog/datadog-lambda-extension/blob/main/README.md"] + title: Datadog Lambda Extension + kind: documentation + aliases: + - /serverless/datadog_lambda_library/extension + - /serverless/libraries_integrations/extension + - repo_name: synthetics-ci-github-action contents: - action: pull-and-push-file