疑難排解 Application Signals 安裝
本節包含 CloudWatch Application Signals 的疑難排解秘訣。
主題
Application Signals Java Layer 冷啟動效能
將 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-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
對於 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 的額外步驟
在分叉的工作程序進程中匯入自動檢測。
對於 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啟用 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 的條件
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並重新部署應用程式,在 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。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,請參閱 刪除 Container Insights 的 CloudWatch 代理程式和 Fluent Bit 以取得詳細資訊。
或者,附加元件也支援衝突解決組態選項,該選項可指定 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_LEVELOTEL_DOTNET_AUTO_LOG_DIRECTORYCOREHOST_TRACECOREHOST_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 Observability 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 Observability 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 自動檢測代理程式升級至最新版本。
下列各節中的指示可協助您更新至受支援的版本。
內容
更新 Amazon CloudWatch Observability EKS 附加元件
對於 Amazon CloudWatch Observability EKS 附加元件,可以使用 AWS 管理主控台 或 AWS CLI。
使用主控台
使用主控台升級附加元件
在以下網址開啟 Amazon EKS 主控台:https://console.aws.amazon.com/eks/home#/clusters
。 選擇要更新之 Amazon EKS 叢集的名稱。
選擇附加元件索引標籤,然後選擇 Amazon CloudWatch Observability。
選擇編輯、選取要更新的版本,然後選擇儲存變更。
請務必選擇
v1.7.0-eksbuild.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 升級附加元件
輸入下列命令尋找最新版本。
aws eks describe-addon-versions \ --addon-name amazon-cloudwatch-observability輸入下列命令安裝附加元件。將
$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注意
如果使用的是附加元件的自訂組態,可以在 啟用 CloudWatch Application Signals 中找到用於
$JSON_CONFIG的組態範例。輸入以下 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 上執行之服務升級代理程式
建立新的任務定義修訂版本。如需詳細資訊,請參閱使用主控台更新任務定義。
將
ecs-cwagent容器的$IMAGE替換為 Amazon ECR 中 cloudwatch-agent的最新映像標籤。 如果升級至固定版本,請務必使用
1.300040.0或之後的版本。將
init容器 的$IMAGE替換為來自下列位置的最新映像標籤:對於 Java,請使用 aws-observability/adot-autoinstrumentation-java
。 如果升級至固定版本,請務必使用
1.32.2或之後的版本。對於 Python,請使用 aws-observability/adot-autoinstrumentation-python
。 如果升級至固定版本,請務必使用
0.2.0或之後的版本。-
對於 .NET,請使用 aws-observability/adot-autoinstrumentation-dotnet
。 如果升級至固定版本,請務必使用
1.3.2或之後的版本。 -
對於 Node.js,請使用 aws-observability/adot-autoinstrumentation-node
。 如果升級至固定版本,請務必使用
0.3.0或之後的版本。
遵循 步驟 4:使用 CloudWatch 代理程式檢測您的應用程式 中的指示,更新應用程式容器中的 Application Signals 環境變數。
使用新的任務定義部署服務。
Amazon EC2 或其他架構上的更新
為在 Amazon EC2 或其他架構上執行之服務升級代理程式
請務必選取 CloudWatch 代理程式的
1.300040.0或更高版本。從以下任一位置下載最新版本的 AWS Distro for OpenTelemetry Java 自動檢測代理程式:
對於 Java,請使用 aws-otel-java-instrumentation
。 如果升級至固定版本,請務必選擇
1.32.2或之後的版本。對於 Python,請使用 aws-otel-python-instrumentation
。 如果升級至固定版本,請務必選擇
0.2.0或之後的版本。-
對於 .NET,請使用 aws-otel-dotnet-instrumentation
。 如果升級至固定版本,請務必選擇
1.3.2或之後的版本。 -
對於 Node.js,請使用 aws-otel-js-instrumentation
。 如果升級至固定版本,請務必選擇
0.3.0或之後的版本。
將更新的 Application Signals 環境變數套用至您的應用程式,然後啟動應用程式。如需更多詳細資訊,請參閱 步驟 3:檢測您的應用程式並啟動它。
Application Signals 已停用內嵌指標格式 (EMF)
停用 /aws/application-signals/data 日誌群組的 EMF 可能對 Application Signals 功能產生以下影響。
Application Signals 指標和圖表不會顯示
Application Signals 功能將降級
如何還原 Application Signals?
當 Application Signals 顯示空白圖表或指標時,必須啟用 /aws/application-signals/data 日誌群組的 EMF,以還原完整功能。如需詳細資訊,請參閱 PutAccountPolicy。