aws-observability
熱門建置、設定、偵錯並最佳化 AWS 可觀測性（Observability），支援 CloudWatch（Log Insights、Metrics、Alarms、Dashboards、EMF）、X-Ray、CloudTrail 及 ADOT（AWS Distro for OpenTelemetry），並能透過 ADOT 自動埋點（Auto-instrumentation）SDK 為服務啟用並導入 Application Signals。涵蓋 Log Insights 查詢、告警（指標告警、複合告警、異常檢測告警）、儀表板、自訂指標/EMF、X-Ray 追蹤與採樣、ADOT Collector 設定、CloudTrail 稽核，以及經由 ADOT SDK 實現的端到端 Application Signals 啟用（包含 CloudWatch Observability EKS Add-on、CloudWatch Agent IAM、OTLP 端點、ServiceEvents、動態埋點 Dynamic Instrumentation）。支援動態埋點中的中斷點與快照功能，可在運作中的服務中擷取即時資料，無需重新部署即可完成偵錯。適用於 CloudWatch、告警、儀表板、EMF、X-Ray、Traces、CloudTrail、ADOT、監控、Synthetics/Canaries，或為服務啟用/導入/埋點 Application Signals 的情境。不適用於一般應用程式日誌記錄或安全性威脅偵測。
建置、設定、偵錯並最佳化 AWS 可觀測性（Observability），支援 CloudWatch（Log Insights、Metrics、Alarms、Dashboards、EMF）、X-Ray、CloudTrail 及 ADOT（AWS Distro for OpenTelemetry），並能透過 ADOT 自動埋點（Auto-instrumentation）SDK 為服務啟用並導入 Application Signals。涵蓋 Log Insights 查詢、告警（指標告警、複合告警、異常檢測告警）、儀表板、自訂指標/EMF、X-Ray 追蹤與採樣、ADOT Collector 設定、CloudTrail 稽核，以及經由 ADOT SDK 實現的端到端 Application Signals 啟用（包含 CloudWatch Observability EKS Add-on、CloudWatch Agent IAM、OTLP 端點、ServiceEvents、動態埋點 Dynamic Instrumentation）。支援動態埋點中的中斷點與快照功能，可在運作中的服務中擷取即時資料，無需重新部署即可完成偵錯。適用於 CloudWatch、告警、儀表板、EMF、X-Ray、Traces、CloudTrail、ADOT、監控、Synthetics/Canaries，或為服務啟用/導入/埋點 Application Signals 的情境。不適用於一般應用程式日誌記錄或安全性威脅偵測。
AWS Observability
Overview
涵蓋指標 (Metrics)、日誌 (Logs) 與追蹤 (Traces) 的 AWS 可觀測性專業知識，涵蓋完整生命週期：透過 ADOT (AWS Distro for OpenTelemetry) 自動埋點 SDK 與 ServiceEvents 為服務啟用/導入 Application Signals——讓服務能在 EC2、ECS、EKS 及 Lambda 上（支援 Python、Node.js、Java 與 .NET）顯示於 Application Signals 中。
最適合搭配 AWS MCP 伺服器 使用——可直接執行 CLI 命令、查詢 CloudWatch 並驗證設定。所有指引亦適用於標準 AWS CLI 存取方式。
注意： 參考檔案中包含特定的執行階段版本、配額數值與功能支援表，這些內容可能會有所變更。當需要精準資訊時（例如部署至正式環境、選擇執行階段或檢查配額），請務必對照最新 AWS 官方文件確認，而非完全依賴本檔案中的數值。
Routing
| 使用者需求 | 建議動作 |
|---|---|
| 為服務啟用/導入 Application Signals（自動埋點） | 閱讀 application-signals-onboarding.md |
| 透過 CI/CD 傳遞 ServiceEvents git/部署元資料 | 閱讀 application-signals-cicd-metadata.md |
| 各平台/各語言的具體啟用步驟 | 閱讀對應的 references/appsignals-guides/<platform>-<language>.md（例如 eks-python.md） |
| 撰寫 Log Insights 查詢指令 | 閱讀 log-insights.md |
| 設定告警（指標告警、複合告警、異常檢測告警） | 閱讀 alarms.md |
| 發布自訂指標或使用 EMF | 閱讀 metrics.md |
| 設定 X-Ray 追蹤或 ADOT | 閱讀 tracing.md |
| 建置儀表板 | 閱讀 dashboards.md |
| 排除可觀測性相關疑難雜症 | 閱讀 troubleshooting.md —— 從 5 個最常見的修復方案開始 |
| 偵錯 Canary 測試失敗問題 | 閱讀 synthetics.md —— 參閱常見失敗對照表 |
| CloudTrail 營運稽核 | 閱讀 cloudtrail.md |
| 使用 CDK 設定 Lambda 監控 | 使用 alarm-template.ts 作為起始範本 |
| 建立 Synthetic Canaries 撥測 | 閱讀 synthetics.md |
| 設定 ADOT Collector | 使用 otel-config.yaml 作為起始範本 |
| 利用中斷點/快照偵錯運作中的服務 —— 動態埋點 Dynamic Instrumentation（會修改線上服務並擷取即時資料） | 在採取任何行動前，請先完整閱讀 dynamic-instrumentation.md。在執行任何建立/刪除操作前須向使用者確認，並在執行重大操作前進行口述說明：觀察 → 假設 → 提議動作 → 預期結果。從原始碼/程式碼檢視中診斷運作中服務的根本原因。僅憑程式碼檢視只能提出假設，無法確認根本原因。在取得執行階段證據證實之前，請將疑似原因視為待驗證假設。 |
| 涵蓋多個領域 | 先閱讀最具針對性的參考檔案，再依需求查閱其他檔案 |
Files
| 檔案 | 內容說明 |
|---|---|
| application-signals-onboarding.md | 啟用 Application Signals 自動埋點：EKS Add-on、CloudWatch Agent IAM、OTLP 端點、ServiceEvents 環境變數、動態埋點 —— 按平台與語言劃分的兩層級範圍 |
| application-signals-cicd-metadata.md | 經由 CI/CD 傳遞 ServiceEvents git 與部署元資料（5 個 OTEL_AWS_SERVICE_EVENTS_* 變數） |
references/appsignals-guides/（例如 eks-python.md） |
16 個涵蓋各平台 × 各語言的啟用指南（EC2/ECS/EKS/Lambda × Python/Node.js/Java/.NET） |
| alarms.md | 指標、複合及異常檢測告警 —— 設定、限制條件與推薦預設值 |
| log-insights.md | 完整查詢語法、命令、函數、已知問題及可複用的查詢庫 |
| metrics.md | 自訂指標、EMF 規格、指標篩選條件、高解析度、保留週期 |
| tracing.md | X-Ray 遷移至 ADOT、採樣規則、註解 (Annotations) 與元資料 (Metadata) 比較、Collector 設定 |
| dashboards.md | Widget 元件類型、跨帳號/跨區域、動態標籤、共用設定 |
| troubleshooting.md | 針對所有可觀測性服務的 錯誤 → 原因 → 修復方案 對照指南 |
| cloudtrail.md | 營運稽核、事件類型、S3+Athena 查詢 |
| synthetics.md | Canary 執行階段/藍圖限制、VPC 網路配置、常見失敗案例 |
| alarm-template.ts | 最佳實踐的 CDK Lambda 監控範本（告警 + 儀表板） |
| otel-config.yaml | 適用於 X-Ray 追蹤與 CloudWatch EMF 指標的 ADOT Collector 設定檔 |
| dynamic-instrumentation.md | 動態埋點偵錯流程 —— 在線上程式碼上設定中斷點/探針、快照擷取與關聯分析、建立/刪除門控機制、快照 PII 敏感資料處理。透過 scripts/di_instrumentation.py 與 scripts/di_snapshots.py 執行。 |
