View a markdown version of this page

Depurar aplicativos com Dynamic Instrumentation - Amazon CloudWatch
ConceitosIdiomas compatíveisPré-requisitosAdicionar instrumentação dinâmica à sua aplicaçãoArmazenamento de dadosExibir e gerenciar configuraçõesSaiba mais sobre o statusLimites de captura

Depurar aplicativos com Dynamic Instrumentation

Com o Dynamic Instrumentation, é possível capturar o estado do runtime de um aplicativo ativo sem reiniciar ou reimplantar. O estado do runtime inclui valores de variáveis, argumentos de método, valores de retorno e rastreamentos de pilha. Você define configurações de instrumentação que especificam onde capturar dados em seu código, e o agente em execução instrumenta o aplicativo em runtime.

Conceitos

Ponto de interrupção

Instrumentação temporária que expira de maneira automática. A expiração padrão é de 24 horas, configurável de 5 minutos a 24 horas. Utilize pontos de interrupção para depuração e investigação.

Sonda

Instrumentação permanente que persiste até ser explicitamente excluída. Utilize sondas para observabilidade contínua.

Snapshot

Uma captura pontual do estado do programa, incluindo variáveis locais, argumentos, valor de retorno, exceções e rastreamento de pilha. O Dynamic Instrumentation emite snapshots como registros de log para o CloudWatch Logs.

Local

O local do código em que a instrumentação é aplicada. Os campos obrigatórios variam de acordo com a linguagem.

Idiomas compatíveis

  • Java

  • Python

  • JavaScript ou TypeScript

Pré-requisitos

Para usar o Dynamic Instrumentation, atualize seus componentes de instrumentação para a versão mais recente com base no seu tipo de implantação:

  • Clientes do Amazon EKS — atualize o complemento do Amazon CloudWatch Observability EKS para a versão mais recente. O complemento inclui o SDK ADOT e o CloudWatch Agent. Para obter mais informações, consulte Instalar o complemento CloudWatch Observability EKS.

  • Todos os outros clientes — atualize os dois componentes a seguir:

    • O SDK de instrumentação do AWS Distro for OpenTelemetry (ADOT) para sua linguagem (Java, Python ou Node.js).

    • O CloudWatch Agent para a versão mais recente.

As seguintes condições também devem ser atendidas:

  • O CloudWatch Application Signals deve estar habilitado para seu aplicativo.

  • Defina a variável de ambiente OTEL_AWS_DYNAMIC_INSTRUMENTATION_ENABLED=true em seu aplicativo.

  • Defina a variável de ambiente OTEL_SERVICE_NAME para o nome do serviço.

  • Defina a variável de ambiente OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=my_deployment_env_name. Para usuários existentes do Application Signals, o valor deve corresponder ao nome do ambiente do seu serviço, conforme aparece no console do Application Signals.

  • O CloudWatch Agent deve estar em execução com a configuração do Application Signals.

  • A instrumentação dinâmica não é compatível com ambientes Lambda.

Adicionar instrumentação dinâmica à sua aplicação

Depois de instrumentar seu aplicativo (veja Pré-requisitos), você cria uma configuração de instrumentação que especifica em qual parte do seu código você deseja introduzir a telemetria dinâmica. Cada configuração define duas coisas:

  1. Onde monitorar no código — o local do código em que o ponto de interrupção ou a sonda é aplicado.

  2. Quais dados capturar — o estado de runtime capturado quando o ponto de interrupção ou a sonda é executado.

nota

Por padrão, o Dynamic Instrumentation captura apenas dados limitados. Para maximizar o valor desse atributo, considere expandir a configuração de captura usando as opções descritas em Limites de captura.

É possível criar configurações usando a CLI ou o SDK da AWS, ou usando o servidor do protocolo de contexto para modelos (MCP) com um assistente de codificação de IA em seu IDE.

Criar configurações usando a CLI ou o SDK

Use a CLI da AWS ou o SDK da AWS para criar configurações de instrumentação programaticamente.

Especifique o local do código

O local define onde a instrumentação é aplicada no seu código. Os campos obrigatórios variam de acordo com a linguagem:

Linguagem Campos obrigatórios Campos opcionais
Java CodeUnit (pacote), ClassName, MethodName, FilePath LineNumber
Python CodeUnit (módulo), MethodName, FilePath LineNumber, ClassName
JavaScript ou TypeScript FilePath, LineNumber Nenhum. Apenas pontos de interrupção em nível de linha são suportados. Sondas e pontos de interrupção em nível de função não são compatíveis. O TypeScript é compatível quando você fornece mapas de origem.

Configurar quais dados capturar

A configuração de captura controla qual estado de runtime é coletado quando a instrumentação é acionada. Opções disponíveis:

  • CaptureArguments — Lista de nomes de argumentos de métodos a serem capturados.

  • CaptureReturn — Capture o valor de retorno (booleano).

  • CaptureStackTrace — Capture o rastreamento de pilha (booleano).

  • CaptureLocals — Lista de nomes de variáveis locais a serem capturadas.

  • CaptureLimits — Controle a profundidade e o tamanho da captura (veja Limites de captura).

Parâmetros de configuração

Parâmetros-chave ao criar uma configuração:

  • instrumentation-type — BREAKPOINT ou PROBE

  • service — O nome do serviço conforme relatado pelo Application Signals

  • environment — O nome do ambiente

  • signal-type — SNAPSHOT

  • location — Campos de logal do código (veja acima)

  • capture-configuration — Opções de captura (veja acima)

Exemplo

O exemplo mostrado a seguir cria um ponto de interrupção em um método Java:

aws application-signals create-instrumentation-configuration \
    --instrumentation-type BREAKPOINT \
    --service "my-service" \
    --environment "production" \
    --signal-type SNAPSHOT \
    --location '{
        "CodeLocation": {
            "Language": "Java",
            "CodeUnit": "com.example.service",
            "ClassName": "OrderController",
            "MethodName": "processOrder",
            "FilePath": "OrderController.java"
        }
    }' \
    --capture-configuration '{
        "CodeCapture": {
            "CaptureArguments": ["orderId", "user"],
            "CaptureReturn": true,
            "CaptureStackTrace": true,
            "CaptureLimits": {
                "MaxHits": 100,
                "MaxStringLength": 255,
                "MaxCollectionWidth": 20,
                "MaxObjectDepth": 3,
                "MaxFieldsPerObject": 20,
                "MaxStackFrames": 20
            }
        }
    }'

Criar configurações usando o servidor MCP

A abordagem recomendada para usar o Dynamic Instrumentation é por meio do servidor MCP (Model Context Protocol) do CloudWatch Application Signals. O MCP permite que assistentes e agentes de codificação de IA em seu IDE criem, gerenciem e consultem configurações do Dynamic Instrumentation diretamente do seu ambiente de desenvolvimento.

Usando o MCP, seu assistente de IA pode:

  • Criar pontos de interrupção e sondas em locais de código específicos sem sair do editor.

  • Consultar os snapshots capturados para inspecionar os valores das variáveis de runtime e os caminhos de chamada.

  • Correlacionar automaticamente os dados do snapshot com o código em que você está trabalhando para sugerir correções.

  • Gerenciar o ciclo de vida das configurações de instrumentação (visualizar o status, excluir os pontos de interrupção expirados).

Para obter instruções de configuração e uso, veja o servidor MCP do Application Signals no site do GitHub.

Armazenamento de dados

Quando um ponto de interrupção ou sonda é acionado, o Dynamic Instrumentation cria um grupo de logs no CloudWatch Logs com o prefixo /aws/application-signals/service-name (em que service-name é o valor da sua variável de ambiente OTEL_SERVICE_NAME) e grava os snapshots capturados como registros de log nesse grupo de logs.

Se o grupo de logs ainda não existir, o Dynamic Instrumentation o criará de maneira automática na primeira vez que um snapshot for emitido. Você é cobrado pela ingestão e pelo armazenamento de logs de acordo com as taxas padrão do CloudWatch Logs.

Exibir e gerenciar configurações

No console do CloudWatch, navegue até a página de detalhes do serviço e escolha a guia Instrumentação.

  • Alterne entre Pontos de interrupção e Sondas para ver as configurações por tipo.

  • Visualize detalhes da configuração, incluindo descrição, configuração de captura, local, ARN e tempo de expiração.

  • Visualize o histórico de status para rastrear as transições: Pronto para Ativo para Erro/Desativado.

  • Exclua configurações que não sejam mais necessárias.

Saiba mais sobre o status

Cada configuração de instrumentação tem um status que indica seu estado atual.

Status Descrição
READY O agente recebeu a configuração.
ACTIVE O agente aplicou a instrumentação ao aplicativo em execução.
ERROR A instrumentação não foi aplicada. Veja a causa do erro para obter detalhes.
DESATIVADA A instrumentação expirou ou você a removeu.

Quando uma instrumentação entra no estado ERROR, as seguintes causas podem ser relatadas:

Causa do erro Descrição
FILE_NOT_FOUND O caminho de arquivo especificado não existe no aplicativo.
METHOD_NOT_FOUND O método especificado não existe na classe ou no módulo de destino.
LINE_NOT_EXECUTABLE O número da linha especificado não corresponde a uma instrução executável.
OVERLOADED_METHODS Vários métodos correspondem ao nome especificado. Forneça detalhes adicionais do local para identificar o método correto.
LANGUAGE_MISMATCH Os campos de local não correspondem à linguagem do aplicativo em execução.
RUNTIME_ERROR Ocorreu um erro inesperado ao aplicar a instrumentação.

Limites de captura

Os limites de captura controlam o tamanho e a profundidade dos dados capturados. Configure esses valores no campo capture-limits da configuração de captura.

Limite Padrão Intervalo Descrição
maxStringLength 255 1–255 Máximo de caracteres capturados por valor de string.
maxCollectionWidth 20 1–20 Máximo de elementos capturados por coleta ou matriz.
maxObjectDepth 3 1–5 Profundidade máxima para percurso de objetos aninhados.
maxFieldsPerObject 20 1–20 Máximo de campos capturados por objeto.
maxStackFrames 20 1–20 Máximo de quadros de pilha capturados.
maxHits 100 1–1.000 Máximo de capturas antes da desativação automática. Apenas pontos de interrupção.

Cada ponto de instrumentação tem uma taxa limitada a 5 capturas por segundo.