在 Amazon EKS 叢集上啟用您的應用程式

在現有 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 可觀測性 EKS 附加元件的進階組態，為您的服務設定 Application Signals。如需附加元件的詳細資訊，請參閱 (選用) 額外組態。

   如果您沒有看到工作負載和命名空間的清單，請確保您具有為此叢集檢視它們的正確許可。如需詳細資訊，請參閱必要許可。

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

   使用自動監控 （自動監控） 監控所有服務工作負載：

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

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

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

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

   若要監控單一工作負載：

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

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

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

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

   若要監控整個命名空間：

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

   2. 使用選取語言 (Select language) 下拉式清單來選取命名空間的語言。選取您要啟用 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_DEPLOYMENT_NAME、 OTEL_RESOURCE_ATTRIBUTES_NODE_NAMEPOD_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區段。

   語言	檔案
   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)