在 Amazon EKS 叢集上啟用 Application Signals

在現有 Amazon EKS 叢集上為您的應用程式啟用 Application Signals

1. 透過 https://console.aws.amazon.com/cloudwatch/ 開啟 CloudWatch 主控台。

2. 選擇 Application Signals。

3. 針對指定平台，選擇 EKS。

4. 針對選取 EKS 叢集，選取要啟用 Application Signals 的叢集。

5. 如果此叢集尚未啟用 Amazon CloudWatch Observability EKS 附加元件，系統會提示您啟用它。在此情況下，請執行下列操作：

   1. 選擇新增 CloudWatch Observability EKS 附加元件。Amazon EKS 主控台會出現。

   2. 選取 Amazon CloudWatch Observability 的核取方塊，然後選擇下一步。

      CloudWatch Observability EKS 附加元件會啟用 Application Signals 和 CloudWatch Container Insights，搭配 Amazon EKS 的增強可觀測性。如需更多 Container Insights 的相關資訊，請參閱 Container Insights。

   3. 選取最新版本的附加元件進行安裝。

   4. 選取要用於附加元件的 IAM 角色。如果選擇從節點繼承，請將正確的許可附接至工作節點使用的 IAM 角色。使用 Kubernetes 工作節點使用的 IAM 角色，來取代 my-worker-node-role。

      aws iam attach-role-policy \
      --role-name my-worker-node-role \
      --policy-arn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy \
      --policy-arn arn:aws:iam::aws:policy/AWSXRayWriteOnlyAccess

   5. 如果想要建立服務角色以使用附加元件，請參閱 使用 Amazon CloudWatch 可觀測性 EKS 附加元件或 Helm Chart 安裝 CloudWatch 代理程式 Amazon CloudWatch 。

   6. 選擇下一步，確認畫面上的資訊，然後選擇建立。

   7. 在下一個畫面中，選擇啟用 CloudWatch Application Signals 以返回 CloudWatch 主控台並完成此程序。

6. 為 Application Signals 啟用應用程式的方法有兩種。為保持一致性，建議您為每個叢集選擇一個選項。

   • 主控台選項更簡單。使用此方法會導致您的 Pod 即刻重新啟動。

   • 透過註釋資訊清單檔案方法，您可以進一步控制 Pod 重新啟動的時間，如果不想集中管控，還能以更分散的方式管理監控。

   注意

   如果使用 ESM 為 Node.js 應用程式啟用 Application Signals，請跳至 設定採用 ESM 模組格式的 Node.js 應用程式。

   Console

   主控台選項使用 Amazon CloudWatch Observability EKS 附加元件的進階組態，為您的服務設定 Application Signals。如需有關附加元件的詳細資訊，請參閱(選用) 額外組態。

   如果看不到工作負載和命名空間的清單，請確定您具備檢視此叢集相關項目的許可。如需詳細資訊，請參閱必要許可。

   可以選取自動監控核取方塊來監控所有服務工作負載，或者選擇性地選擇要監控的特定工作負載和命名空間。

   使用自動監控功能監控所有服務工作負載：

   1. 選取自動監控核取方塊，以自動選取叢集中的所有服務工作負載。

   2. 選擇自動重新啟動以重新啟動所有工作負載 Pod，以使用注入 Pod 的 AWS Distro for OpenTelemetry 自動檢測 (ADOT) SDKs，立即啟用 Application Signals。

   3. 選擇完成。選取自動重新啟動時，CloudWatch Observability EKS 附加元件將即刻啟用 Application Signals。否則，Application Signals 會在每個工作負載的下次部署期間啟用。

   可以監控單一工作負載或整個命名空間。

   若要監控單一工作負載：

   1. 選取想要監控的工作負載旁的核取方塊。

   2. 使用選取語言下拉式清單選取工作負載的語言。選取要啟用 Application Signals 的語言，然後選擇核取記號圖示 (✓) 儲存此選項。

      對於 Python 應用程式，請先確定您的應用程式遵循必要的先決條件，然後再繼續。如需詳細資訊，請參閱啟用 Application Signals 後，Python 應用程式無法啟動。

   3. 選擇完成。Amazon CloudWatch 可觀測性 EKS 附加元件會立即將 AWS Distro for OpenTelemetry 自動檢測 (ADOT) SDKs 注入您的 Pod，並觸發 Pod 重新啟動，以啟用應用程式指標和追蹤的集合。

   若要監控整個命名空間：

   1. 選取想要監控的命名空間旁的核取方塊。

   2. 使用選取語言下拉式清單選取命名空間的語言。選取要啟用 Application Signals 的語言，然後選擇核取記號圖示 (✓) 儲存此選項。這適用於此命名空間中的所有工作負載，無論是目前已部署或未來將部署的工作負載。

      對於 Python 應用程式，請先確定您的應用程式遵循必要的先決條件，然後再繼續。如需詳細資訊，請參閱啟用 Application Signals 後，Python 應用程式無法啟動。

   3. 選擇完成。Amazon CloudWatch 可觀測性 EKS 附加元件會立即將 AWS Distro for OpenTelemetry 自動檢測 (ADOT) SDKs 注入您的 Pod，並觸發 Pod 重新啟動，以啟用應用程式指標和追蹤的集合。

   若要在其他 Amazon EKS 叢集中啟用 Application Signals，請從服務畫面中選擇啟用 Application Signals。

   Annotate manifest file

   在 CloudWatch 主控台中，監控服務區段會說明，您必須將注釋新增至叢集中的資訊清單檔案 YAML。新增此注釋會自動檢測應用程式，以便將指標、追蹤和日誌傳送至 Application Signals。

   有兩個注釋選項：

   • 標註工作負載會自動檢測叢集中的單一工作負載。

   • 標註命名空間會自動檢測所選命名空間中部署的所有工作負載。

   選擇其中一個選項，然後遵循適當的步驟：

   • 若要標註單一工作負載：

     1. 選擇標註工作負載。

     2. 將下列行之一貼到工作負載資訊清單檔案的 PodTemplate 區段中。

        • 對於 Java 工作負載： annotations: instrumentation.opentelemetry.io/inject-java: "true"

        • 對於 Python 工作負載： annotations: instrumentation.opentelemetry.io/inject-python: "true"

          對於 Python 應用程式，還需進行額外的必要設定。如需詳細資訊，請參閱啟用 Application Signals 後，Python 應用程式無法啟動。

        • 對於 .NET 工作負載 annotations: instrumentation.opentelemetry.io/inject-dotnet: "true"

          注意

          若要為以 Alpine Linux (linux-musl-x64) 為基礎之映像上的 .NET 工作負載啟用 Application Signals，請新增下列註釋。

          instrumentation.opentelemetry.io/otel-dotnet-auto-runtime: "linux-musl-x64"

        • 對於 Node.js 工作負載： annotations: instrumentation.opentelemetry.io/inject-nodejs: "true"

     3. 在終端中，輸入 kubectl apply -f your_deployment_yaml 以套用變更。

   • 若要標註命名空間中的所有工作負載：

     1. 選擇標註命名空間。

     2. 將下列行之一貼到命名空間資訊清單檔案的中繼資料區段中。如果命名空間包含 Java、Python 和 .NET 工作負載，請將下列所有行貼入命名空間資訊清單檔案。

        • 如果命名空間中有 Java 工作負載： annotations: instrumentation.opentelemetry.io/inject-java: "true"

        • 如果命名空間中有 Python 工作負載： annotations: instrumentation.opentelemetry.io/inject-python: "true"

          對於 Python 應用程式，還需進行額外的必要設定。如需詳細資訊，請參閱啟用 Application Signals 後，Python 應用程式無法啟動。

        • 如果命名空間中有 .NET 工作負載： annotations: instrumentation.opentelemetry.io/inject-dotnet: "true"

        • 如果命名空間中有 Node.JS 工作負載： annotations: instrumentation.opentelemetry.io/inject-nodejs: "true"

     3. 在終端中，輸入 kubectl apply -f your_namespace_yaml 以套用變更。

     4. 在終端中，輸入命令以重新啟動命名空間中的所有 Pod。重新啟動部署工作負載的範例命令為 kubectl rollout restart deployment -n namespace_name

7. 選擇完成後檢視服務。這會帶您前往 Application Signals Services 檢視，您可以在其中查看 Application Signals 正在收集的資料。可能需要幾分鐘的時間才會顯示資料。

   若要在其他 Amazon EKS 叢集中啟用 Application Signals，請從服務畫面中選擇啟用 Application Signals。

   如需服務檢視的詳細資訊，請參閱 使用 Application Signals 監控應用程式的運作狀態。

為採用 ESM 的 Node.js 應用程式啟用 Application Signals

1. 將相關的相依項安裝到 Node.js 應用程式以進行自動檢測：

   npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation
   npm install @opentelemetry/instrumentation@0.54.0

2. 將下列環境變數新增至應用程式的 Dockerfile，然後建置映像。

   ...
   ENV OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true
   ENV OTEL_TRACES_SAMPLER_ARG='endpoint=http://cloudwatch-agent.amazon-cloudwatch:2000'
   ENV OTEL_TRACES_SAMPLER='xray'
   ENV OTEL_EXPORTER_OTLP_PROTOCOL='http/protobuf'
   ENV OTEL_EXPORTER_OTLP_TRACES_ENDPOINT='http://cloudwatch-agent.amazon-cloudwatch:4316/v1/traces'
   ENV OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT='http://cloudwatch-agent.amazon-cloudwatch:4316/v1/metrics'
   ENV OTEL_METRICS_EXPORTER='none'
   ENV OTEL_LOGS_EXPORTER='none'
   ENV NODE_OPTIONS='--import @aws/aws-distro-opentelemetry-node-autoinstrumentation/register --experimental-loader=@opentelemetry/instrumentation/hook.mjs'
   ENV OTEL_SERVICE_NAME='YOUR_SERVICE_NAME' #replace with a proper service name
   ENV OTEL_PROPAGATORS='tracecontext,baggage,b3,xray'
   ...
   
   # command to start the application
   # for example
   # CMD ["node", "index.mjs"]

3. 將環境變數 OTEL_RESOURCE_ATTRIBUTES_POD_NAME、OTEL_RESOURCE_ATTRIBUTES_NODE_NAME、OTEL_RESOURCE_ATTRIBUTES_DEPLOYMENT_NAME、POD_NAMESPACE 和 OTEL_RESOURCE_ATTRIBUTES 新增至應用程式的部署 yaml 檔案。例如：

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: nodejs-app
     labels:
       app: nodejs-app
   spec:
     replicas: 2
     selector:
       matchLabels:
         app: nodejs-app
     template:
       metadata:
         labels:
           app: nodejs-app
         # annotations:
         # make sure this annotation doesn't exit
         #   instrumentation.opentelemetry.io/inject-nodejs: 'true'
       spec:
         containers:
         - name: nodejs-app
           image:your-nodejs-application-image #replace with a proper image uri
           imagePullPolicy: Always
           ports:
           - containerPort: 8000
           env:
             - name: OTEL_RESOURCE_ATTRIBUTES_POD_NAME
               valueFrom:
                 fieldRef:
                   fieldPath: metadata.name
             - name: OTEL_RESOURCE_ATTRIBUTES_NODE_NAME
               valueFrom:
                 fieldRef:
                   fieldPath: spec.nodeName
             - name: OTEL_RESOURCE_ATTRIBUTES_DEPLOYMENT_NAME
               valueFrom:
                 fieldRef:
                   fieldPath: metadata.labels['app'] # Assuming 'app' label is set to the deployment name
             - name: POD_NAMESPACE
               valueFrom:
                 fieldRef:
                   fieldPath: metadata.namespace
             - name: OTEL_RESOURCE_ATTRIBUTES
               value: "k8s.deployment.name=$(OTEL_RESOURCE_ATTRIBUTES_DEPLOYMENT_NAME),k8s.namespace.name=$(POD_NAMESPACE),k8s.node.name=$(OTEL_RESOURCE_ATTRIBUTES_NODE_NAME),k8s.pod.name=$(OTEL_RESOURCE_ATTRIBUTES_POD_NAME)"

4. 將 Node.js 應用程式部署至叢集。

1. 為您的應用程式啟用 Application Signals。

   import { aws_applicationsignals as applicationsignals } from 'aws-cdk-lib';
   
   const cfnDiscovery = new applicationsignals.CfnDiscovery(this,
     'ApplicationSignalsServiceRole', { }
   );

   Discovery CloudFormation 資源將授與 Application Signals 下列許可：

   • xray:GetServiceGraph

   • logs:StartQuery

   • logs:GetQueryResults

   • cloudwatch:GetMetricData

   • cloudwatch:ListMetrics

   • tag:GetResources

   如需有關此角色的詳細資訊，請參閱 CloudWatch Application Signals 的服務連結角色許可。

2. 安裝 amazon-cloudwatch-observability 附加元件。

   1. 使用與叢集關聯的 CloudWatchAgentServerPolicy 和 OIDC 建立 IAM 角色。

      const cloudwatchRole = new Role(this, 'CloudWatchAgentAddOnRole', {
          assumedBy: new OpenIdConnectPrincipal(cluster.openIdConnectProvider),
          managedPolicies: [ManagedPolicy.fromAwsManagedPolicyName('CloudWatchAgentServerPolicy')],
      });

3. 使用上面建立的 IAM 角色安裝附加元件。

   new CfnAddon(this, 'CloudWatchAddon', {
       addonName: 'amazon-cloudwatch-observability',
       clusterName: cluster.clusterName,
       serviceAccountRoleArn: cloudwatchRole.roleArn
   });

4. 將下列其中一項新增至工作負載資訊清單檔案的 PodTemplate 區段。

   Language	檔案
   Java	instrumentation.opentelemetry.io/inject-java: "true"
   Python	instrumentation.opentelemetry.io/inject-python: "true"
   .Net	instrumentation.opentelemetry.io/inject-dotnet: "true"
   Node.js	instrumentation.opentelemetry.io/inject-nodejs: "true"

   const deployment = {
     apiVersion: "apps/v1",
     kind: "Deployment",
     metadata: { name: "sample-app" },
     spec: {
       replicas: 3,
       selector: {
         matchLabels: {
           "app": "sample-app"
         }
       },
       template: {
         metadata: {
           labels: {
             "app": "sample-app"
           },
           annotations: {
             "instrumentation.opentelemetry.io/inject-$LANG": "true"
           }
         },
         spec: {...},
       },
     },
   };
   
   cluster.addManifest('sample-app', deployment)