本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 疑難排解 Application Signals 安裝 本節包含 CloudWatch Application Signals 的疑難排解秘訣。 **Topics** + [使用 Application Signals 處理 Amazon EKS 中的 OpenTelemetry 組態衝突](#Application-Signals-troubleshoot-eks-applications) + [Application Signals Java Layer 冷啟動效能](#Application-Signals-troubleshoot-cold-start-performance) + [啟用 Application Signals 後，應用程式無法啟動。](#Application-Signals-troubleshoot-starting) + [啟用 Application Signals 後，Python 應用程式無法啟動](#Application-Signals-troubleshoot-starting-Python) + [使用 WSGI 伺服器的 Python 應用程式沒有 Application Signals 資料](#Application-Signals-troubleshoot-Python-WSGI) + [我的 Node.js 應用程式未經檢測或未產生 Application Signals 遙測](#Application-Signals-troubleshoot-telemetry-nodejs) + [我的 .NET 應用程式未檢測或中斷 AWS SDK 呼叫](#Application-Signals-troubleshoot-sdk-calls) + [Application Signals 儀表板中沒有應用程式資料](#Application-Signals-troubleshoot-missingdata) + [服務指標或相依項指標具有未知的值](#Application-Signals-troubleshoot-unknown-values) + [管理 Amazon CloudWatch Observability EKS 附加元件時處理 ConfigurationConflict](#Application-Signals-troubleshoot-conflict) + [我想要篩選掉不必要的指標和追蹤](#Application-Signals-troubleshoot-cardinality) + [`InternalOperation` 是什麼意思？](#Application-Signals-troubleshoot-InternalOperation) + [如何啟用 .NET 應用程式記錄？](#Application-Signals-troubleshoot-dotnet-logging) + [如何解決 .NET 應用程式中的組件版本衝突問題？](#Application-Signals-troubleshoot-dotnet-conflicts) + [可以停用 FluentBit 嗎？](#Application-Signals-troubleshoot-FluentBit) + [可以先篩選容器日誌，再匯出至 CloudWatch Logs 嗎？](#Application-Signals-troubleshoot-filter-logs) + [解決使用 AWS Distro for OpenTelemetry (ADOT) JavaScript Lambda Layer 時的 TypeError](#lambda-execution) + [搭配 AWS Distro for OpenTelemetry (ADOT) JavaScript Lambda Layer 使用 Response Streaming Lambda 處理常式時的 TypeError](#lambda-execution-streaming) + [更新必要版本的代理程式或 Amazon EKS 附加元件](#CloudWatch-Application-Signals-Agent-Versions) + [Application Signals 已停用內嵌指標格式 (EMF)](#emf-appsignals) ## 使用 Application Signals 處理 Amazon EKS 中的 OpenTelemetry 組態衝突 如果您使用 OpenTelemetry (OTel) 搭配 Amazon EKS 進行應用程式效能監控 (APM)，並設定 CloudWatch 端點以外的自訂 OTLP 匯出工具端點，則在安裝或升級至 CloudWatch Observability 附加元件 5.0.0 版或更新版本之後，您可能會遇到下列行為： + 中斷現有的 OTel 遙測 – CloudWatch 可觀測性附加元件可能會覆寫您在應用程式中硬式編碼的 OTLP 匯出工具端點。此覆寫不會影響透過容器環境變數或 ConfigMap `envFrom` 設定的端點。覆寫時，您的指標和追蹤可能無法到達其預期目的地。若要在升級至 V5.0.0 或更新版本後維護現有的 APM 設定，請參閱 [選擇不接收 Application Signals](install-CloudWatch-Observability-EKS-addon.md#Opting-out-App-Signals) + 如果您之前使用 CloudWatch 可觀測性附加元件啟用 Application Signals，並已設定自訂 OTLP 端點，則 Application Signals 可能無法運作。若要解決此問題，請在安裝或升級至 5.0.0 版或更新版本`OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true`時移除自訂 OTLP 端點或設定環境變數 ## Application Signals Java Layer 冷啟動效能 將 Application Signals Layer 新增至 Java Lambda 函式會增加啟動延遲 (冷啟動時間)。以下秘訣有助於減少時間敏感函式的延遲。 **Java 代理程式快速啟動 **：Application Signals Java Lambda Layer 包含一項預設關閉的快速啟動功能，可透過將 OTEL\$1JAVA\$1AGENT\$1FAST\$1STARTUP\$1ENABLED 變數設定為 true 來啟用。啟用此功能後，系統將設定 JVM 使用分層編譯等級 1 的 C1 編譯器，以產生快速最佳化的原生程式碼，從而加快冷啟動速度。C1 編譯器優先追求速度，但犧牲了長期最佳化；而 C2 編譯器則會長期分析效能資料，整體表現更卓越。 如需詳細資訊，請參閱 [Java 代理程式快速啟動](https://github.com/open-telemetry/opentelemetry-lambda/blob/main/java/README.md#fast-startup-for-java-agent)。 **使用佈建並行 – 佈建並行預先配置指定數量的函數執行個體來縮短冷啟動時間**，讓它們保持初始化並準備好立即處理請求。 AWS Lambda 此舉透過消除執行期間初始化函式環境的需求，有效縮短了冷啟動時間，確保更快速且更穩定的效能表現，尤其適用於對延遲敏感的工作負載。如需資訊，請參閱[設定函式的佈建並行](https://docs.aws.amazon.com/lambda/latest/dg/provisioned-concurrency.html)。 **使用 Lambda SnapStart 最佳化啟動效能** – AWS Lambda SnapStart 是一種功能，可在函數初始化階段後建立執行環境的預先初始化快照，以最佳化 Lambda 函數的啟動效能。然後，系統會重複使用此快照來啟動新的執行個體，藉由在函式調用期間略過初始化程序，大幅縮短冷啟動時間。如需詳細資訊，請參閱[使用 Lambda SnapStart 提升啟動效能](https://docs.aws.amazon.com/lambda/latest/dg/snapstart.html) ## 啟用 Application Signals 後，應用程式無法啟動。 如果在叢集上啟用 Application Signals 後，Amazon EKS 叢集上的應用程式並未啟動，請檢查下列事項： + 檢查應用程式是否已由另一個監控解決方案進行檢測。Application Signals 可能不支援與其他檢測解決方案共存。 + 確認您的應用程式符合使用 Application Signals 的相容性要求。如需詳細資訊，請參閱[支援的系統](CloudWatch-Application-Signals-supportmatrix.md)。 + 如果您的應用程式無法提取 Application Signals 成品，例如 AWS Distro for OpenTelemetery Java 或 Python 代理程式和 CloudWatch 代理程式映像，這可能是網路問題。 若要緩解此問題，請從應用程式部署資訊清單中移除註解 `instrumentation.opentelemetry.io/inject-java: "true"` 或 `instrumentation.opentelemetry.io/inject-python: "true"`，然後重新部署應用程式。然後檢查應用程式是否正常運作。 **已知問題** 已知 Java SDK v1.32.5 版本中的執行時期指標收集功能，無法與使用 JBoss Wildfly 的應用程式配合運作。此問題延伸到 Amazon CloudWatch Observability EKS 附加元件，影響版本 `2.3.0-eksbuild.1` 至 `2.5.0-eksbuild.1`。 如果您受到影響，請將環境變數 `OTEL_AWS_APPLICATION_SIGNALS_RUNTIME_ENABLED=false` 新增至您的應用程式，以降級版本或停用執行時期指標收集功能。 ## 啟用 Application Signals 後，Python 應用程式無法啟動 對於 OpenTelemetry 自動檢測，已知存在一個問題：如果 `PYTHONPATH` 環境變數缺失，有時會導致應用程式無法啟動。若要解決此問題，請確定將 `PYTHONPATH` 環境變數設定為應用程式的工作目錄位置。如需有關此問題的詳細資訊，請參閱 [Python autoinstrumentation setting of PYTHONPATH is not compliant with Python's module resolution behavior, breaking Django applications](https://github.com/open-telemetry/opentelemetry-operator/issues/2302)。 對於 Django 應用程式，還需要進行額外的必要設定，相關說明詳見 [OpenTelemetry Python 文件](https://opentelemetry-python.readthedocs.io/en/latest/examples/django/README.html)。 + `--noreload` 旗標可用於防止自動重新載入。 + 將 `DJANGO_SETTINGS_MODULE` 環境變數設定為 Django 應用程式 `settings.py` 檔案的所在位置。如此可確保 OpenTelemetry 能夠正確存取並整合您的 Django 設定。 ## 使用 WSGI 伺服器的 Python 應用程式沒有 Application Signals 資料 如果使用的是 Gunicorn、uWSGI 等 WSGI 伺服器，必須進行額外調整，才能讓 ADOT Python 自動檢測功能正常運作。 **注意** 請先確定您使用的是最新版本的 ADOT Python 和 Amazon CloudWatch Observability EKS 附加元件，然後繼續。 **透過 WSGI 伺服器啟用 Application Signals 的額外步驟** 1. 在分叉的工作程序進程中匯入自動檢測。 對於 Gunicorn，使用 `post_fork` 勾點： ``` # gunicorn.conf.py def post_fork(server, worker): from opentelemetry.instrumentation.auto_instrumentation import sitecustomize ``` 對於 uWSGI，使用 `import` 指令。 ``` # uwsgi.ini [uwsgi] ; required for the instrumentation of worker processes enable-threads = true lazy-apps = true import = opentelemetry.instrumentation.auto_instrumentation.sitecustomize ``` 1. 啟用 ADOT Python 自動檢測設定，使其跳過主進程並轉交給工作程序處理，方法是將 `OTEL_AWS_PYTHON_DEFER_TO_WORKERS_ENABLED` 環境變數設定為 `true`。 ## 我的 Node.js 應用程式未經檢測或未產生 Application Signals 遙測 要為 Node.js 啟用 Application Signals，必須確保您的 Node.js 應用程式採用 CommonJS (CJS) 模組格式。 AWS Distro for OpenTelemetry Node.js 不支援 ESM 模組格式，因為 OpenTelemetry JavaScript 對 ESM 的支援是實驗性的，並且是進行中的工作。 若要判斷您的應用程式是否使用 CJS 而非 ESM，請確定您的應用程式不符合[啟用 ESM 的條件](https://nodejs.org/api/esm.html#enabling)。 ## 我的 .NET 應用程式未檢測或中斷 AWS SDK 呼叫 適用於 .NET 的 AWS Distro for Open Telemetry (ADOT) SDK 不支援適用於 .NET V4 的 AWS SDK。使用 AWS SDK .NET V3 取得完整的 Application Signals 支援。 ## Application Signals 儀表板中沒有應用程式資料 如果 Application Signals 儀表板中遺失指標或追蹤，則可能是如下原因。只有在上次更新後等待 Application Signals 收集並顯示資料 15 分鐘後，才會調查這些原因。 + 請確定您使用的程式庫和架構受到 ADOT Java 代理程式的支援。如需詳細資訊，請參閱[程式庫/框架](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md#libraries--frameworks)。 + 確認 CloudWatch 代理程式正在執行中。首先檢查 CloudWatch 代理程式 Pod 的狀態，並確定它們都處於 `Running` 狀態。 ``` kubectl -n amazon-cloudwatch get pods. ``` 將下列內容新增至 CloudWatch 代理程式組態檔案以啟用偵錯日誌，然後重新啟動代理程式。 ``` "agent": { "region": "${REGION}", "debug": true }, ``` 然後檢查 CloudWatch 代理程式 Pod 中是否有錯誤。 + 檢查 CloudWatch 代理程式的組態問題。確認下列內容仍在 CloudWatch 代理程式組態檔案中，且新增代理程式後已重新啟動。 ``` "agent": { "region": "${REGION}", "debug": true }, ``` 然後檢查 OpenTelemetry 偵錯日誌中的錯誤訊息，例如 `ERROR io.opentelemetry.exporter.internal.grpc.OkHttpGrpcExporter - Failed to export ...`。這些訊息可能表示有問題。 如果不能解決問題，請透過使用 `kubectl describe pod` 命令描述 pod，轉儲並檢查名稱以 `OTEL_` 開頭的環境變數。 + 若要啟用 OpenTelemetry Python 偵錯記錄，請將環境變數 `OTEL_PYTHON_LOG_LEVEL` 設定為 `debug`，然後重新部署應用程式。 + 檢查從 CloudWatch 代理程式匯出資料的許可是否錯誤或不足。如果在 CloudWatch 代理程式日誌中看到 `Access Denied` 訊息，這可能是問題所在。這可能是因為安裝 CloudWatch 代理程式時套用的許可稍後被變更或撤銷。 + 產生遙測資料時，請檢查 AWS Distro for OpenTelemetry (ADOT) 問題。 請確定檢測註解 `instrumentation.opentelemetry.io/inject-java` 和 ` sidecar.opentelemetry.io/inject-java` 套用至應用程式部署，且值為 `true`。如果沒有這些註解，即使 ADOT 附加元件已正確安裝，也不會檢測應用程式 Pod。 接下來，檢查 `init` 容器是否已套用於應用程式，並且 `Ready` 狀態為 `True`。如果 `init` 容器尚未就緒，請參閱原因狀態。 如果問題仍然存在，請透過將環境變數設定為 `OTEL_JAVAAGENT_DEBUG` 並重新部署應用程式，在 OpenTelemetry Java SDK 上啟用偵錯記錄。然後尋找以 `ERROR io.telemetry` 開頭的訊息。 + 指標/範圍匯出程式可能正在捨棄資料。要找出答案，請檢查應用程式日誌中包含 `Failed to export...` 的訊息 + 將指標或範圍傳送至 Application Signals 時，CloudWatch 代理程式可能會受到限制。檢查 CloudWatch 代理程式日誌中是否有指示限流的訊息。 + 請確保您已啟用服務探索設定。只需要在區域中執行一次此操作。 若要確認，請在 CloudWatch 主控台中選擇 **Application Signals**，然後選擇**服務**。如果步驟 1 未標記為**完成**，選擇**開始探索您的服務**。資料應該會在五分鐘內開始流入。 ## 服務指標或相依項指標具有未知的值 若在 Application Signals 儀表板中，發現相依項名稱或操作為 **UnknownService**、**UnknownOperation**、**UnknownRemoteService** 或 **UnknownRemoteOperation**，請檢查未知遠端服務和未知遠端操作的資料點的出現是否與其部署一致。 + **UnknownService** 表示被檢測應用程式的名稱未知。如果 `OTEL_SERVICE_NAME` 環境變數未定義且未在 `OTEL_RESOURCE_ATTRIBUTES` 中指定 `service.name`，則服務名稱會設為 `UnknownService`。若要修正此問題，請在 `OTEL_SERVICE_NAME` 或 `OTEL_RESOURCE_ATTRIBUTES` 中指定服務名稱。 + **UnknownOperation** 表示被調用操作的名稱未知。當 Application Signals 無法偵測到調用遠端呼叫的操作名稱，或擷取的操作名稱包含高基數值時，就會出現這種情況。 + **UnknownRemoteService** 表示目的地服務的名稱未知。當系統無法擷取遠端呼叫存取的目的地服務名稱時，就會出現這種情況。 一個解決方案是在傳送請求的函式周圍建立自訂範圍，並新增具有指定值的 `aws.remote.service` 屬性。另一個選項是設定 CloudWatch 代理程式來自訂 `RemoteService` 的指標值。如需有關 CloudWatch 代理程式自訂功能的詳細資訊，請參閱 [啟用 CloudWatch Application Signals](CloudWatch-Agent-Application_Signals.md)。 + **UnknownRemoteOperation** 表示目的地操作的名稱未知。當系統無法擷取遠端呼叫存取的目的地操作名稱時，就會出現這種情況。 一個解決方案是在傳送請求的函式周圍建立自訂範圍，並新增具有指定值的 `aws.remote.operation` 屬性。另一個選項是設定 CloudWatch 代理程式來自訂 `RemoteOperation` 的指標值。如需有關 CloudWatch 代理程式自訂功能的詳細資訊，請參閱 [啟用 CloudWatch Application Signals](CloudWatch-Agent-Application_Signals.md)。 ## 管理 Amazon CloudWatch Observability EKS 附加元件時處理 ConfigurationConflict 當您安裝或更新 Amazon CloudWatch Observability EKS 附加元件時，如果您注意到 `ConfigurationConflict` 類型的 `Health Issue` 導致的失敗，且其說明以 `Conflicts found when trying to apply. Will not continue due to resolve conflicts mode` 開頭，則很可能是因為您已經在叢集上安裝 CloudWatch 代理程式及其關聯元件，例如 ServiceAccount、ClusterRole 和 ClusterRoleBinding。當附加元件嘗試安裝 CloudWatch 代理程式及其相關元件時，如果偵測到內容有任何變更，則預設情況下，安裝或更新會失敗，以避免覆寫叢集上資源的狀態。 如果您嘗試上載 Amazon CloudWatch Observability EKS 附加元件，但發現此失敗，建議刪除先前安裝在叢集上的現有 CloudWatch 代理程式設定，然後再安裝 EKS 附加元件。請務必備份您對原始 CloudWatch 代理程式設定所做的任何自訂設定 (例如自訂代理程式組態)，並在下次安裝或更新附加元件時將這些自訂設定提供給 Amazon CloudWatch Observability EKS 附加元件。如果之前已安裝 CloudWatch 代理程式以登入 Container Insights，請參閱 [刪除 Container Insights 的 CloudWatch 代理程式和 Fluent Bit](ContainerInsights-delete-agent.md) 以取得詳細資訊。 或者，附加元件也支援衝突解決組態選項，該選項可指定 `OVERWRITE`。您可以使用此選項覆寫叢集上的衝突來繼續安裝或更新附加元件。如果您使用 Amazon EKS 主控台，則在建立或更新附加元件時選擇**可選組態設定**，可找到**衝突解決方法**。如果您使用的是 AWS CLI，您可以將 `--resolve-conflicts OVERWRITE` 提供給命令，以建立或更新附加元件。 ## 我想要篩選掉不必要的指標和追蹤 如果 Application Signals 在收集您不想要的追蹤和指標，請參閱 [管理高基數操作](Application-Signals-Cardinality.md) 以了解如何透過自訂規則設定 CloudWatch 代理程式，從而降低基數。 如需有關自訂追蹤取樣規則的資訊，請參閱 X-Ray 文件中的[設定取樣規則](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console)。 ## `InternalOperation` 是什麼意思？ `InternalOperation` 是應用程式內部 (而非外部調用) 觸發的操作。看到 `InternalOperation` 是預期中的正常行為。 您會看到 `InternalOperation` 的典型範例包括： + **啟動時預先載入**：您的應用程式執行名為 `loadDatafromDB` 的操作，該操作會在預熱階段從資料庫讀取中繼資料。系統不會將 `loadDatafromDB` 視為服務操作，而是將其歸類為 `InternalOperation`。 + **在背景中非同步執行**：您的應用程式會訂閱事件佇列，並在每次更新時據此處理串流資料。每個觸發的操作都將作為服務操作在 `InternalOperation` 下執行。 + **從服務登錄檔擷取主機資訊**：您的應用程式會與服務登錄檔通訊以進行服務探索。與探索系統的所有互動都被歸類為 `InternalOperation`。 ## 如何啟用 .NET 應用程式記錄？ 若要啟用 .NET 應用程式記錄，請設定下列環境變數。如需如何設定這些環境變數的詳細資訊，請參閱 OpenTelemetry 文件中的[對 .NET 自動檢測問題進行疑難排解](https://opentelemetry.io/docs/zero-code/net/troubleshooting/#general-steps)。 + `OTEL_LOG_LEVEL` + `OTEL_DOTNET_AUTO_LOG_DIRECTORY` + `COREHOST_TRACE` + `COREHOST_TRACEFILE` ## 如何解決 .NET 應用程式中的組件版本衝突問題？ 如果您收到下列錯誤，請參閱 OpenTelemetry 文件中的[組件版本衝突](https://opentelemetry.io/docs/zero-code/net/troubleshooting/#assembly-version-conflicts)。 ``` Unhandled exception. System.IO.FileNotFoundException: Could not load file or assembly 'Microsoft.Extensions.DependencyInjection.Abstractions, Version=7.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60'. The system cannot find the file specified. File name: 'Microsoft.Extensions.DependencyInjection.Abstractions, Version=7.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60' at Microsoft.AspNetCore.Builder.WebApplicationBuilder..ctor(WebApplicationOptions options, Action`1 configureDefaults) at Microsoft.AspNetCore.Builder.WebApplication.CreateBuilder(String[] args) at Program.
$(String[] args) in /Blog.Core/Blog.Core.Api/Program.cs:line 26 ``` ## 可以停用 FluentBit 嗎？ 可以透過設定 Amazon CloudWatch Observability EKS 附加元件來停用 FluentBit。如需詳細資訊，請參閱[(選用) 額外組態](install-CloudWatch-Observability-EKS-addon.md#install-CloudWatch-Observability-EKS-addon-configuration)。 ## 可以先篩選容器日誌，再匯出至 CloudWatch Logs 嗎？ 不可以，暫時不支援篩選容器日誌。 ## 解決使用 AWS Distro for OpenTelemetry (ADOT) JavaScript Lambda Layer 時的 TypeError 以下情況下 Lambda 函式可能會因為此錯誤而失敗：`TypeError - "Cannot redefine property: handler"` + 使用 ADOT JavaScript Lambda Layer + 使用 `esbuild` 編譯 TypeScript + 使用 `export` 關鍵字匯出您的處理常式 ADOT JavaScript Lambda Layer 需要在執行時期修改您的處理常式。當您搭配 `esbuild`（直接或透過 AWS CDK) 使用 `export`關鍵字時， `esbuild`會讓您的處理常式不可變，防止這些修改。 使用 `module.exports` (而非 `export` 關鍵字) 匯出您的處理常式函式： ``` // Before export const handler = (event) => { // Handler Code } ``` ``` // After const handler = async (event) => { // Handler Code } module.exports = { handler } ``` ## 搭配 AWS Distro for OpenTelemetry (ADOT) JavaScript Lambda Layer 使用 Response Streaming Lambda 處理常式時的 TypeError 以下情況下 Lambda 函式可能會因為此錯誤而失敗：`TypeError - "responseStream.write is not a function"` + 使用已啟用 Lambda 檢測的 ADOT JavaScript AWS Lambda Layer （預設為啟用） + 在 Node.js 受管執行時間中使用回應串流功能。例如，當您的函數處理常式如下： ``` * export const handler = awslambda.streamifyResponse(...) ``` ADOT JavaScript AWS Lambda Layer 中的 Lambda 檢測目前不支援 Node.js 受管執行期中的回應串流，因此必須停用以避免此 TypeError。 ## 更新必要版本的代理程式或 Amazon EKS 附加元件 2024 年 8 月 9 日之後，CloudWatch Application Signals 將不再支援舊版的 Amazon CloudWatch 可觀測性 EKS 附加元件、CloudWatch 代理程式和 AWS Distro for OpenTelemetry 自動檢測代理程式。 + 對於 Amazon CloudWatch Observability EKS 附加元件，系統不支援 `v1.7.0-eksbuild.1` 之前的版本。 + 對於 CloudWatch 代理程式，不支援 `1.300040.0` 之前的版本。 + 對於 AWS Distro for OpenTelemetry 自動檢測代理程式： + 對於 Java，不支援 `1.32.2` 之前的版本。 + 對於 Python，不支援 `0.2.0` 之前的版本。 + 對於 .NET，不支援 `1.3.2` 之前的版本。 + 對於 Node.js，不支援 `0.3.0` 之前的版本。 **重要** 最新版本的代理程式包含對 Application Signals 指標結構描述的更新。這些更新不具向後相容性，若使用不相容的版本，可能導致資料問題。要協助確保無縫轉換至新功能，請執行下列動作： 如果您的應用程式在 Amazon EKS 上執行，請務必在更新 Amazon CloudWatch Observability 附加元件後，重新啟動所有經檢測的應用程式。 對於在其他平台上執行的應用程式，請務必**同時**將 CloudWatch 代理程式和 AWS OpenTelemetry 自動檢測代理程式升級至最新版本。 下列各節中的指示可協助您更新至受支援的版本。 **Contents** + [更新 Amazon CloudWatch Observability EKS 附加元件](#Application-Signals-Upgrade-Addon) + [使用主控台](#Upgrade-Addon-Console) + [使用 AWS CLI](#Upgrade-Addon-CLI) + [更新 CloudWatch 代理程式及 ADOT 代理程式](#Application-Signals-Upgrade-Agents) + [Amazon ECS 上的更新](#Upgrade-Agents-ECS) + [Amazon EC2 或其他架構上的更新](#Upgrade-Addon-EC2) ### 更新 Amazon CloudWatch Observability EKS 附加元件 對於 Amazon CloudWatch 可觀測性 EKS 附加元件，您可以使用 AWS 管理主控台 或 AWS CLI。 #### 使用主控台 **使用主控台升級附加元件** 1. 在以下網址開啟 Amazon EKS 主控台：[https://console.aws.amazon.com/eks/home\$1/clusters](https://console.aws.amazon.com/eks/home#/clusters)。 1. 選擇要更新之 Amazon EKS 叢集的名稱。 1. 選擇**附加元件**索引標籤，然後選擇 **Amazon CloudWatch Observability**。 1. 選擇**編輯**、選取要更新的版本，然後選擇**儲存變更**。 請務必選擇 `v1.7.0-eksbuild.1` 或更高版本。 1. 輸入下列其中一個 AWS CLI 命令以重新啟動您的 服務。 ``` # Restart a deployment kubectl rollout restart deployment/name # Restart a daemonset kubectl rollout restart daemonset/name # Restart a statefulset kubectl rollout restart statefulset/name ``` #### 使用 AWS CLI **使用 升級附加元件 AWS CLI** 1. 輸入下列命令尋找最新版本。 ``` aws eks describe-addon-versions \ --addon-name amazon-cloudwatch-observability ``` 1. 輸入下列命令安裝附加元件。將 *\$1VERSION* 替換為 `v1.7.0-eksbuild.1` 或更高版本。將 *\$1AWS\$1REGION* 和 *\$1CLUSTER* 替換為您的區域和叢集名稱。 ``` aws eks update-addon \ --region $AWS_REGION \ --cluster-name $CLUSTER \ --addon-name amazon-cloudwatch-observability \ --addon-version $VERSION \ # required only if the advanced configuration is used. --configuration-values $JSON_CONFIG ``` **注意** 如果使用的是附加元件的自訂組態，可以在 [啟用 CloudWatch Application Signals](CloudWatch-Agent-Application_Signals.md) 中找到用於 *\$1JSON\$1CONFIG* 的組態範例。 1. 輸入下列其中一個 AWS CLI 命令以重新啟動您的 服務。 ``` # Restart a deployment kubectl rollout restart deployment/name # Restart a daemonset kubectl rollout restart daemonset/name # Restart a statefulset kubectl rollout restart statefulset/name ``` ### 更新 CloudWatch 代理程式及 ADOT 代理程式 如果您的服務在 Amazon EKS 以外的架構上執行，則必須升級 CloudWatch 代理程式和 ADOT 自動檢測代理程式，才能使用最新的 Application Signals 功能。 #### Amazon ECS 上的更新 **為在 Amazon ECS 上執行之服務升級代理程式** 1. 建立新的任務定義修訂版本。如需詳細資訊，請參閱[使用主控台更新任務定義](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/update-task-definition-console-v2)。 1. 將 `ecs-cwagent` 容器的 `$IMAGE` 替換為 Amazon ECR 中 [cloudwatch-agent](https://gallery.ecr.aws/cloudwatch-agent/cloudwatch-agent) 的最新映像標籤。 如果升級至固定版本，請務必使用 `1.300040.0` 或之後的版本。 1. 將 `init` 容器 的 `$IMAGE` 替換為來自下列位置的最新映像標籤： + 對於 Java，請使用 [aws-observability/adot-autoinstrumentation-java](https://gallery.ecr.aws/aws-observability/adot-autoinstrumentation-java)。 如果升級至固定版本，請務必使用 `1.32.2` 或之後的版本。 + 對於 Python，請使用 [aws-observability/adot-autoinstrumentation-python](https://gallery.ecr.aws/aws-observability/adot-autoinstrumentation-python)。 如果升級至固定版本，請務必使用 `0.2.0` 或之後的版本。 + 對於 .NET，請使用 [aws-observability/adot-autoinstrumentation-dotnet](https://gallery.ecr.aws/aws-observability/adot-autoinstrumentation-dotnet)。 如果升級至固定版本，請務必使用 `1.3.2` 或之後的版本。 + 對於 Node.js，請使用 [aws-observability/adot-autoinstrumentation-node](https://gallery.ecr.aws/aws-observability/adot-autoinstrumentation-node)。 如果升級至固定版本，請務必使用 `0.3.0` 或之後的版本。 1. 遵循 [步驟 4：使用 CloudWatch 代理程式檢測您的應用程式](CloudWatch-Application-Signals-ECS-Sidecar.md#CloudWatch-Application-Signals-Enable-ECS-Instrument) 中的指示，更新應用程式容器中的 Application Signals 環境變數。 1. 使用新的任務定義部署服務。 #### Amazon EC2 或其他架構上的更新 **為在 Amazon EC2 或其他架構上執行之服務升級代理程式** 1. 請務必選取 CloudWatch 代理程式的 `1.300040.0` 或更高版本。 1. 從下列其中一個位置下載最新版本的 AWS Distro for OpenTelemetry 自動檢測代理程式： + 對於 Java，請使用 [aws-otel-java-instrumentation](https://gallery.ecr.aws/aws-observability/adot-autoinstrumentation-java)。 如果升級至固定版本，請務必選擇 `1.32.2` 或之後的版本。 + 對於 Python，請使用 [aws-otel-python-instrumentation ](https://github.com/aws-observability/aws-otel-python-instrumentation/releases)。 如果升級至固定版本，請務必選擇 `0.2.0` 或之後的版本。 + 對於 .NET，請使用 [aws-otel-dotnet-instrumentation](https://github.com/aws-observability/aws-otel-dotnet-instrumentation/releases)。 如果升級至固定版本，請務必選擇 `1.3.2` 或之後的版本。 + 對於 Node.js，請使用 [aws-otel-js-instrumentation](https://github.com/aws-observability/aws-otel-js-instrumentation/releases)。 如果升級至固定版本，請務必選擇 `0.3.0` 或之後的版本。 1. 將更新的 Application Signals 環境變數套用至您的應用程式，然後啟動應用程式。如需詳細資訊，請參閱[步驟 3：檢測您的應用程式並啟動它](CloudWatch-Application-Signals-Enable-EC2Main.md#CloudWatch-Application-Signals-Enable-Other-instrument)。 ## Application Signals 已停用內嵌指標格式 (EMF) 停用 `/aws/application-signals/data` 日誌群組的 EMF 可能對 Application Signals 功能產生以下影響。 + Application Signals 指標和圖表不會顯示 + Application Signals 功能將降級 **如何還原 Application Signals？** 當 Application Signals 顯示空白圖表或指標時，必須啟用 `/aws/application-signals/data` 日誌群組的 EMF，以還原完整功能。如需詳細資訊，請參閱 [PutAccountPolicy](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutAccountPolicy.html#API_PutAccountPolicy_RequestSyntax)。