本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 在 Amazon EKS 叢集上啟用 Application Signals CloudWatch Application Signals 支援 Java、Python、Node.js 和 .NET 應用程式。若要為現有 Amazon EKS 叢集上的應用程式啟用 Application Signals，您可以使用 AWS 管理主控台 AWS CDK或 CloudWatch Observability 附加元件 Auto 監控進階組態。 **Topics** + [ ## 透過主控台在 Amazon EKS 叢集上啟用 Application Signals ](#CloudWatch-Application-Signals-Enable-EKS-Console) + [ ## 使用 CloudWatch Observability 附加元件進階組態在 Amazon EKS 叢集上啟用 Application Signals ](#CloudWatch-Application-Signals-Enable-EKS-Addon) + [ ## 使用 在 Amazon EKS 上啟用 Application Signals AWS CDK ](#CloudWatch-Application-Signals-EKS-CDK) + [ ## 使用模型內容通訊協定 (MCP) 在 Amazon EKS 上啟用應用程式訊號 ](#CloudWatch-Application-Signals-EKS-MCP) ## 透過主控台在 Amazon EKS 叢集上啟用 Application Signals 若要在現有 Amazon EKS 叢集上為應用程式啟用 CloudWatch Application Signals，請依循本節中的說明操作。 **重要** 如果您已經在搭配使用 OpenTelemetry 與您想要為 Application Signals 啟用的應用程式，請在啟用 Application Signals 之前參閱 [支援的系統](CloudWatch-Application-Signals-supportmatrix.md)。 **在現有 Amazon EKS 叢集上為您的應用程式啟用 Application Signals** **注意** 如果尚未啟用 Application Signals，請遵循 [在您的帳戶中啟用 Application Signals](CloudWatch-Application-Signals-Enable.md) 中的說明，然後完成下列程序。 1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。 1. 選擇 **Application Signals**。 1. 針對**指定平台**，選擇 **EKS**。 1. 針對**選取 EKS 叢集**，選取要啟用 Application Signals 的叢集。 1. 如果此叢集尚未啟用 Amazon CloudWatch Observability EKS 附加元件，系統會提示您啟用它。在此情況下，請執行下列操作： 1. 選擇**新增 CloudWatch Observability EKS 附加元件**。Amazon EKS 主控台會出現。 1. 選取 **Amazon CloudWatch Observability** 的核取方塊，然後選擇**下一步**。 CloudWatch Observability EKS 附加元件會啟用 Application Signals 和 CloudWatch Container Insights，搭配 Amazon EKS 的增強可觀測性。如需更多 Container Insights 的相關資訊，請參閱 [Container Insights](ContainerInsights.md)。 1. 選取最新版本的附加元件進行安裝。 1. 選取要用於附加元件的 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 ``` 1. 如果想要建立服務角色以使用附加元件，請參閱 [使用 Amazon CloudWatch Observability EKS 附加元件或 Helm Chart 安裝 CloudWatch 代理程式](install-CloudWatch-Observability-EKS-addon.md)。 1. 選擇**下一步**，確認畫面上的資訊，然後選擇**建立**。 1. 在下一個畫面中，選擇**啟用 CloudWatch Application Signals** 以返回 CloudWatch 主控台並完成此程序。 1. 為 Application Signals 啟用應用程式的方法有兩種。為保持一致性，建議您為每個叢集選擇一個選項。 + **主控台**選項更簡單。使用此方法會導致您的 Pod 即刻重新啟動。 + 透過**註釋資訊清單檔案**方法，您可以進一步控制 Pod 重新啟動的時間，如果不想集中管控，還能以更分散的方式管理監控。 **注意** 如果使用 ESM 為 Node.js 應用程式啟用 Application Signals，請跳至 [設定採用 ESM 模組格式的 Node.js 應用程式](#EKS-NodeJs-ESM)。 ------ #### [ Console ] **主控台**選項使用 Amazon CloudWatch Observability EKS 附加元件的進階組態，為您的服務設定 Application Signals。如需有關附加元件的詳細資訊，請參閱[(選用) 額外組態](install-CloudWatch-Observability-EKS-addon.md#install-CloudWatch-Observability-EKS-addon-configuration)。 如果看不到工作負載和命名空間的清單，請確定您具備檢視此叢集相關項目的許可。如需詳細資訊，請參閱[必要許可](https://docs.aws.amazon.com/eks/latest/userguide/view-kubernetes-resources.html#view-kubernetes-resources-permissions)。 可以選取**自動監控**核取方塊來監控所有服務工作負載，或者選擇性地選擇要監控的特定工作負載和命名空間。 使用自動監控功能監控所有服務工作負載： 1. 選取**自動監控**核取方塊，以自動選取叢集中的所有服務工作負載。 1. 選擇**自動重新啟動**以重新啟動所有工作負載 Pod，以使用注入 Pod 的 AWS Distro for OpenTelemetry 自動檢測 (ADOT) SDKs，立即啟用 Application Signals。 1. 選擇**完成**。選取**自動重新啟動**時，CloudWatch Observability EKS 附加元件將即刻啟用 Application Signals。否則，Application Signals 會在每個工作負載的下次部署期間啟用。 可以監控單一工作負載或整個命名空間。 若要監控單一工作負載： 1. 選取想要監控的工作負載旁的核取方塊。 1. 使用**選取語言**下拉式清單選取工作負載的語言。選取要啟用 Application Signals 的語言，然後選擇核取記號圖示 (✓) 儲存此選項。 對於 Python 應用程式，請先確定您的應用程式遵循必要的先決條件，然後再繼續。如需詳細資訊，請參閱[啟用 Application Signals 後，Python 應用程式無法啟動](CloudWatch-Application-Signals-Enable-Troubleshoot.md#Application-Signals-troubleshoot-starting-Python)。 1. 選擇**完成**。Amazon CloudWatch 可觀測性 EKS 附加元件會立即將 AWS Distro for OpenTelemetry 自動檢測 (ADOT) SDKs 注入您的 Pod，並觸發 Pod 重新啟動，以啟用應用程式指標和追蹤的集合。 若要監控整個命名空間： 1. 選取想要監控的命名空間旁的核取方塊。 1. 使用**選取語言**下拉式清單選取命名空間的語言。選取要啟用 Application Signals 的語言，然後選擇核取記號圖示 (✓) 儲存此選項。這適用於此命名空間中的所有工作負載，無論是目前已部署或未來將部署的工作負載。 對於 Python 應用程式，請先確定您的應用程式遵循必要的先決條件，然後再繼續。如需詳細資訊，請參閱[啟用 Application Signals 後，Python 應用程式無法啟動](CloudWatch-Application-Signals-Enable-Troubleshoot.md#Application-Signals-troubleshoot-starting-Python)。 1. 選擇**完成**。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. 選擇**標註工作負載**。 1. 將下列行之一貼到工作負載資訊清單檔案的 `PodTemplate` 區段中。 + **對於 Java 工作負載：** `annotations: instrumentation.opentelemetry.io/inject-java: "true"` + **對於 Python 工作負載：** `annotations: instrumentation.opentelemetry.io/inject-python: "true"` 對於 Python 應用程式，還需進行額外的必要設定。如需詳細資訊，請參閱[啟用 Application Signals 後，Python 應用程式無法啟動](CloudWatch-Application-Signals-Enable-Troubleshoot.md#Application-Signals-troubleshoot-starting-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"` 1. 在終端中，輸入 `kubectl apply -f your_deployment_yaml` 以套用變更。 + 若要標註命名空間中的所有工作負載： 1. 選擇**標註命名空間**。 1. 將下列行之一貼到命名空間資訊清單檔案的中繼資料區段中。如果命名空間包含 Java、Python 和 .NET 工作負載，請將下列所有行貼入命名空間資訊清單檔案。 + **如果命名空間中有 Java 工作負載：** `annotations: instrumentation.opentelemetry.io/inject-java: "true"` + **如果命名空間中有 Python 工作負載：** `annotations: instrumentation.opentelemetry.io/inject-python: "true"` 對於 Python 應用程式，還需進行額外的必要設定。如需詳細資訊，請參閱[啟用 Application Signals 後，Python 應用程式無法啟動](CloudWatch-Application-Signals-Enable-Troubleshoot.md#Application-Signals-troubleshoot-starting-Python)。 + **如果命名空間中有 .NET 工作負載：** `annotations: instrumentation.opentelemetry.io/inject-dotnet: "true"` + **如果命名空間中有 Node.JS 工作負載：** `annotations: instrumentation.opentelemetry.io/inject-nodejs: "true"` 1. 在終端中，輸入 `kubectl apply -f your_namespace_yaml` 以套用變更。 1. 在終端中，輸入命令以重新啟動命名空間中的所有 Pod。重新啟動部署工作負載的範例命令為 `kubectl rollout restart deployment -n namespace_name` ------ 1. 選擇**完成後檢視服務**。這會帶您前往 Application Signals Services 檢視，您可以在其中查看 Application Signals 正在收集的資料。可能需要幾分鐘的時間才會顯示資料。 若要在其他 Amazon EKS 叢集中啟用 Application Signals，請從**服務**畫面中選擇**啟用 Application Signals**。 如需**服務**檢視的詳細資訊，請參閱 [使用 Application Signals 監控應用程式的運作狀態](Services.md)。 **注意** 如果為 Python 應用程式使用 WSGI 伺服器，請參閱 [使用 WSGI 伺服器的 Python 應用程式沒有 Application Signals 資料](CloudWatch-Application-Signals-Enable-Troubleshoot.md#Application-Signals-troubleshoot-Python-WSGI) 以取得有關使 Application Signals 正常運作的資訊。 我們還發現其他需留意事項，當您為 Application Signals 啟用 Python 應用程式時，應謹記於心。如需詳細資訊，請參閱[啟用 Application Signals 後，Python 應用程式無法啟動](CloudWatch-Application-Signals-Enable-Troubleshoot.md#Application-Signals-troubleshoot-starting-Python)。 ### 設定採用 ESM 模組格式的 Node.js 應用程式 對於採用 ESM 模組格式的 Node.js 應用程式，我們提供有限支援。如需詳細資訊，請參閱[Node.js 搭配使用 ESM 的已知限制](CloudWatch-Application-Signals-supportmatrix.md#ESM-limitations)。 對於 ESM 模組格式，無法透過主控台或透過標註資訊清單檔案來啟用 Application Signals。略過先前程序的步驟 8，然後改為執行下列動作。 **為採用 ESM 的 Node.js 應用程式啟用 Application Signals** 1. 將相關的相依項安裝到 Node.js 應用程式以進行自動檢測： ``` npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation npm install @opentelemetry/instrumentation@0.54.0 ``` 1. 將下列環境變數新增至應用程式的 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"] ``` 1. 將環境變數 `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)" ``` 1. 將 Node.js 應用程式部署至叢集。 在 Amazon EKS 上啟用應用程式後，即可監控應用程式的運作狀態。如需詳細資訊，請參閱[使用 Application Signals 監控應用程式的運作狀態](Services.md)。 ## 使用 CloudWatch Observability 附加元件進階組態在 Amazon EKS 叢集上啟用 Application Signals 根據預設，安裝 CloudWatch 可觀測性 EKS 附加元件 (V5.0.0 或更高版本） 或 Helm Chart 時，透過 Application Signals 啟用 OpenTelemetry (OTEL) 型應用程式效能監控 (APM)。您可以使用 Amazon EKS 附加元件的進階組態或使用 Helm Chart 覆寫值，進一步自訂具體設定。 **注意** 如果您使用任何 OpenTelemetry (OTEL) 型 APM 解決方案，啟用 Application Signals 會影響您現有的可觀測性設定。在繼續之前，請先檢閱您目前的實作。若要在升級至 V5.0.0 或更新版本後維護現有的 APM 設定，請參閱 [選擇不接收 Application Signals](install-CloudWatch-Observability-EKS-addon.md#Opting-out-App-Signals)。 CloudWatch Observability 附加元件還提供更細緻的控制選項，可視需要在新的進階組態中包含或排除特定服務。如需詳細資訊，請參閱 [透過 Amazon EKS 叢集的 Application Signals 啟用 APM](install-CloudWatch-Observability-EKS-addon.md#Container-Insights-setup-EKS-appsignalsconfiguration)。 ## 使用 在 Amazon EKS 上啟用 Application Signals AWS CDK 如果尚未在此帳戶中啟用 Application Signals，則必須授予 Application Signals 所需的許可，以探索您的服務。請參閱 [在您的帳戶中啟用 Application Signals](CloudWatch-Application-Signals-Enable.md)。 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 的服務連結角色許可](using-service-linked-roles.md#service-linked-role-signals)。 1. 安裝 `amazon-cloudwatch-observability` 附加元件。 1. 使用與叢集關聯的 `CloudWatchAgentServerPolicy` 和 OIDC 建立 IAM 角色。 ``` const cloudwatchRole = new Role(this, 'CloudWatchAgentAddOnRole', { assumedBy: new OpenIdConnectPrincipal(cluster.openIdConnectProvider), managedPolicies: [ManagedPolicy.fromAwsManagedPolicyName('CloudWatchAgentServerPolicy')], }); ``` 1. 使用上面建立的 IAM 角色安裝附加元件。 ``` new CfnAddon(this, 'CloudWatchAddon', { addonName: 'amazon-cloudwatch-observability', clusterName: cluster.clusterName, serviceAccountRoleArn: cloudwatchRole.roleArn }); ``` 1. 將下列其中一項新增至工作負載資訊清單檔案的 `PodTemplate` 區段。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable-EKS.html) ``` 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) ``` ## 使用模型內容通訊協定 (MCP) 在 Amazon EKS 上啟用應用程式訊號 您可以使用 CloudWatch Application Signals 模型內容通訊協定 (MCP) 伺服器，透過對話式 AI 互動在 Amazon EKS 叢集上啟用 Application Signals。這提供用於設定 Application Signals 監控的自然語言界面。 MCP 伺服器會了解您的需求並產生適當的組態，以自動化啟用程序。您可以直接描述要啟用的內容，而不是手動遵循主控台步驟或撰寫 CDK 程式碼。 ### 先決條件 使用 MCP 伺服器啟用 Application Signals 之前，請確定您已： + 支援 MCP 的開發環境 （例如 Kiro、Claude Desktop、VSCode 搭配 MCP 延伸模組或其他 MCP 相容工具） + 在您的 IDE 中設定的 CloudWatch Application Signals MCP 伺服器。如需詳細設定說明，請參閱 [CloudWatch Application Signals MCP Server 文件](https://awslabs.github.io/mcp/servers/cloudwatch-applicationsignals-mcp-server)。 ### 使用 MCP 伺服器 在 IDE 中設定 CloudWatch Application Signals MCP 伺服器後，您可以使用自然語言提示請求啟用指引。雖然編碼助理可以從專案結構推斷內容，但在提示中提供特定詳細資訊有助於確保更準確和相關的指導。包含您的應用程式語言、Amazon EKS 叢集名稱，以及基礎設施和應用程式程式碼的絕對路徑等資訊。 **最佳實務提示 （特定且完整）：** ``` "Enable Application Signals for my Python service running on EKS. My app code is in /home/user/flask-api and IaC is in /home/user/flask-api/terraform" "I want to add observability to my Node.js application on EKS cluster 'production-cluster'. The application code is at /Users/dev/checkout-service and the Kubernetes manifests are at /Users/dev/checkout-service/k8s" "Help me instrument my Java Spring Boot application on EKS with Application Signals. Application directory: /opt/apps/payment-api CDK infrastructure: /opt/apps/payment-api/cdk" ``` **效率較低的提示：** ``` "Enable monitoring for my app" → Missing: platform, language, paths "Enable Application Signals. My code is in ./src and IaC is in ./infrastructure" → Problem: Relative paths instead of absolute paths "Enable Application Signals for my EKS service at /home/user/myapp" → Missing: programming language ``` **快速範本：** ``` "Enable Application Signals for my [LANGUAGE] service on EKS. App code: [ABSOLUTE_PATH_TO_APP] IaC code: [ABSOLUTE_PATH_TO_IAC]" ``` ### 使用 MCP 伺服器的優點 使用 CloudWatch Application Signals MCP 伺服器有幾個優點： + **自然語言界面：**描述您想要啟用的內容，而不記住命令或組態語法 + **內容感知指引：**MCP 伺服器了解您的特定環境，並提供量身打造的建議 + **減少錯誤：**自動化組態產生可將手動輸入錯誤降至最低 + **更快的設定：**更快速地從意圖到實作 + **學習工具：**查看產生的組態並了解 Application Signals 的運作方式 ### 其他資源 如需有關設定和使用 CloudWatch Application Signals MCP 伺服器的詳細資訊，請參閱 [MCP 伺服器文件](https://awslabs.github.io/mcp/servers/cloudwatch-applicationsignals-mcp-server)。