Agentes APM
Instale o agente APM em um servidor Linux ou Windows, instrumente suas aplicações (também serviços do Windows e IIS), atualize-o sem reinstalar, confira seu status e revogue-o ou remova-o quando não f
Nesta página
- Antes de começar
- Criar o comando de instalação
- Instalar o agente no servidor
- Instrumentar uma aplicação
- Observar uma aplicação sem instrumentá-la (eBPF)
- Instalar o agente no Windows
- Instrumentar um serviço do Windows ou IIS
- Desinstalar o agente do Windows
- O que você ganha
- Ver o status
- Atualizar um agente
- Criar um novo token para um agente
- Revogar um agente
- Remover um agente
- Relacionado
Um agente APM recebe a telemetria das aplicações de um servidor e a envia ao ARGUNIS com um certificado próprio desse agente. Em Configurações → APM → Agentes APM você cria o comando com que ele é instalado, vê os passos para instrumentar cada aplicação, atualiza-o quando há uma nova versão, confere se está conectado e o revoga ou remove.
Antes de começar
O seu plano precisa incluir o módulo APM e o APM precisa estar ativo. Veja Ativar o APM.
Para ver a lista, você precisa de Operar no módulo APM. Para criar tokens, atualizar, revogar ou remover, você precisa de Administrar.
Um servidor Linux com systemd (x64 ou arm64) com alguém que possa usar
sudo, ou um Windows Server 2016 ou posterior (x64) com alguém que possa abrir o PowerShell como Administrador.
Se a página mostrar um aviso acima da lista (por exemplo, que o APM não está ativo), não é possível criar tokens até resolvê-lo.
O ARGUNIS não instala, instrumenta nem reinicia nada por conta própria nos seus servidores. Os comandos desta página são executados pelo administrador do servidor quando ele decidir.
Criar o comando de instalação
Entre em Configurações → APM → Agentes APM.
Clique em Novo agente APM.
Digite um Nome que identifique o servidor ou o sistema (por exemplo, o nome do servidor e seu ambiente). Ele não pode repetir o de outro agente.
Clique em Criar.
Copie o comando com Copiar comando de instalação e guarde-o em um lugar seguro: ele leva o token do agente. Abaixo aparece a Conexão do agente: o endereço onde ele se registra, para onde enviará e a impressão digital da autoridade. Depois clique em Concluído.
O comando é mostrado uma única vez, o token dele serve para instalar um único agente e expira em 24 horas. Se ele se perder ou expirar, crie um novo (abaixo).
Instalar o agente no servidor
Entre no servidor Linux onde as aplicações rodam, com um usuário que possa usar
sudo.Cole e execute o comando que você copiou. Ele tem esta forma:
curl -fsSL 'https://<tu ARGUNIS>/apm-agent/v1/install.sh' | sudo sh -s -- --token 'jaa_…'Espere a mensagem Agente APM … instalado y corriendo.
O instalador confere a assinatura do agente antes de instalar qualquer coisa, cria um usuário de sistema próprio para o agente, registra-o com o token (a chave do certificado é gerada no seu servidor e nunca sai dele) e o deixa como serviço que inicia sozinho. Em poucos minutos o agente aparece conectado na lista.
Em um ARGUNIS instalado na sua rede com um certificado próprio, o comando mostrado na tela já vem preparado para isso: baixa o instalador, confere a impressão digital dele e passa o certificado da sua autoridade (--server-ca). Use-o como está.
Instrumentar uma aplicação
Cada aplicação que você quer ver no APM é instrumentada uma vez, com seu serviço do systemd. Em Configurações → APM → Chave de API e SDK, seção Instrumentar uma aplicação com o agente APM, escolha a linguagem (Java, .NET, Node.js ou Python) para ver os passos exatos.
Se a linguagem pedir, prepare a aplicação:
Node.js: na pasta da aplicação,
npm install @opentelemetry/api @opentelemetry/auto-instrumentations-node.Python: no ambiente da aplicação,
pip install opentelemetry-distro opentelemetry-exporter-otlp && opentelemetry-bootstrap -a install.Java e .NET: nada; o agente baixa e verifica o necessário.
No servidor, execute o comando com o nome do serviço, seu ambiente e sua versão:
sudo argunis-apm-agent --instrumentar facturacion.service --lenguaje java --env produccion --version 1.4.2Só em Python: adicione
opentelemetry-instrumentantes do comando de inicialização do serviço.Reinicie o serviço quando for conveniente (por exemplo, em uma janela de manutenção):
sudo systemctl restart facturacion.serviceO comando deixa a configuração pronta, mas não reinicia a aplicação: ela começa a enviar depois que você a reiniciar.
Para deixar de instrumentá-la, execute sudo argunis-apm-agent --desinstrumentar facturacion.service e reinicie o serviço.
Observar uma aplicação sem instrumentá-la (eBPF)
Se uma aplicação de um servidor Linux não puder ser instrumentada (um programa sem código-fonte, um binário antigo ou uma linguagem sem agente), o agente pode observá-la a partir do sistema operacional com eBPF, usando o OpenTelemetry eBPF Instrumentation (OBI). Ele vê as requisições HTTP e gRPC dela e suas consultas a bancos de dados (MySQL, PostgreSQL, SQL Server, Redis, MongoDB), Kafka e outros, sem mexer na aplicação nem reiniciá-la. Vem desligado: quem o ativa é o administrador do servidor.
Você precisa de um servidor Linux com kernel 5.8 ou superior (ou Red Hat Enterprise Linux 8 e seus derivados) que exponha BTF, como as distribuições atuais (Ubuntu 20.10+, Debian 11+, RHEL 8.2+), e do agente APM já instalado. Se o servidor não cumprir os requisitos, o comando informa e não ativa nada.
Escolha o que observar: os programas que escutam em certas portas ou um executável pelo nome.
No servidor, execute um destes comandos:
sudo argunis-apm-agent --ebpf activar --puertos 80,443,8080 --env produccion
sudo argunis-apm-agent --ebpf activar --proceso facturador --env produccionEspere a mensagem eBPF activado. Em alguns minutos a aplicação aparece em APM → Serviços com o nome do executável dela.
Para conferir, execute sudo argunis-apm-agent --ebpf estado; para alterar o que ele observa, execute de novo --ebpf activar com outras portas ou outro processo; para desligá-lo, sudo argunis-apm-agent --ebpf desactivar.
Com eBPF você vê a taxa, os erros e a latência de cada requisição e de suas chamadas, mas não o que acontece dentro do código (funções, exceções com seu detalhe) nem as requisições HTTPS que a própria aplicação Java criptografa. Se a aplicação puder ser instrumentada com a linguagem dela (acima), essa é a melhor opção. As aplicações já instrumentadas não são duplicadas: o eBPF as pula.
O que cada forma de instrumentar cobre, por linguagem e versão: O que pode ser monitorado com o APM.
Instalar o agente no Windows
No diálogo de instalação do agente, escolha a aba Windows.
No servidor Windows, abra o PowerShell como Administrador.
Copie o comando do Passo 1 e cole-o no PowerShell (é uma única linha). Ele baixa o instalador, confere a impressão digital (SHA-256) e só então o executa.
Quando ele pedir a chave, copie a do Passo 2, cole-a e pressione Enter. Ao colá-la, nada aparece na tela: é normal.
Espere a mensagem Agente APM … instalado y corriendo.
O instalador confere a assinatura do agente, deixa o serviço do Windows ArgunisApmAgent (que inicia sozinho com o host) e registra o agente: a chave do certificado dele é gerada no servidor, em C:\ProgramData\ArgunisApmAgent, que só o sistema e os administradores podem ler. Os registros do agente ficam em C:\ProgramData\ArgunisApmAgent\logs.
Em um ARGUNIS instalado na sua rede com um certificado próprio, o comando da aba Windows já traz o certificado da sua autoridade (-ServerCa). Use-o como está.
Instrumentar um serviço do Windows ou IIS
No Windows, são instrumentadas aplicações .NET (.NET Framework 4.6.2 ou superior e .NET 6 ou superior) e Java (8 ou superior) que rodam como serviço do Windows, e sites .NET no IIS pelo grupo de aplicativos (app pool). O agente baixa e verifica o necessário; não é preciso alterar a aplicação. Todos os comandos vão no PowerShell como Administrador.
Serviço do Windows (use o nome do serviço, o que o Get-Service mostra, não o nome de exibição):
& 'C:\Program Files\ArgunisApmAgent\bin\argunis-apm-agent.ps1' -Instrumentar Facturacion -Lenguaje dotnet -Env produccion -Version 1.4.2Com Java, troque -Lenguaje dotnet por -Lenguaje java. Depois, quando for conveniente, reinicie o serviço:
Restart-Service -Name 'Facturacion'IIS (só .NET), com o nome do app pool:
& 'C:\Program Files\ArgunisApmAgent\bin\argunis-apm-agent.ps1' -AppPool Ventas -Lenguaje dotnet -Env produccionDepois recicle o app pool quando for conveniente:
Restart-WebAppPool -Name 'Ventas'O comando deixa as variáveis da instrumentação no serviço ou no app pool, mas não reinicia a aplicação: ela começa a enviar depois que você a reiniciar ou reciclar. O IIS pode reciclar o app pool por conta própria ao mudar a configuração dele, se estiver configurado assim.
As variáveis que o serviço ou o app pool já tinham são mantidas. Para deixar de instrumentar, execute argunis-apm-agent.ps1 -Desinstrumentar Facturacion (serviço) ou argunis-apm-agent.ps1 -Desinstrumentar -AppPool Ventas (IIS), e reinicie ou recicle: as variáveis do agente são removidas e voltam as que havia antes. Para ver o status do agente: argunis-apm-agent.ps1 -Status.
Desinstalar o agente do Windows
Remova antes a instrumentação de cada aplicação (acima) e reinicie-a: o desinstalador não avança se restar alguma instrumentada.
No PowerShell como Administrador, execute o instalador com
-Desinstalar(baixe-o da URL que o diálogo mostra):
& "$env:TEMP\argunis-apm-agent-install.ps1" -DesinstalarRemova também o agente no ARGUNIS (abaixo, Remover um agente).
O que você ganha
A aplicação aparece em APM → Serviços com o nome, o ambiente e a versão que você indicou, e com seus traces, taxa, erros e latências. Veja Ver os serviços.
O agente envia por um canal criptografado com um certificado próprio que ele renova sozinho antes de vencer.
Se o ARGUNIS não estiver disponível por um tempo, o que for enviado espera no disco do servidor e é mandado na volta, sem se perder.
Ver o status
Cada agente mostra:
Coluna | O que indica |
|---|---|
Status (ponto e texto abaixo do nome) | aguardando instalação (ainda não foi instalado; se disser token expirado, crie um novo), conectado (enviou nos últimos minutos), sem conexão, instalado · ainda não se conectou ou revogado |
Servidor | Nome do host e sistema operacional que o agente informou |
Versão | Versão do agente instalado. → 1.3.1 (amarelo) avisa que há uma nova versão; atualizando para …, que a ordem foi enviada; falhou …, voltou para … (vermelho), que a nova versão não iniciou e o agente continuou com a anterior (passe o mouse para ver o motivo) |
Última conexão | Há quanto tempo ele se conectou ou enviou pela última vez (passe o mouse para ver a data exata) |
Certificado expira | Até quando o certificado dele vale. O agente o renova sozinho antes dessa data |
Atualizar um agente
Quando há uma nova versão do agente APM, a coluna Versão avisa e aparece o botão Atualizar (ícone de setas) na linha. Não é preciso reinstalar nem criar um token: o agente mantém sua identidade, seu certificado, o que tiver em espera no disco, as aplicações instrumentadas e o eBPF.
Na linha do agente, clique em Atualizar (ou em Atualizar todos para … acima da lista, para todos os que tiverem uma versão anterior).
Confirme com Atualizar.
Em no máximo um minuto o agente recebe a ordem: baixa a nova versão, confere a assinatura e reinicia só o agente APM (suas aplicações continuam rodando). Ao terminar, a coluna Versão mostra a nova.
Se a nova versão não iniciar, o agente volta sozinho à anterior em alguns minutos e a linha mostra isso em vermelho. Os dados não se perdem: esperam no disco do servidor enquanto o agente reinicia.
O administrador do servidor também pode atualizá-lo:
sudo argunis-apm-agent --actualizar& 'C:\Program Files\ArgunisApmAgent\bin\argunis-apm-agent.ps1' -ActualizarOs agentes com versão anterior à 1.3.0 não são atualizados pela web (o aviso de nova versão aparece, mas sem botão): reinstale-os uma vez com um novo token (abaixo).
Criar um novo token para um agente
Use-o se o token expirou antes da instalação ou se você precisar reinstalar o agente.
Na linha do agente, clique no ícone de chave (Novo token de instalação).
Confirme com Criar token.
Copie o novo comando de instalação e clique em Concluído.
Execute-o no servidor como em Instalar o agente no servidor ou Instalar o agente no Windows. As aplicações já instrumentadas não são tocadas.
Se o agente já estava instalado, o certificado dele deixa de valer na hora e você terá que instalá-lo de novo com o novo token. Se não estava, os tokens anteriores não usados deixam de valer.
Revogar um agente
Na linha do agente, clique no ícone de parar (Revogar).
Confirme com Revogar.
O certificado dele deixa de valer na hora e o ARGUNIS corta a conexão. O agente fica na lista como revogado; para voltar a usar esse servidor, remova-o e crie um agente novo.
Remover um agente
Na linha do agente, clique no ícone de lixeira (Remover).
Confirme com Remover.
Se o agente estava vigente, o certificado dele deixa de valer na hora e o ARGUNIS corta a conexão. Depois, desinstale-o do servidor.
Os dados que o agente já enviou continuam no APM até vencerem pela retenção.
Relacionado
Instrumentar uma aplicação de servidor (sem agente, enviando direto ao ARGUNIS)