概要

Kubernetes 環境では、APM 用のシングルステップインスツルメンテーション (SSI) を利用して Datadog Agent をインストールし、Datadog SDK を使ってアプリケーションを 1 ステップでインスツルメントします。

要件

• Kubernetes v1.20 以降。
• Helm (Datadog Operator デプロイ用)。
• Kubectl CLI (Datadog Agent インストール用)。
• シングルステップインスツルメンテーション互換性環境 に基づいて環境互換性確認済み。

アプリケーションで APM を有効にする

クラスター全体でシングルステップインスツルメンテーションを有効にするための手順に従ってください。これにより、サポートされている言語で作成されたすべてのアプリケーションからトレースが自動的に送信されます。

注: 特定のネームスペースや Pod だけをインスツルメントするには、高度なオプションのワークロードターゲティングを参照してください。

1. Datadog で、Kubernetes に Datadog Agent をインストールするのページに移動します。

2. 画面の指示に従ってインストール方法を選択し、API キーを選択して、Operator または Helm のリポジトリをセットアップします。

3. **構成datadog-agent.yaml**セクションで、追加構成 >アプリケーションの監視可能性に移動し、APM インスツルメンテーションをオンにします。

4. 生成される構成ファイルを使用して Agent をデプロイします。

5. アプリケーションを再起動します。

統合サービスタグを構成する

統合サービスタグ (UST) は、トレース、メトリクス、ログを通じて一貫したタグを適用し、監視可能性データのナビゲートと相関を容易にします。UST は、自動ラベル抽出 (推奨)、ddTraceConfigs による明示的な構成、またはデプロイメントマニフェストで構成できます。

(推奨) 自動ラベル抽出を通じて UST を構成する

SSI を使用すると、個々のデプロイメントに変更を加えることなく、Pod ラベルとメタデータから UST 値を自動的に抽出できます。そのためには、既存の Kubernetes ラベルを Datadog サービスタグにマッピングするように kubernetesResourcesLabelsAsTags を構成します。

注: この方法は Remote Configuration と互換性がありません。Remote Configuration を使用している場合は、ddTraceConfigs で UST を明示的に構成するを参照してください。

前提条件

構成

次の例では、app.kubernetes.io/name を、サービス名が含まれる任意のラベルに置き換えてください (例:service.kubernetes.io/name や component)。この方法で複数のラベルを構成できます。

datadog:
  # Automatically extract service names from Kubernetes labels
  kubernetesResourcesLabelsAsTags:
    pods:
      app.kubernetes.io/name: service     # Modern Kubernetes label
    deployments.apps:
      app.kubernetes.io/name: service
    replicasets.apps:
      app.kubernetes.io/name: service

  # Set environment globally for the entire cluster
  tags:
    - "env:production"

  apm:
    instrumentation:
      enabled: true

この構成により、Datadogはこのラベルを含むインスツルメントされた任意のワークロードに対して、app.kubernetes.io/name ラベルの値を使用することにより、service タグを自動的に設定します。

ddTraceConfigs を使用して UST を明示的に構成する

ほとんどの場合、自動構成で十分です。とはいえ、特定のワークロードの設定を詳細に制御する必要がある場合は、ddTraceConfigs を使用することにより、明示的にラベルをサービス構成にマッピングします。

datadog:
  kubernetesResourcesLabelsAsTags:
    pods:
      app.kubernetes.io/name: service
    deployments.apps:
      app.kubernetes.io/name: service

  # Set environment globally for the entire cluster
  tags:
    - "env:production"

  apm:
    instrumentation:
      enabled: true
      targets:
        - name: frontend-services
          podSelector:
            matchLabels:
              tier: frontend
          ddTraceConfigs:
            - name: DD_SERVICE       # Explicitly override service name
              valueFrom:
                fieldRef:
                  fieldPath: metadata.labels['app.kubernetes.io/name']
            # DD_ENV inherited from cluster-level tags above
            # DD_VERSION automatically extracted from image tags

デプロイメントマニフェストで UST を構成する

UST 抽出に適したラベルを使用していないセットアップの場合は、環境変数を使用してデプロイメントマニフェストの中で直接 UST を設定できます。この方法では各デプロイメントに個別に変更を加える必要がありますが、細かい制御が可能になります。

手順について詳しくは、Kubernetesサービスの UST 設定を参照してください。

SDK に依存する製品と機能を有効にする

SSI がアプリケーションに Datadog SDK をロードし、分散トレーシングを有効にした後、SDK に依存する追加の製品を構成できます。

Note: All variables accept true or false. DD_PROFILING_ENABLED also accepts auto, which profiles only eligible processes and is recommended for SSI.

以下のいずれかのセットアップ方法を使用します。

• ワークロードターゲティングで構成する (推奨):

  デフォルトの場合、シングルステップインスツルメンテーションはすべてのネームスペースのすべてのサービスをインスツルメントします。ワークロードターゲティングを使用して、インスツルメンテーションを特定のネームスペース、Pod、またはワークロードに制限し、カスタム構成を適用します。

• 環境変数を設定する:

  アプリケーション構成で環境変数を直接設定することにより製品を有効にします。

高度なオプション

以下の高度なオプションを使用することにより、シングルステップインスツルメンテーションが環境内でどのように動作するかをカスタマイズできます。これらの設定はオプションであり、通常、それらが必要になるのは特別なセットアップの場合だけです。

注入モードを構成する

SSI で複数の注入モードがサポートされており、それらは、インジェクターと APM ライブラリファイルがアプリケーションコンテナにどのように配信されるかを制御します。通常、この設定を手動で構成する必要はありません。Pod の初期化中に、顕著な Pod 起動遅延や予想以上のリソース消費 (CPU、メモリ) に気付いた場合は、調整を検討してください。インジェクターの動作について詳しくは、シングルステップインスツルメンテーションによるインジェクターの動作を参照してください。

csi モードを使用する前に、Datadog CSI ドライバーをインストールし、アクティブにしてください。Helm でデプロイする場合は、datadog.csi.enabled: true を datadog-values.yaml に設定してください。インストール手順や GKE オートパイロットなど、環境固有の要件については、CSI ドライバーのドキュメントを参照してください。

注入モードをグローバルに構成する

datadog:
  apm:
    instrumentation:
      injectionMode: <mode>

features:
  apm:
    instrumentation:
      injectionMode: <mode>

Pod ごとにインジェクションモードを構成する

特定の Pod のインジェクションモードをオーバーライドするには、Pod の指定に次のアノテーションを追加します。

metadata:
  annotations:
    admission.datadoghq.com/apm-inject.injection-mode: "<mode>"

サポートされている値: init_container、csi。

特定のワークロードをターゲットにする

デフォルトの場合、SSI はクラスター内のすべてのネームスペースのすべてのサービスをインスツルメントします。Agent のバージョンに応じて、インスツルメンテーションするサービスとその方法を微調整するために、以下の構成方法のいずれかを使用してください。

   apm:
     instrumentation:
       enabled: true
       disabledNamespaces:
         - "jenkins"
       targets:
         - name: "all-remaining-services"
           ddTraceVersions:
             java: "default"
             python: "3.1.0"

  apm:
    instrumentation:
      enabled: true
      targets:
        - name: "login-service_namespace"
          namespaceSelector:
            matchNames:
              - "login-service"
          ddTraceVersions:
            java: "default"
          ddTraceConfigs:
            - name: "DD_PROFILING_ENABLED"  ## profiling is enabled for all services in this namespace
              value: "auto"
        - name: "billing-service_apps"
          namespaceSelector:
            matchLabels:
              app: "billing-service"
          ddTraceVersions:
            python: "3.1.0"

   apm:
     instrumentation:
       enabled: true
       targets:
         - name: "db-user"
           podSelector:
             matchLabels:
               app: "db-user"
           ddTraceVersions:
             java: "default"
           ddTraceConfigs:   ## trace configs set for services in matching pods
             - name: "DD_DATA_STREAMS_ENABLED"
               value: "true"
         - name: "user-request-router"
           podSelector:
             matchLabels:
               webserver: "user"
           ddTraceVersions:
             php: "default"

   apm:
     instrumentation:
       enabled: true
       targets:
         - name: "login-service-namespace"
           namespaceSelector:
             matchNames:
               - "login-service"
           podSelector:
             matchLabels:
               app: "password-resolver"
           ddTraceVersions:
             java: "default"
           ddTraceConfigs:
             - name: "DD_PROFILING_ENABLED"
               value: "auto"

   apm:
     instrumentation:
       enabled: true
       targets:
         - name: "default-target"
           podSelector:
               matchExpressions:
                 - key: app
                   operator: NotIn
                   values:
                   - app1
                   - app2

   apm:
     instrumentation:
       enabled: true
       targets:
         - name: "web-apps-with-security"
           namespaceSelector:
             matchNames:
               - "web-apps"
           ddTraceVersions:
             java: "default"
             python: "default"
           ddTraceConfigs:
             - name: "DD_APPSEC_ENABLED"
               value: "true"
             - name: "DD_PROFILING_ENABLED"
               value: "auto"

   features:
     apm:
       instrumentation:
         enabled: true
         enabledNamespaces: # Add namespaces to instrument
           - default
           - applications

   features:
     apm:
       instrumentation:
         enabled: true
         disabledNamespaces: # Add namespaces to not instrument
           - default
           - applications

   datadog:
      apm:
        instrumentation:
          enabled: true
          enabledNamespaces: # Add namespaces to instrument
             - namespace_1
             - namespace_2

   datadog:
      apm:
        instrumentation:
          enabled: true
          disabledNamespaces: # Add namespaces to not instrument
            - namespace_1
            - namespace_2

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    # ...
spec:
  template:
    metadata:
      annotations:
        admission.datadoghq.com/java-lib.version: "<CONTAINER IMAGE TAG>"
    spec:
      containers:
        - # ...

   features:
     apm:
       instrumentation:
         enabled: true
         libVersions: # Add any libraries and versions you want to set
            dotnet: "x.x.x"
            python: "x.x.x"
            js: "x.x.x"

   datadog:
     apm:
       instrumentation:
         enabled: true
         libVersions: # Add any libraries and versions you want to set
            dotnet: "x.x.x"
            python: "x.x.x"
            js: "x.x.x"

デフォルトのイメージレジストリを変更する

Datadog は、以下の gcr.io、Docker Hub、Amazon ECR にインスツルメンテーションライブラリのイメージを公開しています。

Datadog Cluster Agent の構成の中の DD_ADMISSION_CONTROLLER_AUTO_INSTRUMENTATION_CONTAINER_REGISTRY 環境変数は、Admission Controller が使用するレジストリを指定します。デフォルト値は gcr.io/datadoghq です。

ローカルコンテナレジストリでイメージをホストしている場合は、docker.io/datadog、public.ecr.aws/datadog、または他の URL に変更することによって、別のレジストリから SDK をプルできます。

コンテナレジストリを変更する手順については、コンテナレジストリの変更を参照してください。

プライベートコンテナレジストリを使用する

組織で公開レジストリ (gcr.io、docker.io、public.ecr.aws など) からの直接プルが許可されていない場合は、必要な Datadog イメージを内部でホスティングし、Admission Controller がそれらを使用するように構成できます。

プライベートコンテナレジストリで SSI を使用するには、次のようにします。

1. Datadog のコンテナイメージをプライベートレジストリにミラーリングするには、これらの手順に従ってください。

   必要なのは、インスツルメントする言語のイメージだけです。どのイメージが必要か不明な場合、ほとんどのケースをカバーする基本的なラインを以下に示します。

   • apm-inject
   • dd-lib-java-init
   • dd-lib-python-init
   • dd-lib-dotnet-init
   • dd-lib-php-init
   • dd-lib-ruby-init
   • dd-lib-js-init

   これらのイメージは、gcr.io、Docker Hub、または Amazon ECR Public Gallery にあります。

2. イメージを構成に従ってタグ付けします。

   ミラーリングするバージョンは、ワークロードで設定されているバージョンと一致している必要があります。これらは以下のいずれかの方法で設定されていることがあります。

   • ddTraceVersions を使用してAgent の設定でグローバルに、または
   • admission.datadoghq.com/java-lib.version のようにアノテーションを使用して Pod ごとに。

   明示的にバージョンが設定されていない場合は、デフォルトバージョン (0) が使用されます。

   たとえば、次のとおりです。

   apm:
     instrumentation:
       enabled: true
       targets:
         - name: "default-target"
           ddTraceVersions:
             java: "1"
             python: "3"
   

   この構成には、以下のイメージタグが必要です。

   • apm-inject:0
   • dd-lib-java-init:1
   • dd-lib-python-init:3

3. プライベートレジストリを使用するよう、クラスター Agent 構成を更新します。

   プライベートレジストリを使用するように、クラスター Agent 構成の中で DD_ADMISSION_CONTROLLER_AUTO_INSTRUMENTATION_CONTAINER_REGISTRY 環境変数を設定します。

コンテナレジストリを変更する詳細については、コンテナレジストリの変更を参照してください。

EKS でのコンテナネットワークインターフェースの使用

Calicoのような CNI を使用する場合、コントロールプレーンノードは Datadog の Admission Controller へのネットワーク接続を開始できず、「アドレスが許可されていない」というエラーが報告されます。 シングルステップインスツルメンテーションを使用するには、useHostNetwork: trueパラメーターにより Datadog のクラスターエージェントに変更を加えます。

datadog:
  ...

clusterAgent:
  useHostNetwork: true

  admissionController:
    ...

シングルステップ APM インスツルメンテーションを Agent から削除する

特定のサービス、ホスト、VM、またはコンテナでトレースデータを収集したくない場合は、以下の手順を実行してください。

特定のサービスのインスツルメンテーションを削除する

特定のサービスの APM インスツルメンテーションを削除してトレース送信を停止する場合は、以下のいずれかのようにすることができます。

インスツルメンテーションルールを使用して、特定のワークロードをターゲットにします (推奨)。

インスツルメンテーションルール (Agent v7.64 以上で利用可能) を使用すると、特定のアプリケーションのトレースを有効または無効にできます。構成の詳細についてはこちらでご確認ください。

Datadog Admission Controller を使用する

代替手段として、またはインスツルメンテーションルールをサポートしていないエージェントバージョンの場合、Pod にラベルを追加することにより、Pod の変更を無効にすることもできます。

1. Pod 指定で admission.datadoghq.com/enabled: ラベルを "false" に設定します。

   spec:
     template:
       metadata:
         labels:
           admission.datadoghq.com/enabled: "false"
   

2. 構成を適用します。

   kubectl apply -f /path/to/your/deployment.yaml
   

3. インスツルメンテーションを削除したいサービスを再起動します。

インフラストラクチャー上のすべてのサービスについて APM を削除する

トレースの送信を停止するには、APM をアンインストールしてインフラストラクチャーを再起動してください:

どのファイルを編集するかは、Datadog Operator か Helm で Single Step Instrumentation を有効にしたかによって異なります。

ベストプラクティス

SSI を有効にすると、クラスターのうちサポートされているすべてのプロセスが自動的にインスツルメントされ、数分以内にトレース生成が開始されます。

どこで APM を有効にするかを制御して、オーバーヘッドを削減するため、以下のベストプラクティスを考慮してください。

targets:
  - name: login-service
    namespaceSelector:
      matchNames: ["login-service"]
    ddTraceVersions:
      java: "1.48.2"    # pin version

targets:
  - name: default-target          # tag any pod *without* an override
    ddTraceVersions:
      java:   "1"   # stay on latest v1.x
      python: "3"   # stay on latest v3.x
      js:     "5"   # NodeJS
      php:    "1"
      dotnet: "3"

トラブルシューティング

SSI で APM を有効にする際に問題が発生した場合は、SSI トラブルシューティングガイドを参照してください。

参考資料

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

ランタイムメトリクスを有効にするドキュメント init コンテナのリソース使用量の詳細ドキュメント ローカル SDK 注入を使用してアプリケーションをインスツルメントするドキュメント Kubernetes でのシングルステップインスツルメンテーションの構成ラーニングセンター