View a markdown version of this page

Configurar métricas do Claude Code no Amazon CloudWatch com um token de portador - Amazon CloudWatch
Pré-requisitosConfigure o exportador de métricasAdicione identidade e atributos organizacionaisVerifique e visualize

Configurar métricas do Claude Code no Amazon CloudWatch com um token de portador

Nesse caminho, o Claude Code envia métricas do OpenTelemetry (OTel) diretamente para o endpoint de métricas OTLP nativo do Amazon CloudWatch e as autentica com um token de portador (uma chave de API de métricas do CloudWatch). Nenhum coletor do OpenTelemetry é necessário. Essa é a forma mais rápida para um desenvolvedor individual ou uma pequena equipe inserir as métricas do Claude Code nos painéis do Coding Agent Insights.

Importante

Os tokens do portador são credenciais de longo prazo. Nós os recomendamos somente quando credenciais de curto prazo da AWS não são viáveis, como laptops de desenvolvedores fora da AWS. Para obter as compensações de segurança e a orientação sobre rotação de chaves, veja Configurar autenticação do token do portador para Metrics. Organizações que federam identidades por meio de SSO corporativo devem utilizar a implantação corporativa com o gateway de aplicativos Claude ao invés disso. Consulte Configure o Claude Code com o gateway de aplicativos Claude.

Pré-requisitos

  • Claude Code instalado na máquina do desenvolvedor.

  • Uma forma funcional de o Claude Code chamar um modelo para inferência. Essa configuração de telemetria é independente da inferência, então você pode utilizar uma conta Anthropic (o provedor padrão do Claude Code) ou o Amazon Bedrock. Para utilizar o Amazon Bedrock para inferência, veja Claude Code no Amazon Bedrock na documentação do Claude Code.

  • Uma chave de API de métricas do CloudWatch (token portador), criada através de um usuário do IAM que tem permissões de métricas do CloudWatch. Para o procedimento que cria o usuário do IAM e gera a chave, veja Configurar autenticação do token do portador para Metrics.

Configure o exportador de métricas

O Claude Code configura o OpenTelemetry através de variáveis de ambiente. Configure as seguintes variáveis no shell que inicia o Claude Code (ou em seu perfil de shell) para habilitar métricas, selecionar o protocolo OTLP/HTTP e direcionar o exportador de métricas para o endpoint de métricas do CloudWatch com seu token de portador no cabeçalho Authorization. Inclua o caminho /v1/metrics completo.

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT="https://monitoring.region.amazonaws.com/v1/metrics"
export OTEL_EXPORTER_OTLP_METRICS_HEADERS="Authorization=Bearer YOUR_API_KEY"
nota

Trate o token de portador como um segredo. Evite confirmá-lo no controle de origem ou em perfis de shell que são compartilhados ou copiados de maneira insegura. Troque a chave periodicamente conforme descrito em Configurar autenticação do token do portador para Metrics.

Adicione identidade e atributos organizacionais

Os painéis do Coding Agent Insights agrupam o uso por desenvolvedor, equipe, departamento e outras dimensões organizacionais. Forneça-os como atributos de recurso do OTel através da variável de ambiente OTEL_RESOURCE_ATTRIBUTES. Configure os valores com base na identidade do seu desenvolvedor e na estrutura da sua organização.

export OTEL_RESOURCE_ATTRIBUTES="\
user.id=alias,\
user.email=developer@example.com,\
user.name=Jane Doe,\
department=engineering,\
team.id=platform,\
cost_center=cc-1234,\
organization=example-corp,\
location=us-seattle,\
role=software-engineer,\
manager=manager@example.com"
nota

Defini-los como atributos de recursos (em vez de atributos por ponto de dados) corresponde à forma esperada pelos painéis, para que você possa agrupar por @resource.team.id, @resource.department e rótulos semelhantes. O Claude Code marca automaticamente dimensões de nível de métrica, como model e type, nas métricas.

Verifique e visualize

Execute o Claude Code para gerar métricas e, em seguida, confirme se os dados chegaram ao CloudWatch.

Para verificar métricas

  1. Execute uma sessão do Claude Code que realize algum trabalho.

  2. No console do CloudWatch, escolha GenAI Observability, Coding Agent Insights e, em seguida, a guia Claude Code. Normalmente, as métricas aparecem em alguns minutos.

  3. Como opção, consulte as métricas diretamente com o PromQL. Para obter mais informações, consulte Consultas do PromQL.

Para obter a orientação completa e continuamente atualizada, veja a Orientação para Claude Code com o Amazon Bedrock no GitHub.