# Observabilidade de aplicação para o AWS Action
Observabilidade de aplicação para o AWS GitHub Action fornece um fluxo de trabalho de investigação de observabilidade de aplicação de ponta a ponta que conecta o código-fonte e os dados de telemetria da produção ao vivo ao agente de IA. Ele aproveita os MCPs do CloudWatch e gera prompts personalizados para fornecer o contexto de que os agentes de IA precisam para solucionar problemas e aplicar correções de código.
A ação instala e configura o [servidor MCP do CloudWatch Application Signals](https://awslabs.github.io/mcp/servers/cloudwatch-applicationsignals-mcp-server) e o [servidor MCP do CloudWatch](https://awslabs.github.io/mcp/servers/cloudwatch-applicationsignals-mcp-server), permitindo que acessem dados de telemetria ao vivo como contexto da solução de problemas. Você pode usar seu modelo de IA preferido, seja por meio de sua própria chave de API, de um modelo de terceiros ou do Amazon Bedrock, para investigações de performance de aplicações.
Para começar, mencione `@awsapm` nos seus problemas do GitHub para acionar o agente de IA. O agente solucionará os problemas de produção, implementará correções e aprimorará a cobertura da observabilidade com base nos dados da aplicação.
Essa ação em si não incorre em custos diretos. Porém, o uso dessa ação pode gerar cobranças por serviços da AWS e uso do modelo de IA. Consulte a [documentação sobre considerações de custo](https://github.com/marketplace/actions/application-observability-for-aws#-cost-considerations) para saber mais detalhes sobre possíveis custos.
## Conceitos básicos
Essa ação configura agentes de IA no fluxo de trabalho do GitHub gerando configurações de MCP e prompts de observabilidade personalizados específicos da AWS. Você precisa apenas fornecer o perfil do IAM que deve ser assumido e um [ID de modelo do Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html) que você deseja usar ou um token de API de sua assinatura do LLM existente. O exemplo abaixo demonstra um modelo de fluxo de trabalho que integra essa ação com a [claude-code-base-action da Anthropic](https://github.com/anthropics/claude-code-base-action) para executar investigações automatizadas.
### Pré-requisitos
Antes de começar, certifique-se ter:
+ **Permissões do repositório do GitHub**: acesso de gravação ou superior ao repositório (necessário para acionar a ação)
+ **Perfil do AWS IAM**: um perfil do IAM configurado com OpenID Connect (OIDC) para o GitHub Actions com permissões para:
+ Acesso ao CloudWatch Application Signals e ao CloudWatch
+ Acesso a modelo do Amazon Bedrock (se estiver usando modelos Bedrock)
+ **Token do GitHub**: o fluxo de trabalho usa automaticamente o GITHUB\$1TOKEN com as permissões necessárias
### Etapas da configuração
#### Etapa 1: configurar credenciais da AWS
Essa ação depende da ação [aws-actions/configure-aws-credentials](https://github.com/aws-actions/configure-aws-credentials) para configurar a autenticação da AWS no ambiente do GitHub Actions. Recomendamos o uso de OpenID Connect (OIDC) para autenticação na AWS. O OIDC permite que os fluxos de trabalho do GitHub Actions acessem recursos da AWS com credenciais de curta duração da AWS para não ser necessário armazenar credenciais de longo prazo no repositório.
1. **Criar um provedor de identidade do IAM**
Primeiro, crie um provedor de identidade do IAM que confie no endpoint OIDC do GitHub no AWS Management Console:
1. Abrir o console do IAM
1. Clique em **Provedores de identidade** em **Gerenciamento de acesso**
1. Clique no botão **Adicionar provedor** para adicionar um provedor de identidade do GitHub, se ainda não tiver sido criado
1. Selecione o tipo de provedor de identidade **OpenID Connect**
1. Insira `https://token.actions.githubusercontent.com` na caixa de entrada **URL do provedor**
1. Insira `sts.amazonaws.com` Na caixa de entrada **Público**
1. Clique no botão **Adicionar provedor**
1. **Criar uma política do IAM**
Crie uma política do IAM com as permissões necessárias para essa ação. Consulte a seção [Permissões obrigatórias](#Service-Application-Observability-for-AWS-GitHub-Action-required-permissions) abaixo para obter detalhes.
1. **Criar um perfil do IAM**
Crie um perfil do IAM (por exemplo, `AWS_IAM_ROLE_ARN`) no AWS Management Console com o seguinte modelo de política de confiança. Isso permite que repositórios autorizados do GitHub assumam o perfil:
```
{
"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/"
}
}
}
]
}
```
Substitua os seguintes espaços reservados no modelo:
+ ``: o ID da sua conta da AWS
+ ``: o nome da organização do GitHub
+ ``: o nome do repositório
+ ``: o nome da ramificação (por exemplo, principal)
1. **Anexar a política do IAM**
Na guia Permissões do perfil, anexe a política do IAM criada em etapa 2.
Para saber mais sobre a configuração do OIDC com a AWS, consulte o [Guia de início rápido do OIDC configure-aws-credentials](https://github.com/aws-actions/configure-aws-credentials/tree/main?tab=readme-ov-file#quick-start-oidc-recommended).
#### Etapa 2: Configurar segredos e adicionar fluxo de trabalho
1. **Configurar segredos do repositório**
Vá para o repositório → Configurações → Segredos e variáveis → Ações.
+ Crie um novo segredo de repositório denominado `AWS_IAM_ROLE_ARN` e defina seu valor como o ARN do perfil do IAM criado na Etapa 1.
+ (Opcional) Crie uma variável de repositório denominada `AWS_REGION` para especificar a região da AWS (o padrão é `us-east-1` se não estiver definida)
1. **Adicionar o arquivo de fluxo de trabalho**
O exemplo a seguir é de fluxo de trabalho que demonstra o uso dessa ação com os modelos do Amazon Bedrock. Crie o fluxo de trabalho de investigação de observabilidade da aplicação com base nesse modelo no diretório `.github/workflows` do repositório do GitHub.
```
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 }}
```
**Nota da configuração:**
+ Esse fluxo de trabalho é acionado automaticamente quando o `@awsapm` é mencionado em um problema ou comentário
+ O fluxo de trabalho usa o segredo do `AWS_IAM_ROLE_ARN` configurado na etapa anterior
+ Atualize o parâmetro do modelo da Etapa 2 para especificar o ID de seu modelo preferido do Amazon Bedrock
+ Você pode personalizar o nome do bot (por exemplo, `@awsapm-prod`, `@awsapm-staging`) no parâmetro bot\$1name para ter compatibilidade com diferentes ambientes
#### Etapa 3: começar a usar o Action
Depois de configurado o fluxo de trabalho, mencione `@awsapm` em qualquer problema do GitHub para acionar uma investigação baseada em IA. A ação analisará sua solicitação, acessará dados de telemetria ao vivo e fornecerá recomendações ou implementará correções automaticamente.
**Exemplo de casos de uso:**
1. Investigar problemas de performance, publicar e corrigir:
`@awsapm, can you help me investigate availability issues in my appointment service?`
![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/AmazonCloudWatch/latest/monitoring/images/github-availability-issue-investigate.png)
`@awsapm, can you post a fix?`
![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/AmazonCloudWatch/latest/monitoring/images/github-availability-issue-pr-fix.png)
1. Habilitar a instrumentação:
`@awsapm, please enable Application Signals for lambda-audit-service and create a PR with the required changes.`
1. Consulte dados de telemetria:
`@awsapm, how many GenAI tokens have been consumed by my services in the past 24 hours?`
**O que acontece em seguida:**
1. O fluxo de trabalho detecta a menção ao `@awsapm` e aciona a investigação
1. O agente de IA acessa os dados de telemetria da AWS ao vivo por meio dos servidores MCP configurados
1. O agente analisa o problema e:
+ Publica descobertas e recomendações diretamente no problema
+ Cria uma solicitação pull com alterações de código (para instrumentação ou correções)
1. Você pode revisar os resultados e continuar a conversa mencionando @awsapm novamente com perguntas complementares
## Segurança
Essa ação prioriza a segurança com rígidos controles de acesso, autenticação da AWS baseada em OIDC e proteções incorporadas contra ataques de injeção de prompt. Somente usuários com acesso de gravação ou superior podem acionar a ação, e todas as operações têm como escopo o repositório específico.
Para saber mais detalhes sobre segurança, incluindo:
+ Requisitos de controle de acesso e permissão
+ Permissões do AWS IAM e configuração de OIDC
+ Riscos e mitigações de injeção de prompt
+ Práticas recomendadas de segurança
Consulte a [documentação sobre segurança](https://github.com/aws-actions/application-observability-for-aws/blob/main/docs/security.md).
## Configuração
### Permissões obrigatórias
O perfil do IAM assumido pelo GitHub Actions deve ter as seguintes permissões:
**Observação**: `bedrock:InvokeModel` e `bedrock:InvokeModelWithResponseStream` são necessários apenas se você usar os modelos do Amazon Bedrock
```
{
"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": "*"
}
]
}
```
## Documentação
Para saber mais, consulte:
+ [Documentação do CloudWatch Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Intro.html): saiba mais sobre os atributos e recursos do CloudWatch Application Signals
+ [Documentação pública sobre observabilidade de aplicação para o AWS Action](https://github.com/marketplace/actions/application-observability-for-aws): guias e tutoriais detalhados