疑難排解 Application Signals 安裝 - Amazon CloudWatch
Application Signals Java 層冷啟動效能啟用 Application Signals 後，應用程式無法啟動。啟用 Application Signals 後，Python 應用程式不會啟動沒有使用 WSGI 伺服器的 Python 應用程式 Application Signals 資料我的 Node.js 應用程式未經過檢測或未產生 Application Signals 遙測Application Signals 儀表板中沒有應用程式資料服務指標或相依性指標具有未知值管理 Amazon CloudWatch Observability EKS 附加元件時處理 ConfigurationConflict我想要篩選掉不必要的指標和追蹤什麼是 InternalOperation ？如何啟用 .NET 應用程式的記錄？如何解決 .NET 應用程式中的組件版本衝突？我可以停用 FluentBit 嗎？在匯出至 CloudWatch Logs 之前，我可以篩選容器日誌嗎？ 解決使用 AWS Distro for OpenTelemetry (ADOT) JavaScript Lambda Layer 時的 TypeError 更新必要版本的代理程式或 Amazon EKS 附加元件

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

疑難排解 Application Signals 安裝

本節包含 CloudWatch Application Signals 的疑難排解秘訣。

Application Signals Java 層冷啟動效能

將 Application Signals Layer 新增至 Java Lambda 函數會增加啟動延遲 （冷啟動時間）。下列秘訣有助於減少時間敏感函數的延遲。

Java 代理程式的快速啟動 – Application Signals Java Lambda Layer 包含快速啟動功能，預設為關閉，但可以透過將 OTEL_JAVA_AGENT_FAST_STARTUP_ENABLED 變數設定為 true 來啟用。啟用時，此功能會將 JVM 設定為使用分層編譯層級 1 C1 編譯器來產生快速最佳化的原生程式碼，以加快冷啟動速度。C1 編譯器以長期最佳化的成本優先考慮速度，而 C2 編譯器透過分析一段時間內的資料來提供卓越的整體效能。

如需詳細資訊，請參閱 Java 代理程式的快速啟動。

使用佈建並行 - 佈建並行預先配置指定數量的函數執行個體來縮短冷啟動時間，讓它們保持初始化並準備好立即處理請求。 AWS Lambda 這可減少冷啟動時間，無需在執行期間初始化函數環境，確保更快速且更一致的效能，特別是對於延遲敏感的工作負載。如需詳細資訊，請參閱為函數 設定佈建並行。

使用 Lambda SnapStart 最佳化啟動效能 – AWS Lambda SnapStart 是一種功能，可在函數初始化階段後建立執行環境的預先初始化快照，以最佳化 Lambda 函數的啟動效能。然後重複使用此快照來啟動新的執行個體，藉由在函數調用期間略過初始化程序，大幅縮短冷啟動時間。如需詳細資訊，請參閱使用 Lambda SnapStart 改善啟動效能

啟用 Application Signals 後，應用程式無法啟動。

如果在叢集上啟用 Application Signals 後，Amazon EKS 叢集上的應用程式並未啟動，請檢查下列事項：

  • 檢查應用程式是否已由另一個監控解決方案進行檢測。Application Signals 可能不支援與其他檢測解決方案共同存在。

  • 確認您的應用程式符合使用 Application Signals 的相容性要求。如需詳細資訊，請參閱支援的系統。

  • 如果您的應用程式無法提取 Application Signals 成品，例如 AWS Distro for OpenTelemetery Java 或 Python 代理程式和 CloudWatch 代理程式映像，這可能是網路問題。

若要緩解此問題，請從instrumentation.opentelemetry.io/inject-python: "true"應用程式部署資訊清單中移除 註釋instrumentation.opentelemetry.io/inject-java: "true"或 ，然後重新部署您的應用程式。然後檢查應用程式是否正常運作。

已知問題

Java SDK 1.32.5 版中的執行時間指標集合已知無法使用 JBoss Wildfly 的應用程式。此問題延伸到 Amazon CloudWatch 可觀測性 EKS 附加元件，2.3.0-eksbuild.1透過 影響版本2.5.0-eksbuild.1。

如果您受到影響，請將環境變數新增至OTEL_AWS_APPLICATION_SIGNALS_RUNTIME_ENABLED=false應用程式，以降級版本或停用執行時間指標集合。

啟用 Application Signals 後，Python 應用程式不會啟動

缺少PYTHONPATH環境變數有時會導致應用程式無法啟動 ，這是 OpenTelemetry 自動檢測的已知問題。若要解決此問題，請確定您將PYTHONPATH環境變數設定為應用程式工作目錄的位置。如需此問題的詳細資訊，請參閱 PYTHONPATH 的 Python 自動檢測設定不符合 Python 的模組解析度行為，進而破壞 Django 應用程式。

對於 Django 應用程式，還有其他必要的組態，如 OpenTelemetry Python 文件所述。

  • 使用 --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

  2. 啟用 ADOT Python 自動檢測的組態，透過將OTEL_AWS_PYTHON_DEFER_TO_WORKERS_ENABLED環境變數設定為 來略過主要程序並延遲至工作者true。

我的 Node.js 應用程式未經過檢測或未產生 Application Signals 遙測

若要啟用 Node.js 的 Application Signals，您必須確保您的 Node.js 應用程式使用 CommonJS (CJS) 模組格式。目前， AWS Ditro for OpenTelemetry Node.js 不支援 ESM 模組格式，因為 OpenTelemetry JavaScript 對 ESM 的支援是實驗性的，並且是進行中的工作。

若要判斷您的應用程式是否使用 CJS 而非 ESM，請確定您的應用程式不符合啟用 ESM 的條件。

Application Signals 儀表板中沒有應用程式資料

如果 Application Signals 儀表板中遺失指標或追蹤，則可能是如下原因。只有在上次更新後等待 Application Signals 收集並顯示資料 15 分鐘後，才會調查這些原因。

  • 請確定您使用的程式庫和架構受到 ADOT Java 代理程式的支援。如需詳細資訊，請參閱程式庫/框架。

  • 確認 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 true 並重新部署應用程式，在 OpenTelemetry Java SDK 上啟用偵錯記錄。然後尋找以 ERROR io.telemetry 開頭的訊息。

  • 指標/範圍匯出程式可能正在捨棄資料。要找出答案，請檢查應用程式日誌中包含 Failed to export... 的訊息

  • 將指標或範圍傳送至 Application Signals 時，CloudWatch 代理程式可能會受到限制。檢查 CloudWatch 代理程式日誌中是否有指示限流的訊息。

  • 請確定您已啟用服務探索設定。您只需要在區域中執行一次此操作。

    若要確認，請在 CloudWatch 主控台中選擇 Application Signals， Services。如果步驟 1 未標記為完成，請選擇開始探索您的服務。資料應該會在五分鐘內開始流入。

服務指標或相依性指標具有未知值

如果您在 Application Signals 儀表板中看到 UnknownService、 UnknownOperation、 UnknownRemoteService 或 UnknownRemoteOperation 的相依性名稱或操作，請檢查未知遠端服務和未知遠端操作的資料點是否與其部署一致。

  • UnknownService 表示檢測應用程式的名稱不明。如果OTEL_SERVICE_NAME環境變數未定義service.name且未在 中指定OTEL_RESOURCE_ATTRIBUTES，則服務名稱會設為 UnknownService。若要修正此問題，請在 OTEL_SERVICE_NAME或 中指定服務名稱OTEL_RESOURCE_ATTRIBUTES。

  • UnknownOperation 表示調用操作的名稱未知。當 Application Signals 無法探索叫用遠端呼叫的操作名稱，或擷取的操作名稱包含高基數值時，就會發生這種情況。

  • UnknownRemoteService 表示目的地服務的名稱未知。當系統無法擷取遠端呼叫存取的目的地服務名稱時，就會發生這種情況。

    其中一個解決方案是建立傳送請求的函數周圍的自訂跨度，並使用aws.remote.service指定的值新增 屬性。另一個選項是設定 CloudWatch 代理程式來自訂 的指標值RemoteService。如需 CloudWatch 代理程式中自訂的詳細資訊，請參閱 啟用 CloudWatch Application Signals。

  • UnknownRemoteOperation 表示目的地操作的名稱不明。當系統無法擷取遠端呼叫存取的目的地操作名稱時，就會發生這種情況。

    其中一個解決方案是在傳送請求的函數周圍建立自訂跨度，並使用aws.remote.operation指定的值新增 屬性。另一個選項是設定 CloudWatch 代理程式來自訂 的指標值RemoteOperation。如需 CloudWatch 代理程式中自訂的詳細資訊，請參閱 啟用 CloudWatch Application Signals。

管理 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，請參閱 刪除 CloudWatch 代理程式和 Fluent Bit for Container Insights 以取得詳細資訊。

或者，附加元件也支援衝突解決組態選項，該選項可指定 OVERWRITE。您可以使用此選項覆寫叢集上的衝突來繼續安裝或更新附加元件。如果您使用 Amazon EKS 主控台，則在建立或更新附加元件時選擇可選組態設定，可找到衝突解決方法。如果您使用的是 AWS CLI，您可以將 --resolve-conflicts OVERWRITE 提供給命令，以建立或更新附加元件。

我想要篩選掉不必要的指標和追蹤

如果 Application Signals 正在收集您不想要的追蹤和指標，請參閱 以取得有關使用自訂規則設定 CloudWatch 代理程式以降低基數管理高基數操作的資訊。

如需有關自訂追蹤取樣規則的資訊，請參閱 X-Ray 文件中的設定取樣規則。

什麼是 InternalOperation ？

InternalOperation 是由應用程式內部而非外部調用觸發的操作。InternalOperation 預期會看到正常運作的行為。

您會看到的一些典型範例InternalOperation包括下列項目：

  • 啟動時預先載入 – 您的應用程式會執行名為 的操作loadDatafromDB，在暖機階段期間從資料庫讀取中繼資料。您不會將其視為loadDatafromDB服務操作進行觀察，而是將其歸類為 InternalOperation。

  • 在背景中非同步執行 – 您的應用程式會訂閱事件佇列，並在有更新時相應地處理串流資料。每個觸發的操作都會以服務操作InternalOperation的形式在 下。

  • 從服務登錄檔擷取主機資訊 – 您的應用程式會與服務登錄檔通訊以探索服務。與探索系統的所有互動都會分類為 InternalOperation。

如何啟用 .NET 應用程式的記錄？

若要啟用 .NET 應用程式的記錄，請設定下列環境變數。如需如何設定這些環境變數的詳細資訊，請參閱 OpenTelemetry 文件中的疑難排解 .NET 自動檢測問題。

  • OTEL_LOG_LEVEL

  • OTEL_DOTNET_AUTO_LOG_DIRECTORY

  • COREHOST_TRACE

  • COREHOST_TRACEFILE

如何解決 .NET 應用程式中的組件版本衝突？

如果您收到下列錯誤，請參閱 OpenTelemetry 文件中的組件版本衝突以取得解決步驟。

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.<Main>$(String[] args) in /Blog.Core/Blog.Core.Api/Program.cs:line 26

我可以停用 FluentBit 嗎？

您可以透過設定 Amazon CloudWatch 可觀測性 EKS 附加元件來停用 FluentBit。如需詳細資訊，請參閱(選用) 額外組態。

在匯出至 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 }

更新必要版本的代理程式或 Amazon EKS 附加元件

2024 年 8 月 9 日之後，CloudWatch Application Signals 將不再支援舊版的 Amazon CloudWatch 可觀測性 EKS 附加元件、CloudWatch 代理程式和 AWS Distro for OpenTelemetry 自動檢測代理程式。

  • 對於 Amazon CloudWatch 可觀測性 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不支援早於 的版本。

    • 對於 Node0.3.0.js，不支援早於 的版本。

重要

最新版的代理程式包含 Application Signals 指標結構描述的更新。這些更新無法回溯相容，如果使用不相容的版本，這可能會導致資料問題。若要協助確保無縫轉換至新功能，請執行下列動作：

  • 如果您的應用程式在 Amazon EKS 上執行，請務必在更新 Amazon CloudWatch Observability 附加元件後重新啟動所有經檢測的應用程式。

  • 對於在其他平台上執行的應用程式，請務必將 CloudWatch 代理程式和 AWS OpenTelemetry 自動檢測代理程式升級至最新版本。

下列各節中的指示可協助您更新至支援的版本。

更新 Amazon CloudWatch 可觀測性 EKS 附加元件

對於 Amazon CloudWatch 可觀測性 EKS 附加元件，您可以使用 AWS Management Console 或 AWS CLI。

使用主控台

使用主控台升級附加元件

  1. 在以下網址開啟 Amazon EKS 主控台：https://console.aws.amazon.com/eks/home#/clusters。

  2. 選擇要更新的 Amazon EKS 叢集名稱。

  3. 選擇附加元件索引標籤，然後選擇 Amazon CloudWatch 可觀測性。

  4. 選擇編輯，選取要更新的版本，然後選擇儲存變更。

    請務必選擇 v1.7.0-eksbuild.1 或更新版本。

  5. 輸入下列其中一個 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

  2. 輸入下列命令以更新附加元件。將 $VERSION 取代為 v1.7.0-eksbuild.1或更新版本。將 $AWS_REGION 和 $CLUSTER 取代為您的區域和叢集名稱。

    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
    注意

    如果您使用 附加元件的自訂組態，您可以在 中找到用於 $JSON_CONFIG 的組態範例啟用 CloudWatch Application Signals。

  3. 輸入下列其中一個 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. 建立新的任務定義修訂。如需詳細資訊，請參閱使用主控台更新任務定義。

  2. 將ecs-cwagent容器$IMAGE的 取代為 Amazon ECR 上 cloudwatch-agent 的最新映像標籤。

    如果您升級至固定版本，請務必使用等於或晚於 的版本1.300040.0。

  3. 將init容器$IMAGE的 取代為來自下列位置的最新映像標籤：

  4. 遵循 中的指示，更新應用程式容器中的 Application Signals 環境變數步驟 4：使用 CloudWatch 代理程式檢測您的應用程式。

  5. 使用新的任務定義部署您的服務。

Amazon EC2 或其他架構的更新

升級在 Amazon EC2 或其他架構上執行之服務的代理程式

  1. 遵循 中的指示，並將 CloudWatch 代理程式下載 CloudWatch 代理程式套件升級至最新版本。請務必選取版本 1.300040.0 或更新版本。

  2. 從下列其中一個位置下載最新版本的 AWS Distro for OpenTelemetry 自動檢測代理程式：

  3. 將更新的 Application Signals 環境變數套用至您的應用程式，然後啟動您的應用程式。如需詳細資訊，請參閱步驟 3：檢測您的應用程式並啟動它。