# Habilitar aplicações em clusters do Amazon EKS O CloudWatch Application Signals é compatível com aplicações desenvolvidas em Java, Python, Node.js e .NET. Para habilitar o Application Signals para suas aplicações em um cluster do Amazon EKS existente, você pode usar o Console de gerenciamento da AWS, o AWS CDK, ou a configuração avançada, chamada Monitoramento automático, do complemento de observabilidade do CloudWatch. **Topics** + [Habilitar o Application Signals em um cluster do Amazon EKS usando o console](#CloudWatch-Application-Signals-Enable-EKS-Console) + [Habilitação do Application Signals em um cluster do Amazon EKS usando a configuração avançada do complemento de observabilidade do CloudWatch](#CloudWatch-Application-Signals-Enable-EKS-Addon) + [Habilitar o Application Signals no Amazon EKS usando o AWS CDK](#CloudWatch-Application-Signals-EKS-CDK) + [Habilitar o Application Signals no Amazon EKS usando o protocolo de contexto para modelos (MCP)](#CloudWatch-Application-Signals-EKS-MCP) ## Habilitar o Application Signals em um cluster do Amazon EKS usando o console Para habilitar o CloudWatch Application Signals nas aplicações em um cluster do Amazon EKS existente, use as instruções apresentadas nesta seção. **Importante** Se você já estiver usando o OpenTelemetry com uma aplicação para a qual pretende habilitar o Application Signals, consulte [Sistemas compatíveis](CloudWatch-Application-Signals-supportmatrix.md) antes de habilitar o Application Signals. **Como habilitar o Application Signals para suas aplicações em um cluster do Amazon EKS existente** **nota** Se você ainda não tiver habilitado o Application Signals, siga as instruções em [Habilitar o Application Signals na conta](CloudWatch-Application-Signals-Enable.md) e, em seguida, siga o procedimento abaixo. 1. Abra o console do CloudWatch, em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. Escolha **Application Signals**. 1. Em **Especificar plataforma**, escolha **EKS**. 1. Em **Selecionar um cluster do EKS**, selecione o cluster no qual você deseja habilitar o Application Signals. 1. Se esse cluster ainda não tiver o complemento Amazon CloudWatch Observability do EKS habilitado, você será solicitado a habilitá-lo. Se for esse o caso, faça o seguinte: 1. Escolha **Adicionar o complemento CloudWatch Observability do EKS**. O console do Amazon EKS será exibido. 1. Marque a caixa de seleção para **Amazon CloudWatch Observability** e escolha **Próximo**. O complemento CloudWatch Observability do EKS habilita o Application Signals e o CloudWatch Container Insights com observabilidade aprimorada para o Amazon EKS. Para obter mais informações sobre o Container Insights, consulte [Container Insights](ContainerInsights.md). 1. Selecione a versão mais recente do complemento para a instalação. 1. Selecione um perfil do IAM para usar com o complemento. Se você escolher **Herdar do nó**, anexe as permissões adequadas ao perfil do IAM usado pelos nós de processamento. Substitua *my-worker-node-role* pelo perfil do IAM usado por seus nós de processamento do Kubernetes. ``` aws iam attach-role-policy \ --role-name my-worker-node-role \ --policy-arn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy \ --policy-arn arn:aws:iam::aws:policy/AWSXRayWriteOnlyAccess ``` 1. Caso deseje criar um perfil de serviço para usar o complemento, consulte [Instalação do agente do CloudWatch com o complemento de observabilidade do EKS do Amazon CloudWatch ou com o chart do Helm](install-CloudWatch-Observability-EKS-addon.md). 1. Escolha **Próximo**, confirme as informações na tela e escolha **Criar**. 1. Na próxima tela, escolha **Habilitar o CloudWatch Application Signals** para retornar ao console do CloudWatch e finalizar o processo. 1. Existem duas opções para habilitar as aplicações para o Application Signals. Para manter a consistência, recomendamos que você escolha uma opção por cluster. + A opção **Console** é mais simples. O uso desse método resulta na reinicialização imediata dos seus pods. + O método **Anotar o arquivo de manifesto** oferece mais controle sobre quando os pods serão reiniciados e também pode ajudar no gerenciamento do monitoramento de uma forma mais descentralizada se você não desejar centralizá-lo. **nota** Se você estiver habilitando o Application Signals para uma aplicação do Node.js com ESM, avance para a seção [Configuração de uma aplicação do Node.js usando o formato de módulo ESM](#EKS-NodeJs-ESM). ------ #### [ Console ] A opção **Console** usa a configuração avançada do complemento Observability do Amazon CloudWatch para o EKS para configurar o Application Signals para seus serviços. Para obter mais informações sobre o complemento, consulte [(Opcional) Configuração adicional](install-CloudWatch-Observability-EKS-addon.md#install-CloudWatch-Observability-EKS-addon-configuration). Se você não vir uma lista de workloads e de namespaces, certifique-se de ter as permissões adequadas para visualizá-la neste cluster. Para obter mais informações, consulte [Permissões obrigatórias](https://docs.aws.amazon.com/eks/latest/userguide/view-kubernetes-resources.html#view-kubernetes-resources-permissions). Você pode monitorar todas as workloads dos serviços ao marcar a caixa de seleção **Monitoramento automático** ou ao escolher seletivamente workloads e namespaces específicos para monitorar. Para monitorar todas as workloads dos serviços com o Monitoramento automático: 1. Marque a caixa de seleção **Monitoramento automático** para selecionar automaticamente todas as workloads dos serviços em um cluster. 1. Escolha a opção **Reinício automático** para reiniciar todos os pods referentes às workloads e habilitar imediatamente o Application Signals, com os SDKs de instrumentação automática do AWS Distro para OpenTelemetry (ADOT) injetados em seus pods. 1. Escolha **Concluído**. Quando a opção **Reinício automático** estiver selecionada, o complemento de observabilidade do EKS do CloudWatch ativará o Application Signals imediatamente. Caso contrário, a habilitação do Application Signals ocorrerá durante a próxima implantação individual de cada workload. É possível monitorar workloads únicas ou namespaces inteiros. Para monitorar uma única workload: 1. Marque a caixa de seleção ao lado da workload que você deseja monitorar. 1. Use a lista suspensa **Selecionar idioma(s)** para selecionar o idioma da workload. Selecione os idiomas para os quais deseja ativar o Application Signals e, em seguida, escolha o ícone de marca de seleção (✓) para salvar essa seleção. Para aplicações em Python, certifique-se de que a aplicação siga os pré-requisitos obrigatórios antes de prosseguir. Para obter mais informações, consulte [A aplicação em Python não é iniciada após a habilitação do Application Signals](CloudWatch-Application-Signals-Enable-Troubleshoot.md#Application-Signals-troubleshoot-starting-Python). 1. Escolha **Concluído**. O complemento Observability do Amazon CloudWatch para o EKS injetará imediatamente SDKs da instrumentação automática do AWS Distro para OpenTelemetry (ADOT) em seus pods e acionará reinicializações de pods para habilitar a coleta de métricas e de rastreamentos das aplicações. Para monitorar um namespace inteiro: 1. Marque a caixa de seleção ao lado do namespace que você deseja monitorar. 1. Use a lista suspensa **Selecionar idioma(s)** para selecionar o idioma do namespace. Selecione os idiomas para os quais deseja ativar o Application Signals e, em seguida, escolha o ícone de marca de seleção (✓) para salvar essa seleção. Isso será aplicado a todas as workloads neste namespace, independentemente de estarem implantadas atualmente ou de serem implantadas no futuro. Para aplicações em Python, certifique-se de que a aplicação siga os pré-requisitos obrigatórios antes de prosseguir. Para obter mais informações, consulte [A aplicação em Python não é iniciada após a habilitação do Application Signals](CloudWatch-Application-Signals-Enable-Troubleshoot.md#Application-Signals-troubleshoot-starting-Python). 1. Escolha **Concluído**. O complemento Observability do Amazon CloudWatch para o EKS injetará imediatamente SDKs da instrumentação automática do AWS Distro para OpenTelemetry (ADOT) em seus pods e acionará reinicializações de pods para habilitar a coleta de métricas e de rastreamentos das aplicações. Para habilitar o Application Signals em outro cluster do Amazon EKS, escolha **Habilitar o Application Signals** usando a tela **Serviços**. ------ #### [ Annotate manifest file ] No console do CloudWatch, a seção **Monitorar serviços** explica que você deve adicionar uma anotação a um manifesto em YAML no cluster. A adição dessa anotação instrumenta automaticamente a aplicação para enviar métricas, rastreamentos e logs para o Application Signals. Você tem duas opções para a anotação: + **Anotar a workload** instrumenta automaticamente uma única workload no cluster. + **Anotar o namespace** instrumenta automaticamente todas as workloads implantadas no namespace selecionado. Escolha uma dessas opções e siga as etapas apropriadas: + Para anotar uma única workload: 1. Escolha **Anotar a workload**. 1. Cole uma das linhas apresentadas a seguir na seção `PodTemplate` do arquivo de manifesto da workload. + **Para workloads em Java:** `annotations: instrumentation.opentelemetry.io/inject-java: "true"` + **Para workloads em Python:** `annotations: instrumentation.opentelemetry.io/inject-python: "true"` Para aplicações em Python, existem configurações adicionais necessárias. Para obter mais informações, consulte [A aplicação em Python não é iniciada após a habilitação do Application Signals](CloudWatch-Application-Signals-Enable-Troubleshoot.md#Application-Signals-troubleshoot-starting-Python). + **Para workloads do .NET** `annotations: instrumentation.opentelemetry.io/inject-dotnet: "true"` **nota** Para habilitar o Application Signals para uma workload em .NET em imagens baseadas no Alpine Linux (`linux-musl-x64`), adicione a anotação apresentada a seguir. ``` instrumentation.opentelemetry.io/otel-dotnet-auto-runtime: "linux-musl-x64" ``` + **Para workloads em Node.js:** `annotations: instrumentation.opentelemetry.io/inject-nodejs: "true"` 1. No seu terminal, insira `kubectl apply -f your_deployment_yaml` para aplicar a alteração. + Para anotar todas as workloads em um namespace: 1. Escolha **Anotar o namespace**. 1. Cole uma das linhas apresentadas a seguir na seção de metadados do arquivo de manifesto do namespace. Se o namespace incluir workloads em Java, Python e .NET, cole todas as linhas apresentadas a seguir no arquivo de manifesto do namespace. + **Se houver workloads em Java no namespace:** `annotations: instrumentation.opentelemetry.io/inject-java: "true"` + **Se houver workloads em Python no namespace:** `annotations: instrumentation.opentelemetry.io/inject-python: "true"` Para aplicações em Python, existem configurações adicionais necessárias. Para obter mais informações, consulte [A aplicação em Python não é iniciada após a habilitação do Application Signals](CloudWatch-Application-Signals-Enable-Troubleshoot.md#Application-Signals-troubleshoot-starting-Python). + **Se houver workloads do .NET no namespace:** `annotations: instrumentation.opentelemetry.io/inject-dotnet: "true"` + **Se houver workloads em Node.js no namespace:** `annotations: instrumentation.opentelemetry.io/inject-nodejs: "true"` 1. No seu terminal, insira `kubectl apply -f your_namespace_yaml` para aplicar a alteração. 1. No seu terminal, insira um comando para reiniciar todos os pods no namespace. Um exemplo de comando para reiniciar as workloads de implantação é `kubectl rollout restart deployment -n namespace_name`. ------ 1. Escolha **Visualizar os serviços na conclusão**. Isso direciona você para a visualização dos serviços do Application Signals, um local no qual você pode consultar os dados que o Application Signals está coletando. Pode demorar alguns minutos para que os dados sejam exibidos. Para habilitar o Application Signals em outro cluster do Amazon EKS, escolha **Habilitar o Application Signals** usando a tela **Serviços**. Para obter mais informações sobre a visualização dos **Serviços**, consulte [Monitorar a integridade operacional das suas aplicações com o Application Signals](Services.md). **nota** Se você estiver usando um servidor WSGI para a aplicação em Python, consulte [Não há dados do Application Signals para aplicações em Python que usam um servidor WSGI](CloudWatch-Application-Signals-Enable-Troubleshoot.md#Application-Signals-troubleshoot-Python-WSGI) para obter informações sobre como fazer o Application Signals funcionar. Além disso, identificamos outras considerações que você deve considerar ao habilitar aplicações em Python para o Application Signals. Para obter mais informações, consulte [A aplicação em Python não é iniciada após a habilitação do Application Signals](CloudWatch-Application-Signals-Enable-Troubleshoot.md#Application-Signals-troubleshoot-starting-Python). ### Configuração de uma aplicação do Node.js usando o formato de módulo ESM Fornecemos suporte limitado para aplicações do Node.js com o formato de módulo ESM. Para obter detalhes, consulte [Limitações conhecidas sobre o uso de ESM com o Node.js](CloudWatch-Application-Signals-supportmatrix.md#ESM-limitations). No formato de módulo ESM, a habilitação do Application Signals por meio do console ou ao usar a anotação do arquivo manifesto não funciona corretamente. Ignore a etapa 8 do procedimento anterior e, em vez disso, execute as ações apresentadas a seguir. **Para habilitar o Application Signals em uma aplicação do Node.js com o ESM** 1. Instale as dependências relevantes para a instrumentação automática na aplicação do Node.js: ``` npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation npm install @opentelemetry/instrumentation@0.54.0 ``` 1. Adicione as variáveis de ambiente, apresentadas a seguir, ao Dockerfile da aplicação e crie a imagem. ``` ... ENV OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true ENV OTEL_TRACES_SAMPLER_ARG='endpoint=http://cloudwatch-agent.amazon-cloudwatch:2000' ENV OTEL_TRACES_SAMPLER='xray' ENV OTEL_EXPORTER_OTLP_PROTOCOL='http/protobuf' ENV OTEL_EXPORTER_OTLP_TRACES_ENDPOINT='http://cloudwatch-agent.amazon-cloudwatch:4316/v1/traces' ENV OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT='http://cloudwatch-agent.amazon-cloudwatch:4316/v1/metrics' ENV OTEL_METRICS_EXPORTER='none' ENV OTEL_LOGS_EXPORTER='none' ENV NODE_OPTIONS='--import @aws/aws-distro-opentelemetry-node-autoinstrumentation/register --experimental-loader=@opentelemetry/instrumentation/hook.mjs' ENV OTEL_SERVICE_NAME='YOUR_SERVICE_NAME' #replace with a proper service name ENV OTEL_PROPAGATORS='tracecontext,baggage,b3,xray' ... # command to start the application # for example # CMD ["node", "index.mjs"] ``` 1. Adicione as variáveis de ambiente `OTEL_RESOURCE_ATTRIBUTES_POD_NAME`, `OTEL_RESOURCE_ATTRIBUTES_NODE_NAME`, `OTEL_RESOURCE_ATTRIBUTES_DEPLOYMENT_NAME`, `POD_NAMESPACE` e `OTEL_RESOURCE_ATTRIBUTES` ao arquivo de implantação no formato YAML da aplicação. Por exemplo: ``` apiVersion: apps/v1 kind: Deployment metadata: name: nodejs-app labels: app: nodejs-app spec: replicas: 2 selector: matchLabels: app: nodejs-app template: metadata: labels: app: nodejs-app # annotations: # make sure this annotation doesn't exit # instrumentation.opentelemetry.io/inject-nodejs: 'true' spec: containers: - name: nodejs-app image:your-nodejs-application-image #replace with a proper image uri imagePullPolicy: Always ports: - containerPort: 8000 env: - name: OTEL_RESOURCE_ATTRIBUTES_POD_NAME valueFrom: fieldRef: fieldPath: metadata.name - name: OTEL_RESOURCE_ATTRIBUTES_NODE_NAME valueFrom: fieldRef: fieldPath: spec.nodeName - name: OTEL_RESOURCE_ATTRIBUTES_DEPLOYMENT_NAME valueFrom: fieldRef: fieldPath: metadata.labels['app'] # Assuming 'app' label is set to the deployment name - name: POD_NAMESPACE valueFrom: fieldRef: fieldPath: metadata.namespace - name: OTEL_RESOURCE_ATTRIBUTES value: "k8s.deployment.name=$(OTEL_RESOURCE_ATTRIBUTES_DEPLOYMENT_NAME),k8s.namespace.name=$(POD_NAMESPACE),k8s.node.name=$(OTEL_RESOURCE_ATTRIBUTES_NODE_NAME),k8s.pod.name=$(OTEL_RESOURCE_ATTRIBUTES_POD_NAME)" ``` 1. Realize a implantação da aplicação do Node.js no cluster. Depois de habilitar as aplicações em clusters do Amazon EKS, você pode monitorar a integridade da aplicação. Para obter mais informações, consulte [Monitorar a integridade operacional das suas aplicações com o Application Signals](Services.md). ## Habilitação do Application Signals em um cluster do Amazon EKS usando a configuração avançada do complemento de observabilidade do CloudWatch Por padrão, o monitoramento de performance de aplicações (APM) baseado em OpenTelemetry (OTEL) é habilitado usando o Application Signals ao instalar o complemento CloudWatch Observability para o EKS (V5.0.0 ou acima) ou o chart do Helm. É possível personalizar configurações específicas usando a configuração avançada para o complemento do Amazon EKS ou sobrescrevendo valores no chart do Helm. **nota** Se você usar alguma solução de APM baseada em OpenTelemetry (OTEL), a habilitação do Application Signals afetará a configuração de observabilidade existente. Revise a implementação atual antes de continuar. Para manter a configuração de APM existente depois de atualizar para a V5.0.0 ou posterior, consulte [Optar por não usar o Application Signals](install-CloudWatch-Observability-EKS-addon.md#Opting-out-App-Signals). O complemento de observabilidade do CloudWatch também fornece controle granular adicional para incluir ou excluir serviços específicos, conforme necessário, na nova configuração avançada. Para ter mais informações, consulte [Habilitar APM usando o Application Signals para o cluster do Amazon EKS](install-CloudWatch-Observability-EKS-addon.md#Container-Insights-setup-EKS-appsignalsconfiguration) . ## Habilitar o Application Signals no Amazon EKS usando o AWS CDK Caso ainda não tenha habilitado o Application Signals nessa conta, você deve conceder as permissões necessárias para o Application Signals descobrir seus serviços. Consulte [Habilitar o Application Signals na conta](CloudWatch-Application-Signals-Enable.md). 1. Habilite o Application Signals para aplicações. ``` import { aws_applicationsignals as applicationsignals } from 'aws-cdk-lib'; const cfnDiscovery = new applicationsignals.CfnDiscovery(this, 'ApplicationSignalsServiceRole', { } ); ``` O recurso Discovery CloudFormation concede as seguintes permissões ao Application Signals: + `xray:GetServiceGraph` + `logs:StartQuery` + `logs:GetQueryResults` + `cloudwatch:GetMetricData` + `cloudwatch:ListMetrics` + `tag:GetResources` Para obter mais informações sobre essa função, consulte [Permissões de perfis vinculados ao serviço para o CloudWatch Application Signals](using-service-linked-roles.md#service-linked-role-signals). 1. Instale o complemento `amazon-cloudwatch-observability`. 1. Crie um perfil do IAM com o `CloudWatchAgentServerPolicy` e o OIDC associados ao cluster. ``` const cloudwatchRole = new Role(this, 'CloudWatchAgentAddOnRole', { assumedBy: new OpenIdConnectPrincipal(cluster.openIdConnectProvider), managedPolicies: [ManagedPolicy.fromAwsManagedPolicyName('CloudWatchAgentServerPolicy')], }); ``` 1. Instale o complemento com o perfil do IAM criado acima. ``` new CfnAddon(this, 'CloudWatchAddon', { addonName: 'amazon-cloudwatch-observability', clusterName: cluster.clusterName, serviceAccountRoleArn: cloudwatchRole.roleArn }); ``` 1. Inclua uma das seguintes linhas na seção `PodTemplate` do arquivo de manifesto da workload. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable-EKS.html) ``` const deployment = { apiVersion: "apps/v1", kind: "Deployment", metadata: { name: "sample-app" }, spec: { replicas: 3, selector: { matchLabels: { "app": "sample-app" } }, template: { metadata: { labels: { "app": "sample-app" }, annotations: { "instrumentation.opentelemetry.io/inject-$LANG": "true" } }, spec: {...}, }, }, }; cluster.addManifest('sample-app', deployment) ``` ## Habilitar o Application Signals no Amazon EKS usando o protocolo de contexto para modelos (MCP) Você pode usar o servidor MCP (protocolo de contexto para modelos) do Application Signals do CloudWatch para habilitar o Application Signals nos clusters do Amazon EKS por meio de interações conversacionais de IA. Isso fornece uma interface de linguagem natural para configurar o monitoramento do Application Signals. O servidor MCP automatiza o processo de habilitação compreendendo os requisitos e gerando a configuração apropriada. Em vez de seguir as etapas do console manualmente ou escrever código de CDK, você pode simplesmente descrever o que deseja habilitar. ### Pré-requisitos Antes de usar o servidor MCP para habilitar o Application Signals, certifique-se de ter: + Um ambiente de desenvolvimento compatível com MCP (como Kiro, Claude Desktop, VSCode com extensões MCP ou outras ferramentas compatíveis com MCP) + O servidor MCP do Application Signals do CloudWatch configurado no IDE. Para obter instruções detalhadas de configuração, consulte a documentação do [servidor MCP do Application Signals do CloudWatch](https://awslabs.github.io/mcp/servers/cloudwatch-applicationsignals-mcp-server). ### Usar um servidor MCP Depois de configurar o servidor MCP do CloudWatch Application Signals no IDE, você pode solicitar orientação sobre a habilitação usando prompts em linguagem natural. Embora o assistente de codificação possa inferir o contexto da estrutura do projeto, fornecer detalhes específicos nas instruções ajuda a garantir uma orientação mais precisa e relevante. Inclua informações como a linguagem da aplicação, o nome do cluster do Amazon EKS e caminhos absolutos para a infraestrutura e o código da aplicação. **Prompts de acordo com as práticas recomendadas (específicos e completos):** ``` "Enable Application Signals for my Python service running on EKS. My app code is in /home/user/flask-api and IaC is in /home/user/flask-api/terraform" "I want to add observability to my Node.js application on EKS cluster 'production-cluster'. The application code is at /Users/dev/checkout-service and the Kubernetes manifests are at /Users/dev/checkout-service/k8s" "Help me instrument my Java Spring Boot application on EKS with Application Signals. Application directory: /opt/apps/payment-api CDK infrastructure: /opt/apps/payment-api/cdk" ``` **Prompts menos eficazes:** ``` "Enable monitoring for my app" → Missing: platform, language, paths "Enable Application Signals. My code is in ./src and IaC is in ./infrastructure" → Problem: Relative paths instead of absolute paths "Enable Application Signals for my EKS service at /home/user/myapp" → Missing: programming language ``` **Modelo rápido:** ``` "Enable Application Signals for my [LANGUAGE] service on EKS. App code: [ABSOLUTE_PATH_TO_APP] IaC code: [ABSOLUTE_PATH_TO_IAC]" ``` ### Benefícios de usar o servidor MCP O uso do servidor MCP do CloudWatch Application Signals oferece várias vantagens: + **Interface em linguagem natural:** descreva o que você deseja habilitar sem memorizar comandos nem sintaxe de configuração + **Orientação contextual:** o servidor MCP compreende seu ambiente específico e fornece recomendações personalizadas + **Menos erros:** a geração automatizada de configuração minimiza os erros da digitação manual + **Configuração mais rápida:** passe da intenção à implementação mais rapidamente + **Ferramenta de aprendizagem:** veja as configurações geradas e entenda como o Application Signals funciona ### Recursos adicionais Para saber mais sobre a configuração e o uso do servidor MCP do CloudWatch Application Signals, consulte a [documentação do servidor MCP](https://awslabs.github.io/mcp/servers/cloudwatch-applicationsignals-mcp-server).