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

Python Lambda 関数が Python 3.6 以下で書かれている場合、または以前に Datadog Forwarder を使って Lambda 関数をセットアップした場合は、Datadog Forwarder を使ったインスツルメンテーションをご覧ください。それ以外の場合は、このガイドの指示に従って、Datadog Lambda 拡張機能を使用してインスツルメンテーションを行います。
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.

インストール

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 104 -e 66

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

      • <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-stack を update-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: 104
      extensionLayerVersion: 66
      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=104,
    extension_layer_version=66,
    site="<DATADOG_SITE>",
    api_key_secret_arn="<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/. /opt/

      <TAG> を特定のバージョン番号 (例えば 66) または latest に置き換えてください。Alpine も特定のバージョン番号 (例えば 66-alpine) または latest-alpine でサポートされています。Amazon ECR リポジトリで、使用可能なタグの完全なリストを見ることができます。

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

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

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

    4. Dockerfile での 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_ENABLED を true に設定します。

    lambda-datadog Terraform モジュールは aws_lambda_function リソースをラップし、Datadog サーバーレスモニタリング用に以下の方法で Lambda 関数を自動的に設定します。

    • Datadog Lambda レイヤーを追加する
    • Lambda ハンドラーをリダイレクトする
    • メトリクス、トレース、ログの収集と Datadog への送信を有効にする
    module "lambda-datadog" {
  source  = "DataDog/lambda-datadog/aws"
  version = "2.0.0"

  environment_variables = {
    "DD_API_KEY_SECRET_ARN" : "<DATADOG_API_KEY_SECRET_ARN>"
    "DD_ENV" : "<ENVIRONMENT>"
    "DD_SERVICE" : "<SERVICE_NAME>"
    "DD_SITE": "<DATADOG_SITE>"
    "DD_VERSION" : "<VERSION>"
  }

  datadog_extension_layer_version = 67
  datadog_python_layer_version = 104

  # aws_lambda_function arguments
}

    1. aws_lambda_function リソースを lambda-datadog Terraform モジュールに置き換えます。次に、モジュールの source と version を指定します。

    2. aws_lambda_function 引数を設定します。

      aws_lambda_function リソースで利用可能なすべての引数は、この Terraform モジュールでも使用できます。aws_lambda_function リソースでブロックとして定義された引数は、ネストされた引数を含む変数として再定義されます。

      たとえば、aws_lambda_function では、environment は variables 引数を持つブロックとして定義されています。lambda-datadog Terraformモジュールでは、environment_variables の値が aws_lambda_function の environment.variables 引数に渡されます。このモジュールの変数の完全なリストは Inputs を参照してください。

    3. 環境変数のプレースホルダーを埋めます。

      • <DATADOG_API_KEY_SECRET_ARN> を、Datadog API キーが安全に保存されている AWS シークレットの ARN に置き換えます。キーはプレーンテキスト文字列として保存する必要があります (JSON blob ではありません)。また、secretsmanager:GetSecretValue権限が必要です。迅速なテストのために、代わりに環境変数 DD_API_KEY を使用して、Datadog API キーをプレーンテキストで設定することができます。
      • <ENVIRONMENT> を prod や staging などの Lambda 関数の環境に置き換えます。　
      • <SERVICE_NAME> を Lambda 関数のサービス名に置き換えます。
      • <DATADOG_SITE> を に置き換えます。(このページで正しい Datadog サイトが選択されていることを確認してください。)
      • <VERSION> を Lambda 関数のバージョン番号に置き換えます。

    4. 使用する Datadog 拡張機能 Lambda レイヤーと Datadog Python Lambda レイヤーのバージョンを選択します。空白の場合、最新のレイヤーが使用されます。

      datadog_extension_layer_version = 67
  datadog_python_layer_version = 104
    Datadog がサポートする Serverless Framework や AWS CDK などのサーバーレス開発ツールを使用していない場合、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>:104

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

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

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

        <AWS_REGION> を us-east-1 などの有効な AWS リージョンに置き換えます。<RUNTIME> オプションは、Python38, Python39, Python310, Python311, Python312 が利用可能です。

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

        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: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

      <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_ENABLED を true に設定します。

    5. (AWS Chalice のみ) ミドルウェアの登録

      AWS Chalice を利用する場合は、datadog-lambda を pip でインストールし、datadog_lambda_wrapper を app.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 でメトリクス、ログ、トレースを見ることができるようになりました。
    • サービスを標的にしている攻撃者についてアラートを受け取るには、脅威の監視を有効にします。
    • カスタムビジネスロジックの監視のサンプルコードを参照してください
    • テレメトリーの収集に問題がある場合は、トラブルシューティングガイドを参照してください
    • 高度な構成を参照して以下のことを行ってください。
      • タグを使ったテレメトリー接続
      • Amazon 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!'

    その他の参考資料

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

    サーバーレスモニタリングの構成ドキュメント more more サーバーレスモニタリングのトラブルシューティングドキュメント more more サーバーレスアプリケーションからのカスタムメトリクスの送信ドキュメント more more