Observabilidade de aplicação para o AWS Action - Amazon CloudWatch
Conceitos básicosSegurançaConfiguraçãoDocumentação

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 e o servidor MCP do CloudWatch, 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 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 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 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_TOKEN 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 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

    2. Clique em Provedores de identidade em Gerenciamento de acesso

    3. Clique no botão Adicionar provedor para adicionar um provedor de identidade do GitHub, se ainda não tiver sido criado

    4. Selecione o tipo de provedor de identidade OpenID Connect

    5. Insira https://token.actions.githubusercontent.com na caixa de entrada URL do provedor

    6. Insira sts.amazonaws.com Na caixa de entrada Público

    7. Clique no botão Adicionar provedor

  2. 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 abaixo para obter detalhes.

  3. 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::<AWS_ACCOUNT_ID>: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:<GITHUB_ORG>/<GITHUB_REPOSITORY>:ref:refs/heads/<GITHUB_BRANCH>"
        }
      }
    }
  ]
}

    Substitua os seguintes espaços reservados no modelo:

    • <AWS_ACCOUNT_ID>: o ID da sua conta da AWS

    • <GITHUB_ORG>: o nome da organização do GitHub

    • <GITHUB_REPOSITORY>: o nome do repositório

    • <GITHUB_BRANCH>: o nome da ramificação (por exemplo, principal)

  4. 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.

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)

  2. 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_name 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?

    @awsapm, can you post a fix?

  2. Habilitar a instrumentação:

    @awsapm, please enable Application Signals for lambda-audit-service and create a PR with the required changes.

  3. 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

  2. O agente de IA acessa os dados de telemetria da AWS ao vivo por meio dos servidores MCP configurados

  3. 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)

  4. 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.

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: