DocumentaciónAide

Agents APM

Installez l'agent APM sur Linux ou Windows, instrumentez ses applications (services Windows et IIS compris), mettez-le à jour sans réinstaller, et révoquez-le ou retirez-le.

Sur cette page

Un agent APM reçoit la télémétrie des applications d'un serveur et l'envoie à ARGUNIS avec un certificat propre à cet agent. Dans Paramètres → APM → Agents APM, vous créez la commande d'installation, voyez les étapes pour instrumenter chaque application, le mettez à jour quand une nouvelle version sort, vérifiez s'il est connecté et le révoquez ou le retirez.

Avant de commencer

  • Votre forfait doit inclure le module APM et l'APM doit être actif. Voir Activer l'APM.

  • Pour voir la liste, il vous faut Opérer sur le module APM. Pour créer des jetons, mettre à jour, révoquer ou retirer, il vous faut Administrer.

  • Un serveur Linux avec systemd (x64 ou arm64) avec quelqu'un qui peut utiliser sudo, ou un Windows Server 2016 ou ultérieur (x64) avec quelqu'un qui peut ouvrir PowerShell en tant qu'Administrateur.

Si la page affiche un message au-dessus de la liste (par exemple, que l'APM n'est pas actif), aucun jeton ne peut être créé tant que ce n'est pas résolu.

ARGUNIS n'installe, n'instrumente et ne redémarre rien de lui-même sur vos serveurs. Les commandes de cette page sont exécutées par l'administrateur du serveur quand il le décide.

Créer la commande d'installation

  1. Allez dans Paramètres → APM → Agents APM.

  2. Appuyez sur Nouvel agent APM.

  3. Saisissez un Nom qui identifie le serveur ou le système (par exemple, le nom du serveur et son environnement). Il ne peut pas reprendre celui d'un autre agent.

  4. Appuyez sur Créer.

  5. Copiez la commande avec Copier la commande d'installation et conservez-la en lieu sûr : elle contient le jeton de l'agent. En dessous apparaît la Connexion de l'agent : l'adresse où il s'enrôle, la destination de ses envois et l'empreinte de l'autorité. Appuyez ensuite sur Terminé.

La commande ne s'affiche qu'une seule fois, son jeton ne sert qu'à installer un seul agent et expire au bout de 24 heures. S'il est perdu ou expiré, créez-en un nouveau (voir plus bas).

Installer l'agent sur le serveur

  1. Connectez-vous au serveur Linux où s'exécutent les applications, avec un utilisateur qui peut utiliser sudo.

  2. Collez et exécutez la commande que vous avez copiée. Elle a cette forme :

curl -fsSL 'https://<tu ARGUNIS>/apm-agent/v1/install.sh' | sudo sh -s -- --token 'jaa_…'
  1. Attendez le message Agente APM … instalado y corriendo.

L'installateur vérifie la signature de l'agent avant d'installer quoi que ce soit, crée un utilisateur système propre à l'agent, l'enrôle avec le jeton (la clé du certificat est générée sur votre serveur et n'en sort jamais) et le laisse comme service qui démarre tout seul. En quelques minutes, l'agent apparaît connecté dans la liste.

Pour un ARGUNIS installé dans votre réseau avec un certificat propre, la commande affichée à l'écran est déjà préparée pour cela : elle télécharge l'installateur, vérifie son empreinte et lui transmet le certificat de votre autorité (--server-ca). Utilisez-la telle quelle.

Instrumenter une application

Chaque application que vous voulez voir dans l'APM s'instrumente une fois, avec son service systemd. Dans Paramètres → APM → Clé API et SDK, section Instrumenter une application avec l'agent APM, choisissez le langage (Java, .NET, Node.js ou Python) pour voir ses étapes exactes.

  1. Si le langage l'exige, préparez l'application :

    • Node.js : dans le dossier de l'application, npm install @opentelemetry/api @opentelemetry/auto-instrumentations-node.

    • Python : dans l'environnement de l'application, pip install opentelemetry-distro opentelemetry-exporter-otlp && opentelemetry-bootstrap -a install.

    • Java et .NET : rien ; l'agent télécharge et vérifie ce qui est nécessaire.

  2. Sur le serveur, exécutez la commande avec le nom du service, son environnement et sa version :

sudo argunis-apm-agent --instrumentar facturacion.service --lenguaje java --env produccion --version 1.4.2
  1. En Python uniquement : ajoutez opentelemetry-instrument devant la commande de démarrage du service.

  2. Redémarrez le service quand cela vous convient (par exemple, pendant une fenêtre de maintenance) :

sudo systemctl restart facturacion.service

La commande prépare la configuration mais ne redémarre pas l'application : elle commence à envoyer après que vous l'avez redémarrée.

Pour cesser de l'instrumenter, exécutez sudo argunis-apm-agent --desinstrumentar facturacion.service et redémarrez le service.

Observer une application sans l'instrumenter (eBPF)

Si une application d'un serveur Linux ne peut pas être instrumentée (un programme sans code source, un ancien binaire ou un langage sans agent), l'agent peut l'observer depuis le système d'exploitation avec eBPF, grâce à OpenTelemetry eBPF Instrumentation (OBI). Il voit ses requêtes HTTP et gRPC et ses requêtes vers les bases de données (MySQL, PostgreSQL, SQL Server, Redis, MongoDB), Kafka et autres, sans toucher à l'application ni la redémarrer. Cette fonction est désactivée par défaut : c'est l'administrateur du serveur qui l'active.

Il vous faut un serveur Linux avec un noyau 5.8 ou supérieur (ou Red Hat Enterprise Linux 8 et ses dérivés) qui expose BTF, comme les distributions actuelles (Ubuntu 20.10+, Debian 11+, RHEL 8.2+), et l'agent APM déjà installé. Si le serveur ne remplit pas ces conditions, la commande l'indique et n'active rien.

  1. Choisissez quoi observer : les programmes qui écoutent sur certains ports ou un exécutable par son nom.

  2. Sur le serveur, exécutez l'une de ces commandes :

sudo argunis-apm-agent --ebpf activar --puertos 80,443,8080 --env produccion
sudo argunis-apm-agent --ebpf activar --proceso facturador --env produccion
  1. Attendez le message eBPF activado. En quelques minutes, l'application apparaît dans APM → Services avec le nom de son exécutable.

Pour vérifier, exécutez sudo argunis-apm-agent --ebpf estado ; pour changer ce qui est observé, relancez --ebpf activar avec d'autres ports ou un autre processus ; pour le désactiver, sudo argunis-apm-agent --ebpf desactivar.

Avec eBPF, on voit le débit, les erreurs et la latence de chaque requête et de ses appels, mais pas ce qui se passe dans le code (fonctions, exceptions détaillées) ni les requêtes HTTPS chiffrées par l'application Java elle-même. Si l'application peut être instrumentée avec son langage (voir plus haut), c'est la meilleure option. Les applications déjà instrumentées ne sont pas dupliquées : eBPF les ignore.

Ce que couvre chaque façon d'instrumenter, par langage et par version : Ce que l'APM peut superviser.

Installer l'agent sous Windows

  1. Dans la boîte de dialogue d'installation de l'agent, choisissez l'onglet Windows.

  2. Sur le serveur Windows, ouvrez PowerShell en tant qu'Administrateur.

  3. Copiez la commande de l'Étape 1 et collez-la dans PowerShell (elle tient sur une seule ligne). Elle télécharge l'installateur, vérifie son empreinte (SHA-256) et seulement ensuite l'exécute.

  4. Quand la clé est demandée, copiez celle de l'Étape 2, collez-la et appuyez sur Entrée. Rien ne s'affiche à l'écran quand vous la collez : c'est normal.

  5. Attendez le message Agente APM … instalado y corriendo.

L'installateur vérifie la signature de l'agent, installe le service Windows ArgunisApmAgent (qui démarre avec l'ordinateur) et enrôle l'agent : la clé de son certificat est générée sur le serveur, dans C:\ProgramData\ArgunisApmAgent, lisible uniquement par le système et les administrateurs. Les journaux de l'agent se trouvent dans C:\ProgramData\ArgunisApmAgent\logs.

Pour un ARGUNIS installé dans votre réseau avec un certificat propre, la commande de l'onglet Windows inclut déjà le certificat de votre autorité (-ServerCa). Utilisez-la telle quelle.

Instrumenter un service Windows ou IIS

Sous Windows, on instrumente les applications .NET (.NET Framework 4.6.2 ou supérieur et .NET 6 ou supérieur) et Java (8 ou supérieur) qui s'exécutent comme service Windows, et les sites .NET sous IIS par leur pool d'applications (app pool). L'agent télécharge et vérifie ce qui est nécessaire ; il n'y a pas à modifier l'application. Toutes les commandes s'exécutent dans PowerShell en tant qu'Administrateur.

Service Windows (utilisez le nom du service, celui qu'affiche Get-Service, et non le nom d'affichage) :

& 'C:\Program Files\ArgunisApmAgent\bin\argunis-apm-agent.ps1' -Instrumentar Facturacion -Lenguaje dotnet -Env produccion -Version 1.4.2

Pour Java, remplacez -Lenguaje dotnet par -Lenguaje java. Ensuite, quand cela vous convient, redémarrez le service :

Restart-Service -Name 'Facturacion'

IIS (.NET uniquement), avec le nom de l'app pool :

& 'C:\Program Files\ArgunisApmAgent\bin\argunis-apm-agent.ps1' -AppPool Ventas -Lenguaje dotnet -Env produccion

Recyclez ensuite l'app pool quand cela vous convient :

Restart-WebAppPool -Name 'Ventas'

La commande place les variables d'instrumentation dans le service ou l'app pool, mais ne redémarre pas l'application : elle commence à envoyer après que vous l'avez redémarrée ou recyclée. IIS peut recycler l'app pool de lui-même lors d'un changement de configuration s'il est configuré ainsi.

Les variables que le service ou l'app pool avaient déjà sont conservées. Pour cesser d'instrumenter, exécutez argunis-apm-agent.ps1 -Desinstrumentar Facturacion (service) ou argunis-apm-agent.ps1 -Desinstrumentar -AppPool Ventas (IIS), puis redémarrez ou recyclez : les variables de l'agent sont retirées et celles d'avant reviennent. Pour voir l'état de l'agent : argunis-apm-agent.ps1 -Status.

Désinstaller l'agent Windows

  1. Retirez d'abord l'instrumentation de chaque application (voir plus haut) et redémarrez-la : le programme de désinstallation ne continue pas s'il en reste une instrumentée.

  2. Dans PowerShell en tant qu'Administrateur, exécutez l'installateur avec -Desinstalar (téléchargez-le depuis l'URL affichée dans la boîte de dialogue) :

& "$env:TEMP\argunis-apm-agent-install.ps1" -Desinstalar
  1. Retirez aussi l'agent dans ARGUNIS (voir plus bas, Retirer un agent).

Ce que vous obtenez

  • L'application apparaît dans APM → Services avec le nom, l'environnement et la version indiqués, ainsi qu'avec ses traces, son débit, ses erreurs et ses latences. Voir Voir les services.

  • L'agent envoie par un canal chiffré avec un certificat propre qu'il renouvelle tout seul avant son expiration.

  • Si ARGUNIS est indisponible pendant un moment, ce qui est envoyé attend sur le disque du serveur et part au retour, sans perte.

Voir l'état

Chaque agent affiche :

Colonne

Ce qu'elle indique

État (point et texte sous le nom)

en attente d'installation (pas encore installé ; s'il indique jeton expiré, créez-en un nouveau), connecté (il a envoyé ces dernières minutes), hors ligne, installé · pas encore connecté ou révoqué

Serveur

Nom de l'hôte et système d'exploitation remontés par l'agent

Version

Version de l'agent installé. → 1.3.1 (en jaune) signale une nouvelle version ; mise à jour vers … que l'ordre a été envoyé ; échec …, retour à … (en rouge) que la nouvelle version n'a pas démarré et que l'agent a continué avec la précédente (passez la souris pour voir le motif)

Dernière connexion

Depuis combien de temps il s'est connecté ou a envoyé pour la dernière fois (passez la souris pour voir la date exacte)

Expiration du certificat

La date de validité de son certificat. L'agent le renouvelle tout seul avant cette date

Mettre à jour un agent

Quand une nouvelle version de l'agent APM est disponible, la colonne Version le signale et le bouton Mettre à jour (icône de flèches) apparaît sur la ligne. Il n'est pas nécessaire de réinstaller ni de créer de jeton : l'agent conserve son identité, son certificat, ce qu'il a en attente sur le disque, les applications instrumentées et eBPF.

  1. Sur la ligne de l'agent, appuyez sur Mettre à jour (ou sur Tout mettre à jour vers … au-dessus de la liste pour tous ceux qui ont une version antérieure).

  2. Confirmez avec Mettre à jour.

  3. En une minute au plus, l'agent prend l'ordre : il télécharge la nouvelle version, vérifie sa signature et redémarre uniquement l'agent APM (vos applications continuent de tourner). À la fin, la colonne Version affiche la nouvelle.

Si la nouvelle version ne démarre pas, l'agent revient tout seul à la précédente en quelques minutes et la ligne l'affiche en rouge. Les données ne sont pas perdues : elles attendent sur le disque du serveur pendant le redémarrage de l'agent.

L'administrateur du serveur peut aussi le mettre à jour :

sudo argunis-apm-agent --actualizar
& 'C:\Program Files\ArgunisApmAgent\bin\argunis-apm-agent.ps1' -Actualizar

Les agents d'une version antérieure à la 1.3.0 ne se mettent pas à jour depuis le web (l'avertissement de nouvelle version apparaît, mais sans bouton) : réinstallez-les une fois avec un nouveau jeton (voir plus bas).

Créer un nouveau jeton pour un agent

Utilisez-le si le jeton a expiré avant l'installation ou si vous devez réinstaller l'agent.

  1. Sur la ligne de l'agent, appuyez sur l'icône de clé (Nouveau jeton d'installation).

  2. Confirmez avec Créer le jeton.

  3. Copiez la nouvelle commande d'installation et appuyez sur Terminé.

  4. Exécutez-la sur le serveur comme dans Installer l'agent sur le serveur ou Installer l'agent sous Windows. Les applications déjà instrumentées ne sont pas touchées.

Si l'agent était déjà installé, son certificat cesse immédiatement d'être valable et vous devrez le réinstaller avec le nouveau jeton. S'il ne l'était pas, les jetons précédents non utilisés cessent de fonctionner.

Révoquer un agent

  1. Sur la ligne de l'agent, appuyez sur l'icône d'arrêt (Révoquer).

  2. Confirmez avec Révoquer.

Son certificat cesse immédiatement d'être valable et ARGUNIS coupe sa connexion. L'agent reste dans la liste comme révoqué ; pour réutiliser ce serveur, retirez-le et créez un nouvel agent.

Retirer un agent

  1. Sur la ligne de l'agent, appuyez sur l'icône de corbeille (Retirer).

  2. Confirmez avec Retirer.

Si l'agent était en vigueur, son certificat cesse immédiatement d'être valable et ARGUNIS coupe sa connexion. Désinstallez-le ensuite du serveur.

Les données déjà envoyées par l'agent restent dans l'APM jusqu'à leur expiration selon la rétention.

Voir aussi

Rechercher dans Argunis Monitoring

Saisissez au moins 2 caractères pour rechercher dans Argunis Monitoring.

↑↓ naviguer · Enter ouvrir · Esc fermer