本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# AWS 動作的應用程式可觀測性
Application Observability for AWS GitHub Action 提供end-to-end應用程式觀察性調查工作流程，將您的原始程式碼和即時生產遙測資料連線至 AI 代理器。它利用 CloudWatch MCPs 並產生自訂提示，以提供 AI 代理器故障診斷和套用程式碼修正所需的內容。
動作會設定 [CloudWatch Application Signals MCP Server](https://awslabs.github.io/mcp/servers/cloudwatch-applicationsignals-mcp-server) 和 [CloudWatch MCP Server](https://awslabs.github.io/mcp/servers/cloudwatch-applicationsignals-mcp-server)，讓他們能夠存取即時遙測資料做為疑難排解內容。您可以使用您偏好的 AI 模型 - 無論是透過您自己的 API 金鑰、第三方模型或 Amazon Bedrock - 進行應用程式效能調查。
若要開始使用，請在 GitHub 問題`@awsapm`中提及 以觸發 AI 代理器。代理程式會根據您的即時應用程式資料，對生產問題進行故障診斷、實作修正並增強可觀測性涵蓋範圍。
此動作本身不會產生任何直接成本。不過，使用此動作可能會導致 AWS 服務和 AI 模型使用費。如需潛在成本的詳細資訊，[請參閱成本考量文件](https://github.com/marketplace/actions/application-observability-for-aws#-cost-considerations)。
## 開始使用
此動作會透過產生 AWS特定的 MCP 組態和自訂可觀測性提示，在您的 GitHub 工作流程中設定 AI 代理器。您只需要提供要擔任的 IAM 角色和要使用的 [Bedrock 模型 ID](https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html)，或現有 LLM 訂閱中的 API 權杖。以下範例示範工作流程範本，此範本會將此動作與 [Anthropic 的 claude-code-base-action](https://github.com/anthropics/claude-code-base-action) 整合，以執行自動化調查。
### 先決條件
開始之前，請確定您有下列項目：
+ **GitHub 儲存庫許可**：寫入存取儲存庫或更高版本 （觸發 動作時需要）
+ **AWS IAM 角色**：針對具有下列許可的 GitHub 動作使用 OpenID Connect (OIDC) 設定的 IAM 角色：
+ CloudWatch Application Signals 和 CloudWatch 存取
+ Amazon Bedrock 模型存取 （如果使用 Bedrock 模型）
+ **GitHub 權杖**：工作流程會自動使用具有所需許可的 GITHUB\$1TOKEN
### 設定步驟
#### 步驟 1：設定 AWS 登入資料
此動作倚賴 [aws-actions/configure-aws-credentials](https://github.com/aws-actions/configure-aws-credentials) 動作，在您的 GitHub Actions Environment 中設定 AWS 身分驗證。建議使用 OpenID Connect (OIDC) 進行身分驗證 AWS。OIDC 允許 GitHub 動作工作流程使用短期 AWS 憑證存取 AWS 資源，因此您不需要在儲存庫中存放長期憑證。
1. **建立 IAM 身分提供者**
首先，在 AWS 管理主控台中建立信任 GitHub OIDC 端點的 IAM 身分提供者：
1. 開啟 IAM 主控台
1. 按一下**存取管理**下的**身分提供者**
1. 如果尚未建立，請按一下**新增提供者**按鈕來新增 GitHub Identity 提供者
1. 選取身分提供者的 **OpenID Connect** 類型
1. 在**提供者 URL** `https://token.actions.githubusercontent.com` 輸入方塊中輸入
1. **對象**輸入方塊`sts.amazonaws.com`的 Enter
1. 按一下**新增供應商**按鈕
1. **建立 IAM 政策**
建立具有此動作所需許可的 IAM 政策。如需詳細資訊，請參閱以下[所需的許可](#Service-Application-Observability-for-AWS-GitHub-Action-required-permissions)章節。
1. **建立 IAM 角色**
使用下列信任政策範本在 AWS 管理主控台中建立 IAM 角色 （例如 `AWS_IAM_ROLE_ARN`)。這可讓授權的 GitHub 儲存庫擔任該角色：
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Federated": "arn:aws:iam:::oidc-provider/token.actions.githubusercontent.com"
},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {
"StringEquals": {
"token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
},
"StringLike": {
"token.actions.githubusercontent.com:sub": "repo:/:ref:refs/heads/"
}
}
}
]
}
```
取代範本中的下列預留位置：
+ `` - AWS 您的帳戶 ID
+ `` - 您的 GitHub 組織名稱
+ `` - 您的儲存庫名稱
+ `` - 您的分支名稱 （例如主要）
1. **連接 IAM 政策**
在角色的許可索引標籤中，連接您在步驟 2 中建立的 IAM 政策。
如需使用 設定 OIDC 的詳細資訊 AWS，請參閱 [configure-aws-credentials OIDC Quick Start Guide](https://github.com/aws-actions/configure-aws-credentials/tree/main?tab=readme-ov-file#quick-start-oidc-recommended)。
#### 步驟 2：設定秘密並新增工作流程
1. **設定儲存庫秘密**
前往您的儲存庫 → 設定 → 秘密和變數 → 動作。
+ 建立名為 的新儲存庫秘密，並將其值`AWS_IAM_ROLE_ARN`設定為您在步驟 1 中建立之 IAM 角色的 ARN。
+ （選用） 建立名為 的儲存庫變數`AWS_REGION`來指定您的 AWS 區域 (`us-east-1`若未設定，預設為 )
1. **新增工作流程檔案**
以下是示範將此動作與 Amazon Bedrock 模型搭配使用的範例工作流程。在 GitHub 儲存庫目錄 中，從此範本建立應用程式可觀測性調查工作流程`.github/workflows`。
```
name: Application observability for AWS
on:
issue_comment:
types: [created, edited]
issues:
types: [opened, assigned, edited]
jobs:
awsapm-investigation:
if: |
(github.event_name == 'issue_comment' && contains(github.event.comment.body, '@awsapm')) ||
(github.event_name == 'issues' && (contains(github.event.issue.body, '@awsapm') || contains(github.event.issue.title, '@awsapm')))
runs-on: ubuntu-latest
permissions:
contents: write # To create branches for PRs
pull-requests: write # To post comments on PRs
issues: write # To post comments on issues
id-token: write # Required for AWS OIDC authentication
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Configure AWS credentials
uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: ${{ secrets.AWS_IAM_ROLE_ARN }}
aws-region: ${{ vars.AWS_REGION || 'us-east-1' }}
# Step 1: Prepare AWS MCP configuration and investigation prompt
- name: Prepare Investigation Context
id: prepare
uses: aws-actions/application-observability-for-aws@v1
with:
bot_name: "@awsapm"
cli_tool: "claude_code"
# Step 2: Execute investigation with Claude Code
- name: Run Claude Investigation
id: claude
uses: anthropics/claude-code-base-action@beta
with:
use_bedrock: "true"
# Set to any Bedrock Model ID
model: "us.anthropic.claude-sonnet-4-5-20250929-v1:0"
prompt_file: ${{ steps.prepare.outputs.prompt_file }}
mcp_config: ${{ steps.prepare.outputs.mcp_config_file }}
allowed_tools: ${{ steps.prepare.outputs.allowed_tools }}
# Step 3: Post results back to GitHub issue/PR (reuse the same action)
- name: Post Investigation Results
if: always()
uses: aws-actions/application-observability-for-aws@v1
with:
cli_tool: "claude_code"
comment_id: ${{ steps.prepare.outputs.awsapm_comment_id }}
output_file: ${{ steps.claude.outputs.execution_file }}
output_status: ${{ steps.claude.outputs.conclusion }}
```
**組態備註：**
+ 在問題或評論中`@awsapm`提及 時，此工作流程會自動觸發
+ 工作流程使用上一個步驟中設定的`AWS_IAM_ROLE_ARN`秘密
+ 更新步驟 2 中的模型參數，以指定您偏好的 Amazon Bedrock 模型 ID
+ 您可以在 bot\$1name 參數中自訂機器人名稱 （例如 `@awsapm-prod`、`@awsapm-staging`)，以支援不同的環境
#### 步驟 3：開始使用 動作
設定工作流程後，請在任何 GitHub 問題`@awsapm`中提及 ，以觸發 AI 支援的調查。動作會分析您的請求、存取即時遙測資料，並自動提供建議或實作修正。
**範例使用案例：**
1. 調查效能問題並發佈和修正：
`@awsapm, can you help me investigate availability issues in my appointment service?`
![\[alt text not found\]](http://docs.aws.amazon.com/zh_tw/AmazonCloudWatch/latest/monitoring/images/github-availability-issue-investigate.png)
`@awsapm, can you post a fix?`
![\[alt text not found\]](http://docs.aws.amazon.com/zh_tw/AmazonCloudWatch/latest/monitoring/images/github-availability-issue-pr-fix.png)
1. 啟用檢測：
`@awsapm, please enable Application Signals for lambda-audit-service and create a PR with the required changes.`
1. 查詢遙測資料：
`@awsapm, how many GenAI tokens have been consumed by my services in the past 24 hours?`
**接下來會發生什麼：**
1. 工作流程會偵測`@awsapm`提及項目並觸發調查
1. AI 代理器會透過設定的 MCP 伺服器存取您的即時 AWS 遙測資料
1. 代理程式會分析問題，並：
+ 直接在問題中發佈問題清單和建議
+ 建立具有程式碼變更的提取請求 （用於檢測或修正）
1. 您可以使用後續問題再次提及 @awsapm，來檢閱結果並繼續對話
## 安全
此動作透過嚴格的存取控制、以 OIDC 為基礎的 AWS 身分驗證，以及內建的保護來防範提示注入攻擊，以排定安全性的優先順序。只有具有寫入存取權或更高層級的使用者才能觸發 動作，而且所有操作都會範圍限定在特定儲存庫。
如需詳細的安全性資訊，包括：
+ 存取控制和許可要求
+ AWS IAM 許可和 OIDC 組態
+ 提示注入風險和緩解措施
+ 安全最佳實務
請參閱 [安全文件](https://github.com/aws-actions/application-observability-for-aws/blob/main/docs/security.md)。
## Configuration
### 所需的許可
GitHub Actions 擔任的 IAM 角色必須具有下列許可。
**注意**：`bedrock:InvokeModelWithResponseStream`只有在您使用 Amazon Bedrock 模型時才需要 `bedrock:InvokeModel`和
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"application-signals:ListServices",
"application-signals:GetService",
"application-signals:ListServiceOperations",
"application-signals:ListServiceLevelObjectives",
"application-signals:GetServiceLevelObjective",
"application-signals:ListAuditFindings",
"cloudwatch:DescribeAlarms",
"cloudwatch:DescribeAlarmHistory",
"cloudwatch:ListMetrics",
"cloudwatch:GetMetricData",
"cloudwatch:GetMetricStatistics",
"logs:DescribeLogGroups",
"logs:DescribeQueryDefinitions",
"logs:ListLogAnomalyDetectors",
"logs:ListAnomalies",
"logs:StartQuery",
"logs:StopQuery",
"logs:GetQueryResults",
"logs:FilterLogEvents",
"xray:GetTraceSummaries",
"xray:GetTraceSegmentDestination",
"xray:BatchGetTraces",
"xray:ListRetrievedTraces",
"xray:StartTraceRetrieval",
"servicequotas:GetServiceQuota",
"synthetics:GetCanary",
"synthetics:GetCanaryRuns",
"s3:GetObject",
"s3:ListBucket",
"iam:GetRole",
"iam:ListAttachedRolePolicies",
"iam:GetPolicy",
"iam:GetPolicyVersion",
"bedrock:InvokeModel",
"bedrock:InvokeModelWithResponseStream"
],
"Resource": "*"
}
]
}
```
## 文件
如需詳細資訊，請參閱：
+ [CloudWatch Application Signals 文件](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Intro.html) - 了解 CloudWatch Application Signals 功能
+ [AWS 動作公開文件的應用程式可觀測性](https://github.com/marketplace/actions/application-observability-for-aws) - 詳細指南和教學課程