Python サーバーレスアプリケーションのインスツルメンテーション

Python Lambda 関数が Python 3.6 以下で書かれている場合、または以前に Datadog Forwarder を使って Lambda 関数をセットアップした場合は、Datadog Forwarder を使ったインスツルメンテーションをご覧ください。
Lambda 関数が公共のインターネットにアクセスできない VPC にデプロイされている場合、datadoghq.com Datadog サイトには AWS PrivateLink を、それ以外のサイトにはプロキシを使用してデータを送信することができます。

インストール

Datadog は、サーバーレスアプリケーションのインスツルメンテーションを有効にするためのさまざまな方法を提供しています。以下からニーズに合った方法を選択してください。Datadog では、一般的に Datadog CLI の使用を推奨しています。

Datadog CLI は、既存の Lambda 関数のコンフィギュレーションを修正し、新しいデプロイを必要とせずにインスツルメンテーションを可能にします。Datadog のサーバーレスモニタリングをすばやく開始するための最適な方法です。

  1. Datadog CLI クライアントをインストールする

    npm install -g @datadog/datadog-ci
    
  2. Datadog サーバーレスモニタリングに慣れていない場合は、クイックスタートとして最初のインストールを導くためにインタラクティブモードで Datadog CLI を起動し、残りのステップを無視することができます。本番アプリケーションに Datadog を恒久的にインストールするには、このステップをスキップし、残りのステップに従って通常のデプロイの_後に_ CI/CD パイプラインで Datadog CLI コマンドを実行します。

    datadog-ci lambda instrument -i
    
  3. AWS の認証情報を構成する

    Datadog CLI は、AWS Lambda サービスへのアクセスを必要とし、AWS JavaScript SDK に依存して資格情報を解決します。AWS CLI を呼び出すときに使用するのと同じ方法を使用して、AWS の資格情報が構成されていることを確認します。

  4. Datadog のサイトを構成する

    export DATADOG_SITE="<DATADOG_SITE>"
    

    <DATADOG_SITE> に置き換えます。(右側で正しい SITE が選択されていることを確認してください)。

  5. Datadog API キーを構成する

    Datadog は、セキュリティと簡単なローテーションのために、AWS Secrets Manager に Datadog API キーを保存することを推奨します。キーはプレーンテキスト文字列として保存する必要があります (JSON blob ではありません)。Lambda 関数に必要な secretsmanager:GetSecretValue IAM 権限があることを確認します。

    export DATADOG_API_KEY_SECRET_ARN="<DATADOG_API_KEY_SECRET_ARN>"
    

     迅速なテスト目的のために、Datadog API キーをプレーンテキストで設定することも可能です。

    export DATADOG_API_KEY="<DATADOG_API_KEY>"
    
  6. Lambda 関数をインスツルメントする

    : Lambda 関数は、まず開発環境またはステージング環境でインスツルメントしてください。インスツルメンテーションの結果が思わしくない場合は、同じ引数で uninstrument を実行し、変更を元に戻してください。

    Lambda 関数をインスツルメントするには、次のコマンドを実行します。

    datadog-ci lambda instrument -f <functionname> -f <another_functionname> -r <aws_region> -v 64 -e 34
    

    プレースホルダーを埋めるには

    • <functionname><another_functionname> は Lambda 関数の名前に置き換えます。また、--functions-regex を使用すると、指定した正規表現にマッチする名前を持つ複数の関数を自動的にインスツルメントすることができます。
    • <aws_region> を AWS リージョン名に置き換えます。

    その他のパラメーターは、CLI ドキュメントに記載されています。

Datadog Serverless Plugin は、Datadog Lambda 拡張機能 を介してメトリクス、トレース、ログを Datadog に送信するように関数を自動的に構成します。

Datadog サーバーレスプラグインをインストールして構成するには、次の手順に従います。

  1. Datadog サーバーレスプラグインをインストールします。

    serverless plugin install --name serverless-plugin-datadog
    
  2. serverless.yml を更新します:

    custom:
      datadog:
        site: <DATADOG_SITE>
        apiKeySecretArn: <DATADOG_API_KEY_SECRET_ARN>
    

    プレースホルダーを埋めるには

    • <DATADOG_SITE> に置き換えます。(右側で正しい SITE が選択されていることを確認してください)。
    • <DATADOG_API_KEY_SECRET_ARN> を、Datadog API キーが安全に保存されている AWS シークレットの ARN に置き換えます。キーはプレーンテキスト文字列として保存する必要があります (JSON blob ではありません)。また、secretsmanager:GetSecretValue権限が必要です。迅速なテストのために、代わりに apiKey を使用して、Datadog API キーをプレーンテキストで設定することができます。

    詳細および追加設定については、プラグインドキュメントを参照してください。

Datadog CloudFormation マクロは、SAM アプリケーションのテンプレートを自動的に変換して Lambda レイヤーを使用して関数に Datadog をインストールし、Datadog Lambda 拡張機能を通じて Datadog にメトリクス、トレース、ログを送信するように関数を構成します。

  1. Datadog CloudFormation マクロのインストール

    AWS 認証情報で次のコマンドを実行して、マクロ AWS リソースをインストールする CloudFormation スタックをデプロイします。アカウントの特定のリージョンに一度だけマクロをインストールする必要があります。マクロを最新バージョンに更新するには、create-stackupdate-stack に置き換えます。

    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
    

    マクロが表示され、使用を開始できます。

  2. Lambda 関数をインスツルメントする

    SAM の template.yml ファイルの Transform セクションで、 AWS::Serverless 変換の後に DatadogServerless 変換を追加します。

    Transform:
      - AWS::Serverless-2016-10-31
      - Name: DatadogServerless
        Parameters:
          stackName: !Ref "AWS::StackName"
          pythonLayerVersion: 64
          extensionLayerVersion: 34
          site: "<DATADOG_SITE>"
          apiKeySecretArn: "<DATADOG_API_KEY_SECRET_ARN>"
    

    プレースホルダーを埋めるには

    • <DATADOG_SITE> に置き換えます。(右側で正しい SITE が選択されていることを確認してください)。
    • <DATADOG_API_KEY_SECRET_ARN> を、Datadog API キーが安全に保存されている AWS シークレットの ARN に置き換えます。キーはプレーンテキスト文字列として保存する必要があります (JSON blob ではありません)。また、secretsmanager:GetSecretValue権限が必要です。迅速なテストのために、代わりに apiKey を使用して、Datadog API キーをプレーンテキストで設定することができます。

    マクロのドキュメントに詳細と追加のパラメーターがあります。

Datadog CDK コンストラクト は、Lambda レイヤーを使用して Datadog を関数に自動的にインストールし、Datadog Lambda 拡張機能を介してメトリクス、トレース、ログを Datadog に送信するように関数を構成します。

  1. Datadog CDK コンストラクトライブラリのインストール

    # For AWS CDK v1
    pip install datadog-cdk-constructs
    
    # For AWS CDK v2
    pip install datadog-cdk-constructs-v2
    
  2. Lambda 関数をインスツルメントする

    # For AWS CDK v1
    from datadog_cdk_constructs import Datadog
    
    # For AWS CDK v2
    from datadog_cdk_constructs_v2 import Datadog
    
    datadog = Datadog(self, "Datadog",
        python_layer_version=64,
        extension_layer_version=34,
        site="<DATADOG_SITE>",
        apiKeySecretArn="<DATADOG_API_KEY_SECRET_ARN>",
      )
    datadog.add_lambda_functions([<LAMBDA_FUNCTIONS>])
    

    プレースホルダーを埋めるには

    • <DATADOG_SITE> に置き換えます。(右側で正しい SITE が選択されていることを確認してください)。
    • <DATADOG_API_KEY_SECRET_ARN> を、Datadog API キーが安全に保存されている AWS シークレットの ARN に置き換えます。キーはプレーンテキスト文字列として保存する必要があります (JSON blob ではありません)。また、secretsmanager:GetSecretValue権限が必要です。迅速なテストのために、代わりに apiKey を使用して、Datadog API キーをプレーンテキストで設定することができます。

    Datadog CDK のドキュメントに詳細と追加のパラメーターがあります。

  1. Datadog Lambda ライブラリのインストール

    Lambda 関数をコンテナイメージとしてデプロイする場合は、Datadog Lambda ライブラリを Lambda レイヤーとして使用できません。代わりに、Datadog Lambda ライブラリを、イメージ内の関数の依存関係としてインストールする必要があります。

    pip install datadog-lambda
    

    datadog-lambda パッケージのマイナーバージョンは、常にレイヤーのバージョンに一致します。たとえば、datadog-lambda v0.5.0 は、レイヤーバージョン 5 のコンテンツに一致します。

  2. Datadog Lambda 拡張機能のインストール

    Dockerfile に以下を追加して、Datadog Lambda 拡張機能をコンテナイメージに追加します。

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

    <TAG> を特定のバージョン番号 (たとえば 34) または latest に置き換えます。利用可能なタグのリストは、Amazon ECR リポジトリで確認できます。

  3. ハンドラー関数のリダイレクト

    • イメージの CMD 値を datadog_lambda.handler.handler に設定します。AWS で設定するか、Dockerfile 内で直接設定します。両方の値を設定した場合、AWS で設定した値が Dockerfile 内の値をオーバーライドします。
    • 元のハンドラーに、環境変数 DD_LAMBDA_HANDLER を設定します。例: myfunc.handler

    : Datadog ハンドラーのリダイレクトと互換性のないサードパーティのセキュリティツールやモニタリングツールを使用している場合、代わりに関数コードで Datadog ラッパーを適用することができます。

  4. Datadog サイト、API キー、トレーシングの構成

    • 環境変数 DD_SITE を設定します。(右側で正しい SITE が選択されていることを確認してください)。
    • 環境変数 DD_API_KEY_SECRET_ARN を、Datadog API キーが安全に保存されている AWS シークレットの ARN で設定します。キーはプレーンテキスト文字列として保存する必要があります (JSON blob ではありません)。また、secretsmanager:GetSecretValue権限が必要です。迅速なテストのために、代わりに DD_API_KEY を使用して、Datadog API キーをプレーンテキストで設定することができます。
    • 環境変数 DD_TRACE_ENABLEDtrue に設定します。
Serverless Framework や AWS CDK といった Datadog をサポートするサーバーレス開発ツールを使用していない場合は、Datadog はお使いのサーバーレスアプリケーションを Datadog CLI でインスツルメントすることを強く推奨します。
  1. Datadog Lambda ライブラリのインストール

    Datadog Lambda ライブラリは、レイヤー (推奨) または Python パッケージのいずれかとしてインポートすることができます。

    datadog-lambda パッケージのマイナーバージョンは、常にレイヤーのバージョンに一致します。たとえば、datadog-lambda v0.5.0 は、レイヤーバージョン 5 のコンテンツに一致します。

    • オプション A: 以下のフォーマットで、ARN を使用して Lambda 関数にレイヤーを構成します。

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

      <AWS_REGION>us-east-1 などの有効な AWS リージョンに置き換えてください。RUNTIME オプションは、Python37Python38 または Python39 が利用可能です。

    • オプション B: ビルド済みの Datadog Lambda レイヤーを使用できない場合、代わりに datadog-lambda パッケージとその依存関係を、pip などのお気に入りの Python パッケージマネージャーを使って、関数プロジェクトフォルダにローカルにインストールします。

      pip install datadog-lambda -t ./
      

      : datadog-lambda はネイティブ拡張機能を使用する ddtrace に依存しています。したがって、適切なアーキテクチャ (x86_64 または arm64) の Linux 環境でインストールおよびコンパイルする必要があります。例えば、Serverless Framework では dockerizePip を、AWS SAM では –use-container を利用することができます。詳しくは、関数デプロイパッケージへの依存関係の追加方法をご参照ください。

      最新リリースを参照。

  2. Datadog Lambda 拡張機能のインストール

    以下のフォーマットで、ARN を使用して Lambda 関数にレイヤーを構成します。

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

    <AWS_REGION>us-east-1 などの有効な AWS リージョンに置き換えてください。

  3. ハンドラー関数のリダイレクト

    • 関数のハンドラーを datadog_lambda.handler.handler に設定します。
    • 元のハンドラーに、環境変数 DD_LAMBDA_HANDLER を設定します。例: myfunc.handler

    : Datadog ハンドラーのリダイレクトと互換性のないサードパーティのセキュリティツールやモニタリングツールを使用している場合、代わりに関数コードで Datadog ラッパーを適用することができます。

  4. Datadog サイト、API キー、トレーシングの構成

    • 環境変数 DD_SITE を設定します。(右側で正しい SITE が選択されていることを確認してください)。
    • 環境変数 DD_API_KEY_SECRET_ARN を、Datadog API キーが安全に保存されている AWS シークレットの ARN で設定します。キーは json blob の中ではなく、プレーンテキスト文字列として保存する必要があります。また、secretsmanager:GetSecretValue権限が必要です。迅速なテストのために、代わりに DD_API_KEY を使用して、Datadog API キーをプレーンテキストで設定することができます。
    • 環境変数 DD_TRACE_ENABLEDtrue に設定します。
  5. (AWS Chalice のみ) ミドルウェアの登録

    AWS Chalice を利用する場合は、datadog-lambdapip でインストールし、datadog_lambda_wrapperapp.pyミドルウェアとして登録しておく必要があります。

    from chalice import Chalice, ConvertToMiddleware
    from datadog_lambda.wrapper import datadog_lambda_wrapper
    
    app = Chalice(app_name='hello-chalice')
    
    app.register_middleware(ConvertToMiddleware(datadog_lambda_wrapper))
    
    @app.route('/')
    def index():
        return {'hello': 'world'}
    

次のステップ

  • Serverless Homepage でメトリクス、ログ、トレースを見ることができるようになりました。
  • カスタムビジネスロジックの監視のサンプルコードを参照してください。
  • テレメトリーの収集に問題がある場合は、トラブルシューティングガイドを参照してください
  • 高度な構成を参照して以下のことを行ってください。
    • タグを使ったテレメトリー接続
    • AWS API Gateway、SQS などのテレメトリーを収集する
    • Lambda のリクエストとレスポンスのペイロードを取得する
    • Lambda 関数のエラーをソースコードにリンクする
    • ログまたはトレースから機密情報をフィルタリングまたはスクラブする

カスタムビジネスロジックの監視

カスタムビジネスロジックを監視するには、以下のサンプルコードを使用してカスタムメトリクスまたはスパンを送信します。その他のオプションについては、サーバーレスアプリケーションのためのカスタムメトリクスの送信およびカスタムインスツルメンテーションのための APM ガイドを参照してください。

import time
from ddtrace import tracer
from datadog_lambda.metric import lambda_metric

def lambda_handler(event, context):
    # Lambda 関数スパンにカスタムタグを追加します
    # X-Ray トレーシングが有効になっている場合は機能しません
    current_span = tracer.current_span()
    if current_span:
        current_span.set_tag('customer.id', '123456')

    # カスタムスパンを送信します
    with tracer.trace("hello.world"):
        print('Hello, World!')

    # カスタムメトリクスを送信します
    lambda_metric(
        metric_name='coffee_house.order_value',
        value=12.45,
        tags=['product:latte', 'order:online']
    )

    return {
        'statusCode': 200,
        'body': get_message()
    }

# 関数をトレースします
@tracer.wrap()
def get_message():
    return 'Hello from serverless!'

その他の参考資料