Instrumenting Ruby Serverless Applications

このページは日本語には対応しておりません。随時翻訳に取り組んでいます。翻訳に関してご質問やご意見ございましたら、お気軽にご連絡ください。
If you previously set up your Lambda functions using the Datadog Forwarder, see instrumenting using the Datadog Forwarder. Otherwise, follow the instructions in this guide to instrument using the Datadog Lambda Extension.
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.

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.

    1. Configure your Lambda functions

      Enable Datadog APM and wrap your Lambda handler function using the wrapper provided by the Datadog Lambda library.

      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' }
    end
end

    2. Install the Datadog CLI client

      npm install -g @datadog/datadog-ci

    3. 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.

      datadog-ci lambda instrument -i

    4. Configure the AWS credentials

      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.

    5. Configure the Datadog site

      export DATADOG_SITE="<DATADOG_SITE>"

      Replace <DATADOG_SITE> with (ensure the correct SITE is selected on the right).

    6. 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>"

    7. 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 23 -e 66

      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:

    1. Configure your Lambda functions

      Enable Datadog APM and wrap your Lambda handler function using the wrapper provided by the Datadog Lambda library.

      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' }
    end
end

    2. Install the Datadog Serverless Plugin:

      serverless plugin install --name serverless-plugin-datadog

    3. 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.

    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 Lambda Layer. Instead, you must package the Datadog Lambda and tracing libraries within the image.

      Add the following to your Gemfile:

      gem 'datadog-lambda'
gem 'ddtrace'

      ddtrace contains native extensions that must be compiled for Amazon Linux to work with AWS Lambda.

      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.

      FROM <base image>

# assemble your container image

RUN yum -y install gcc gmp-devel make
RUN bundle config set path 'vendor/bundle'
RUN bundle install

    2. Install the Datadog Lambda Extension

      Add the Datadog Lambda Extension to your container image by adding the following to your Dockerfile:

      COPY --from=public.ecr.aws/datadog/lambda-extension:<TAG> /opt/. /opt/

      Replace <TAG> with either a specific version number (for example, 66) or with latest. Alpine is also supported with specific version numbers (such as 66-alpine) or with latest-alpine. You can see a complete list of possible tags in the Amazon ECR repository.

    3. Configure your Lambda functions

      Enable Datadog APM and wrap your Lambda handler function using the wrapper provided by the Datadog Lambda library.

      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' }
    end
end

    4. Configure the Datadog site and API key

      • 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.
    If you are not using a serverless development tool that Datadog supports, such as the Serverless Framework, Datadog strongly encourages you instrument your serverless applications with the Datadog CLI.

    1. Install the Datadog 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.

      • Option A: 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-<RUNTIME>:23

# Use this format for arm64-based Lambda deployed in AWS commercial regions
arn:aws:lambda:<AWS_REGION>:464622532012:layer:Datadog-<RUNTIME>-ARM:23


# Use this format for x86-based Lambda deployed in AWS GovCloud regions
arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:Datadog-<RUNTIME>:23

# Use this format for arm64-based Lambda deployed in AWS GovCloud regions
arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:Datadog-<RUNTIME>-ARM:23

        Replace <AWS_REGION> with a valid AWS region such as us-east-1. The available RUNTIME options are Ruby2-7, and Ruby3-2.

      • Option B: If you cannot use the prebuilt Datadog Lambda layer, alternatively you can install the gems datadog-lambda and ddtrace by adding them to your Gemfile as an alternative:

        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.

        FROM <base image>

# assemble your container image

RUN yum -y install gcc gmp-devel make
RUN bundle config set path 'vendor/bundle'
RUN bundle install

    2. Install the Datadog Lambda Extension

      • Option A: 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:66

# Use this format for arm64-based Lambda deployed in AWS commercial regions
arn:aws:lambda:<AWS_REGION>:464622532012:layer:Datadog-Extension-ARM:66

# Use this format for x86-based Lambda deployed in AWS GovCloud regions
arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:Datadog-Extension:66

# Use this format for arm64-based Lambda deployed in AWS GovCloud regions
arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:Datadog-Extension-ARM:66

        Replace <AWS_REGION> with a valid AWS region, such as us-east-1.

      • Option B: Add the Datadog Lambda Extension to your container image by adding the following to your Dockerfile:

        COPY --from=public.ecr.aws/datadog/lambda-extension:<TAG> /opt/extensions/ /opt/extensions

        Replace <TAG> with either a specific version number (for example, 66) or with latest. You can see a complete list of possible tags in the Amazon ECR repository.

    3. Configure your Lambda functions

      Enable Datadog APM and wrap your Lambda handler function using the wrapper provided by the Datadog Lambda library.

      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' }
    end
end

    4. Configure Datadog site and API key

      • 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.

    What’s next?

    • You can now view metrics, logs, and traces on the Serverless Homepage.
    • Turn on threat monitoring to get alerted on attackers targeting your service.
    • See the sample code to monitor custom 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 Amazon 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

    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 and the APM guide for custom instrumentation.

    require 'ddtrace'
require 'datadog/lambda'

Datadog::Lambda.configure_apm do |c|
# Enable the instrumentation
end

def handler(event:, context:)
    # Apply the Datadog wrapper
    Datadog::Lambda::wrap(event, context) do
        # Add custom tags to the lambda function span,
        # does NOT work when X-Ray tracing is enabled
        current_span = Datadog::Tracing.active_span
        current_span.set_tag('customer.id', '123456')

        some_operation()

        Datadog::Tracing.trace('hello.world') do |span|
          puts "Hello, World!"
        end

        # Submit a custom metric
        Datadog::Lambda.metric(
          'coffee_house.order_value', # metric name
          12.45, # metric value
          time: Time.now.utc, # optional, must be within last 20 mins
          "product":"latte", # tag
          "order":"online" # another tag
        )
    end
end

# Instrument the function
def some_operation()
    Datadog::Tracing.trace('some_operation') do |span|
        # Do something here
    end
end

    For more information on custom metric submission, see Serverless Custom Metrics. For additional details on custom instrumentation, see the Datadog APM documentation for custom instrumentation.

    Further Reading

    お役に立つドキュメント、リンクや記事:

    Datadog Lambda Library for RubyDOCUMENTATION more more Tracing Serverless ApplicationsDOCUMENTATION more more Submitting Custom Metrics from Serverless ApplicationsDOCUMENTATION more more Troubleshoot Serverless MonitoringDOCUMENTATION more more