Instrumenting .NET Serverless Applications
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. You must follow the instructions for “Container Image” if your application is deployed as a container image.
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.
Install the Datadog CLI client
npm install -g @datadog/datadog-ci
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.
datadog-ci lambda instrument -i
Configure the AWS credentials
The Datadog CLI requires access to the AWS Lambda service and depends on the AWS JavaScript SDK to resolve the credentials. Ensure your AWS credentials are configured using the same method you would use when invoking the AWS CLI.
Configure the Datadog site
export DATADOG_SITE="<DATADOG_SITE>"
Replace <DATADOG_SITE>
with
(ensure the correct SITE is selected on the right).
Configure the Datadog API key
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.
export DATADOG_API_KEY_SECRET_ARN="<DATADOG_API_KEY_SECRET_ARN>"
For quick testing purposes, you can also set the Datadog API key in plaintext:
export DATADOG_API_KEY="<DATADOG_API_KEY>"
Instrument your Lambda functions
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.
datadog-ci lambda instrument -f <functionname> -f <another_functionname> -r <aws_region> -v 8 -e 43
To fill in the placeholders:
- Replace
<functionname>
and <another_functionname>
with your Lambda function names. Alternatively, you can use --functions-regex
to automatically instrument multiple functions whose names match the given regular expression. - Replace
<aws_region>
with the AWS region name.
Additional parameters can be found in the CLI documentation.
The Datadog Serverless Plugin automatically configures your functions to send metrics, traces, and logs to Datadog through the Datadog Lambda Extension.
To install and configure the Datadog Serverless Plugin, follow these steps:
Install the Datadog Serverless Plugin:
serverless plugin install --name serverless-plugin-datadog
Update your serverless.yml
:
custom:
datadog:
site: <DATADOG_SITE>
apiKeySecretArn: <DATADOG_API_KEY_SECRET_ARN>
To fill in the placeholders:
- Replace
<DATADOG_SITE>
with
(ensure the correct SITE is selected on the right). - Replace
<DATADOG_API_KEY_SECRET_ARN>
with the ARN of the AWS secret where your Datadog API key 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.
Install the Datadog Lambda Extension
COPY --from=public.ecr.aws/datadog/lambda-extension:<TAG> /opt/. /opt/
Replace <TAG>
with either a specific version number (for example, 43
) or with latest
. You can see a complete list of possible tags in the Amazon ECR repository.
Install the Datadog .NET APM client
RUN yum -y install tar wget gzip
RUN wget https://github.com/DataDog/dd-trace-dotnet/releases/download/v<TRACER_VERSION>/datadog-dotnet-apm-<TRACER_VERSION>.tar.gz
RUN mkdir /opt/datadog
RUN tar -C /opt/datadog -xzf datadog-dotnet-apm-<TRACER_VERSION>.tar.gz
ENV AWS_LAMBDA_EXEC_WRAPPER /opt/datadog_wrapper
Replace <TRACER_VERSION>
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.
Set the required environment variables
- Set the environment variable
DD_SITE
to
(ensure the correct SITE is selected on the right). - Set the environment variable
DD_API_KEY_SECRET_ARN
with the ARN of the AWS secret where your Datadog API key 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.
Install the Datadog Tracer
Configure the layers for your Lambda function using the ARN in the following format:
# Use this format for x86-based Lambda deployed in AWS commercial regions
arn:aws:lambda:<AWS_REGION>:464622532012:layer:dd-trace-dotnet:8
# Use this format for arm64-based Lambda deployed in AWS commercial regions
arn:aws:lambda:<AWS_REGION>:464622532012:layer:dd-trace-dotnet-ARM:8
# Use this format for x86-based Lambda deployed in AWS GovCloud regions
arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:dd-trace-dotnet:8
# Use this format for arm64-based Lambda deployed in AWS GovCloud regions
arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:dd-trace-dotnet-ARM:8
Replace <AWS_REGION>
with a valid AWS region, such as us-east-1
.
Install the Datadog Lambda Extension
Configure the layers for your Lambda function using the ARN in the following format:
# Use this format for x86-based Lambda deployed in AWS commercial regions
arn:aws:lambda:<AWS_REGION>:464622532012:layer:Datadog-Extension:43
# Use this format for arm64-based Lambda deployed in AWS commercial regions
arn:aws:lambda:<AWS_REGION>:464622532012:layer:Datadog-Extension-ARM:43
# Use this format for x86-based Lambda deployed in AWS GovCloud regions
arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:Datadog-Extension:43
# Use this format for arm64-based Lambda deployed in AWS GovCloud regions
arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:Datadog-Extension-ARM:43
Replace <AWS_REGION>
with a valid AWS region, such as us-east-1
.
Install the Datadog Tracer
Configure the layers for your Lambda function using the ARN in the following format:
# Use this format for x86-based Lambda deployed in AWS commercial regions
arn:aws:lambda:<AWS_REGION>:417141415827:layer:dd-trace-dotnet:8
# Use this format for arm64-based Lambda deployed in AWS commercial regions
arn:aws:lambda:<AWS_REGION>:417141415827:layer:dd-trace-dotnet-ARM:8
# Use this format for x86-based Lambda deployed in AWS GovCloud regions
arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:dd-trace-dotnet:8
# Use this format for arm64-based Lambda deployed in AWS GovCloud regions
arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:dd-trace-dotnet-ARM:8
Replace <AWS_REGION>
with a valid AWS region, such as us-east-1
.
Install the Datadog Lambda Extension
Configure the layers for your Lambda function using the ARN in the following format:
# Use this format for x86-based Lambda deployed in AWS commercial regions
arn:aws:lambda:<AWS_REGION>:417141415827:layer:Datadog-Extension:43
# Use this format for arm64-based Lambda deployed in AWS commercial regions
arn:aws:lambda:<AWS_REGION>:417141415827:layer:Datadog-Extension-ARM:43
# Use this format for x86-based Lambda deployed in AWS GovCloud regions
arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:Datadog-Extension:43
# Use this format for arm64-based Lambda deployed in AWS GovCloud regions
arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:Datadog-Extension-ARM:43
Replace <AWS_REGION>
with a valid AWS region, such as us-east-1
.
Set the required environment variables
- Set
AWS_LAMBDA_EXEC_WRAPPER
to /opt/datadog_wrapper
. - Set
DD_SITE
to
(ensure the correct SITE is selected on the right). - Set
DD_API_KEY_SECRET_ARN
to the ARN of the AWS secret where your Datadog API key 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.
What’s next?
- You can now view metrics, logs, and traces on the Serverless Homepage.
- Submit a custom metric or APM span to monitor your business logic.
- See the troubleshooting guide if you have trouble collecting the telemetry
- See the advanced configurations 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
Additional helpful documentation, links, and articles: