このページでは、クラスタエージェントの自動インストゥルメンテーションを検証およびトラブルシューティングする方法について説明します。

前提条件

自動インストゥルメンテーションの検証

  1. 自動インストゥルメンテーションを適用した後、選択した名前戦略に基づいて割り当てられたアプリケーション名を使用して、アプリケーションがコントローラにレポートしていることを確認します。「Auto-Instrument Applications with the Cluster Agent」を参照してください。

  2. 自動インストゥルメンテーションの対象となるアプリケーションポッドが再作成されたことを確認します。自動インストゥルメンテーションが適用されているため、kubectl get pods を -w フラグとともに使用して、ポッドステータスの更新をリアルタイムで出力します。正常に自動インストゥルメント化されたアプリケーションでは、アプリケーションポッドが再作成されたこと、正しい init コンテナが適用され、アプリケーション サーバ エージェントがアプリケーションコンテナにコピーされたことが示されます。

    kubectl -n <app ns> get pods -w
NAME                          READY   STATUS            RESTARTS   AGE
dotnet-app-85c7d66557-s8hzm   1/1     Running           0          3m11s
dotnet-app-6c45b6d4f-fpp75    0/1     Pending           0          0s
dotnet-app-6c45b6d4f-fpp75    0/1     Init:0/1          0          0s
dotnet-app-6c45b6d4f-fpp75    0/1     PodInitializing   0          5s
dotnet-app-6c45b6d4f-fpp75    1/1     Running           0          6s
dotnet-app-85c7d66557-s8hzm   1/1     Terminating       0          20m\
    BASH

    また、kubectl get pods -o yaml を使用して、アプリケーション仕様が init コンテナと init コンテナの状態を含むように更新されたかどうかを確認することもできます。

    kubectl -n <app-ns> get pod <app-pod> -o yaml
 ...
 initContainers:
  - command:
    - cp
    - -r
    - /opt/appdynamics/.
    - /opt/appdynamics-java
    image: docker.io/appdynamics/java-agent:latest
  ...
  initContainerStatuses:
  - containerID: docker://8bb892f322e5a043866d038631392a2272b143e54c8c431b3590312729043eb9
    image: appdynamics/java-agent:20.9.0
    imageID: docker-pullable://appdynamics/java-agent@sha256:077ac1c4f761914c1742f22b2f591a37a127713e3e96968e9e570747f7ba6134
    ...
    state:
      terminated:
        containerID: docker://8bb892f322e5a043866d038631392a2272b143e54c8c431b3590312729043eb9
        exitCode: 0
        finishedAt: "2021-02-03T22:39:25Z"
        reason: Completed
    YML

    インストゥルメンテーションが正常に完了した場合でも、ポッドアノテーションで Node.js および .NET Core（Linux）アプリケーションの APPD_POD_INSTRUMENTATION_STATE が failed と表示されることがあります。

適用されない場合の自動インストゥルメンテーションのトラブルシューティング

アプリケーションポッドが再作成されず、init コンテナが適用されなかった場合は、クラスタエージェントで使用される名前空間とアプリケーションの一致ルールに問題がある可能性があります。

  1. 最初に、クラスタエージェントが最新の自動インストゥルメンテーション構成を使用していることを確認します。

    kubectl -n appdynamics get cm instrumentation-config -o yaml
    CODE

    YAML 出力に最新の自動インストゥルメンテーション構成が反映されていない場合は、クラスタエージェントの YAML 設定を検証し、クラスタエージェントを適用またはアップグレードします。

    kubectl apply -f cluster-agent.yaml
    BASH 
    helm upgrade -f ./ca1-values.yaml "<my-cluster-agent-helm-release>" appdynamics-charts/cluster-agent --namespace appdynamics
    BASH

  2. ポッドがまだ再作成されていない場合は、クラスタエージェントの構成で DEBUG ロギングを有効にします。

    cluster-agent.yaml

    apiVersion: cluster.appdynamics.com/v1alpha1
kind: Clusteragent
metadata:
  name: k8s-cluster-agent
  namespace: appdynamics
spec:
  # content removed for brevity
  logLevel: DEBUG
    YML

    ca1-values.yaml

    clusterAgent:
  # content removed for brevity
  logProperties:
    logLevel: DEBUG
    YML

  3. クラスタエージェントを適用またはアップグレードして、DEBUG ロギング設定を更新します。

    kubectl apply -f cluster-agent.yaml
    BASH 
    helm upgrade -f ./ca1-values.yaml "<my-cluster-agent-helm-release>" appdynamics-charts/cluster-agent --namespace appdynamics
    BASH

  4. クラスタエージェントのロギング設定を更新したら、ログを追跡し、クラスタエージェントがアプリケーションを検出していること、およびアプリケーションを自動インストゥルメンテーションの対象範囲内と見なしていることを示すメッセージを検索します。

    # apply grep filter to see instrumentation related messages:
kubectl -n appdynamics logs <cluster-agent-pod> -f | grep -E 'instrumentationconfig.go|deploymenthandler.go'
    BASH

    ただし、（この例と同様に）自動インストゥルメント化するアプリケーションの出力が表示される場合には、クラスタエージェントはアプリケーションを自動インストゥルメンテーションの対象範囲内と見なしていません。

    [DEBUG]: 2021-03-30 21:22:09 - instrumentationconfig.go:660 - No matching rule found for Deployment dotnet-app in namespace stage with labels map[appName:jah-stage framework:dotnetcore]
[DEBUG]: 2021-03-30 21:22:09 - instrumentationconfig.go:249 - Instrumentation state for Deployment dotnet-app in namespace stage with labels map[appName:jah-stage framework:dotnetcore] is false
    BASH

    自動インストゥルメンテーション構成を確認して必要な更新を決定し、変更を保存します。次に、前述のようにクラスタエージェントを削除して再作成します。たとえば、namespaceRegex を使用して instrumentationRule の名前空間設定を上書きした場合は、必ず nsToInstrumentRegex に含まれている値（例の dev）を使用してください。

    apiVersion: cluster.appdynamics.com/v1alpha1
kind: Clusteragent
metadata:
  name: k8s-cluster-agent
  namespace: appdynamics
spec:
  # content removed for brevity
  nsToInstrumentRegex: stage|dev
  instrumentationRules:
    - namespaceRegex: dev
    YML

    設定を更新し、クラスタエージェントが再作成されると、出力は次の例のようになります。これは、クラスタエージェントがアプリケーションを自動インストゥルメンテーションの対象範囲内として認識していることを示しています。

    [DEBUG]: 2021-03-30 21:22:10 - instrumentationconfig.go:645 - rule stage matches Deployment spring-boot-multicontainer in namespace stage with labels map[appName:jah-stage acme.com/framework:java]
[DEBUG]: 2021-03-30 21:22:10 - instrumentationconfig.go:656 - Found a matching rule {stage  map[acme.com/framework:[java]]   java select .*  JAVA_TOOL_OPTIONS map[agent-mount-path:/opt/appdynamics image:docker.io/appdynamics/java-agent:21.3.0 image-pull-policy:IfNotPresent] map[bci-enabled:true port:3892] 0 0 appName  0 false []} for Deployment spring-boot-multicontainer in namespace stage with labels map[appName:jah-stage acme.com/framework:java]
[DEBUG]: 2021-03-30 21:22:10 - instrumentationconfig.go:249 - Instrumentation state for Deployment spring-boot-multicontainer in namespace stage with labels map[appName:jah-stage acme.com/framework:java] is true
[DEBUG]: 2021-03-30 21:22:10 - deploymenthandler.go:312 - Added instrument task to queue stage/spring-boot-multicontainer
    BASH

完了できなかった場合の自動インストゥルメンテーションのトラブルシューティング

アプリケーションポッドが再作成されたが、インストゥルメント化されたアプリケーションがコントローラにレポートしていない場合、自動インストゥルメンテーションが正常に完了しなかったか、アプリケーション サーバ エージェントがコントローラに登録できていません。

  1. アプリケーションポッドが再起動されても init コンテナが正常に実行されていない場合は、[Cluster Agent Events] ダッシュボードまたは kubectl get events を使用してアプリケーションの名前空間でイベントを確認します。init コンテナの実行を妨げる可能性のある一般的な問題としては、イメージプルまたはリソースクォータの問題があります。

    kubectl -n <app ns> get events
    BASH

  2. アプリケーションの導入仕様が init コンテナで更新されたこと、およびステータス情報にエラーが含まれているかどうかを確認します。

    kubectl -n <app-ns> get pod <app-pod> -o yaml
    BASH

  3. アプリケーションコンテナ内でシェルを起動して、自動インストゥルメンテーションの結果を確認します。アプリケーション サーバ エージェントの環境変数が正しく設定されているかどうか、およびログにエラーがないかどうかを確認します。

    kubectl -n <app-ns> exec -it <app-pod> /bin/sh
# Issue these commands in the container
env | grep APPD

# For Java app
env | grep JAVA_TOOL_OPTIONS # or value of defaultEnv
ls /opt/appdynamics-java
cat /opt/appdynamics-java/ver<version>/logs/<node-name>/agent.<date>.log

# For .NET Core app
ls /opt/appdynamics-dotnetcore
cat /tmp/appd/dotnet/1_agent_0.log

# For Node.js app
ls /opt/appdynamics-nodejs
cat /tmp/appd/<id>/appd_node_agent_<date>.log
    BASH

  4. Node.js または .NET Core アプリケーションをインストゥルメント化し、自動インストゥルメンテーション ファイルがアプリケーションコンテナにコピーされているが、アプリケーション サーバ エージェントのログが存在しない場合、またはバイナリの非互換性に関するエラーが表示される場合は、アプリケーションイメージとアプリケーション サーバ エージェント イメージ（自動インストゥルメンテーション構成の image プロパティで参照）の不一致がある可能性があります。
    .NET Core の場合、イメージ OS のバージョンが一致している必要があります（Linux など）。
    Node.js の場合、イメージ OS のバージョンと Node.js のバージョンが一致している必要があります。確認するには、イメージタグ、Dockerfile、またはアプリケーションコンテナに対する exec の実行をチェックします。

    $ kubectl -n <app-ns> exec -it <app-pod> /bin/sh
cat /etc/os-release   # (or /etc/issue)
NAME="Alpine Linux"... 
# for Node.js app
node -v
    CODE

    アップグレードされた展開の再インストゥルメンテーションの問題のトラブルシューティング

    • Helm アップグレードを使用して展開仕様を編集する場合、クラスタエージェントはアップグレードされた展開を再インストゥルメントしません。クラスタエージェントによって適用された仕様に対する変更がインストゥルメンテーション プロパティに干渉する場合、インストゥルメンテーションは動作を停止します。
      この問題は、Java インストゥルメンテーションで、Java アプリケーションが JAVA_TOOL_OPTION を使用していて、helm アップグレードによって展開仕様の JAVA_TOOL_OPTION 環境変数がオーバーライドされる可能性がある場合に主に発生します。
      Java エージェントがこの環境変数を使用してシステムプロパティを使用するためにオーバーライドが発生し、インストゥルメンテーションが失敗します。 
    • クラスタエージェントは、アノテーションを使用して、展開のインストゥルメンテーションの状態を確認します。展開ツールまたはスクリプトが編集またはパッチ Kubernetes API を使用して展開仕様を編集する場合、展開のアノテーションは更新されません。したがって、インストゥルメンテーションの状態に変更がない場合、再インストゥルメンテーションは発生しません。
      展開仕様のアノテーション APPD_POD_INSTRUMENTATION_STATE を APPD_POD_INSTRUMENTATION_STATE: Failed に更新すると、この問題を回避できます。