• Pré-requis
• Étapes d’installation
• Options
  • Déploiement et identifiant d’application
    • Plusieurs JVMs pour une application
    • Plusieurs applications pour une JVM
  • JMX
  • Application Java / JVM
• Conteneurs et serveurs d’applications
  • Tomcat
  • JBoss et Wildfly
    • JBoss 4, JBoss 5 (EAP et versions open-source)
    • JBoss AS 7 - JBoss EAP 6, 7 - Wildfly 8, 9, 10
  • Glassfish
  • WebLogic
    • Websphere
    • JOnAS 5.1
  • JOnAS 5.2
    • Liferay
• Mise à jour de l’agent
  • Procédure
  • Avertissements
  • Compatibilité
  • Téléchargement
  • Contrainte de nommage
  • Utilisation d’un lien symbolique

Pré-requis

La sonde est compatible avec la version java 8 ou supérieur et jusqu’à java 17.

Étapes d’installation

• Si ce n’est déjà fait, téléchargez la sonde depuis l’écran de création/paramétrage de votre application dans l’interface Nudge APM

• Créez un répertoire sur le serveur qui héberge votre application et extrayez le contenu du ZIP à l’intérieur.

  • les fichiers nudge-x.y.z.jar et nudge.properties doivent rester dans le même répertoire.
  • l’agent a une contrainte de nommage du fichier : vous devez soit conservez le nom original nudge-x.y.z.jar soit le renommez le en nudge.jar mais pas autre chose.

• Ajoutez -javaagent:/path/to/nudge-x.y.z.jar à la ligne de commande de la JVM. (plus de détails ci-dessous)

• Redémarrez votre application.

Suivant votre application et éventuellement le conteneur JEE que vous utilisez, la meilleure façon de d’ajouter l’argument -javaagent à la JVM peut varier.
Voici des exemples de consignes de paramétrages pour les conteneurs les plus courants :

• Tomcat
• JBoss & Wildfly
• Glassfish
• Weblogic
• Websphere
• JOnAS 5.1
• JOnAS 5.2
• Liferay

Options

La configuration de la sonde Java est effectuée via :

• un fichier nudge.properties, situé dans le même répertoire que l’agent JVM

• les propriétés système de la JVM préfixées par nudge. : -Dnudge.<nom parametre>=<valeur parametre>

  Par exemple, pour configurer le niveau de log log_level en FINE, il faudra ajouter le paramètre suivant : -Dnudge.log_level=FINE.

Le fichier nudge.properties peut devenir optionnel en fournissant les paramètres via les proprtiétés système de la JVM.

Consultez la liste des paramètres pour plus de détails.

Déploiement et identifiant d’application

Nudge APM récolte les métriques de votre application et de son environnement à l’aide d’un agent Nudge. Cet agent est à considérer en fonction de façon votre application est construite.

Les métriques sont envoyées avec le protocole encrypté HTTPS (par défaut) vers le Controleur Nudge qui s’occupe de stocker et analyser ces données.

Le paramètre app_id est le seul paramètre obligatoire et le plus important. Sa valeur définie le lien entre la JVM et l’application Nudge. Une valeur adéquate est fournis automatiquement dans le fichier nudge.properties disponible dans le fichier téléchargé. Ainsi, aucune action n’est nécessaire avec votre application exécutée sur une seule JVM.

Plusieurs JVMs pour une application

Vous pourriez avoir un groupe (cluster) de serveurs dédiés à une unique application. Dans ce cas, il faut alors configurer le paramètre app_id de toutes les JVMs de sorte qu’ils aient la même valeur. Les métriques vont alors être aggrégés dans la même application Nudge. Toutefois, Nudge APM est toujours capable de différencier les serveurs/JVMs concernant les métriques locales aux serveurs.

Plusieurs applications pour une JVM

Un agent Nudge est lié à la JVM. Mais il est possible de déployer plusieurs archives (avec des fichiers WAR ou EAR par exemple) sur une unique JVM d’un conteneur ou serveur d’application. Dans ce cas, il n’y a qu’un seul agent et une seule valeur app_id. Ainsi, toutes les métriques des archives déployées sont aggrégées au sein d’une unique application Nudge.

Il existe néanmoins des solutions évoquées ici pour distinguer les transactions des archives.

JMX

La configuration de l’observation des attributs JMX sur Nudge-APM se fait grâce aux propriétés de la sonde via les attributs activate_jmx et mbeans_monitored.

activate_jmx=true
mbeans_monitored=<mbean1>;<mbean2>;...

Pour obtenir la syntaxe exacte de chaque MBean, nous recommandons d’utiliser l’outil JConsole fourni avec le JDK

Notez que certains serveurs d’application (par exemple Tomcat 5.5) ne publient pas systématiquement dans l’arborescence JMX de la JVM.

Si vous ne pouvez pas obtenir les informations via JConsole, nous vous invitons à vous référer à la documentation de votre serveur d’application.

Par exemple, pour suivre le nombre de sessions actives sur l’application servlets-examples d’un serveur Tomcat :

activate_jmx=true
mbeans_monitored=Catalina:type=Manager,path=/servlets-examples,host=localhost

Après redémarrage de la JVM, vous pouvez ensuite lister l’ensemble des attributs (activeSessions) via l’interface:

Application Java / JVM

À utiliser si vous utilisez un jar exécutable ou une application Spring Boot.

Il suffit d’ajouter l’argument -javaagent aux paramètres de la JVM avec le chemin complet vers le fichier .jar de l’agent.

java -javaagent:c:/full/path/to/nudge-x.y.z.jar -jar myapp.jar

Conteneurs et serveurs d’applications

Tomcat

Ajouter le paramètre -javaagent aux paramètres de la JVM

Sous Unix/Linux, éditer ou créer bin\setenv.sh

CATALINA_OPTS="$CATALINA_OPTS -javaagent:/full/path/to/nudge-x.y.z.jar"

Sous Windows, éditer ou créer bin\setenv.bat

set "CATALINA_OPTS=%CATALINA_OPTS% -javaagent:c:/full/path/to/nudge-x.y.z.jar"

Si vous utilisez Tomcat en tant que service Windows, le fichier setenv.bat est ignoré.
Il faut alors utiliser l’outil tomcat7w.exe via la ligne de commande (ici pour un Tomcat7 dont le service est nommé “tomcat7service).

bin/tomcat7w.exe //ES//tomcat7service

Dans l’onglet Java, il faut rajouter la ligne suivante dans le champ Java Options

-javaagent:c:/full/path/to/nudge-x.y.z.jar

Vous trouverez plus d’informations sur la configuration de Tomcat en tant que service Windows dans la documentation officielle.

JBoss et Wildfly

La configuration diffère légèrement en fonction de la version Jboss/Wildfly utilisée. Nous vous recommandons de vérifier votre version avant de modifier la configuration.

Listing des versions de RedHat JBoss EAP qui sont construites sur les versions open-source.

JBoss 4, JBoss 5 (EAP et versions open-source)

Rajouter les lignes suivantes à la fin du fichier :

Sous Unix/Linux, éditier le fichier bin/run.conf

JAVA_OPTS="$JAVA_OPTS -javaagent:/full/path/to/nudge-x.y.z.jar -Djboss.platform.mbeanserver"

Sous Windows, éditer le fichier bin\run.conf.bat

set "JAVA_OPTS=%JAVA_OPTS% -javaagent:c:/full/path/to/nudge-x.y.z.jar -Djboss.platform.mbeanserver"

JBoss AS 7 - JBoss EAP 6, 7 - Wildfly 8, 9, 10

Lorsque le paramètre jboss.modules.system.pkgs serait déjà utilisé, il faut rajouter ,org.nudge à la valeur existante (les valeurs sont séparés par une virgule).

Standalone

Sous Unix/Linux, éditer le fichier bin/standalone.conf

JAVA_OPTS="$JAVA_OPTS -Djboss.modules.system.pkgs=org.nudge"
JAVA_OPTS="$JAVA_OPTS -javaagent:/full/path/to/nudge-x.y.z.jar"

Sous Windows, éditer le fichier bin\standalone.conf.bat

set "JAVA_OPTS=%JAVA_OPTS% -Djboss.modules.system.pkgs=org.nudge"
set "JAVA_OPTS=%JAVA_OPTS% -javaagent:c:/full/path/to/nudge-x.y.z.jar"

Domaine

Il faut utiliser l’outil en ligne de commande bin/jboss-cli.sh pour Unix/Linux ou bin\jboss-cli.bat et exécuter la commande connect pour se connecter au cluster.

Lister les serveurs existants avec la commande ci-dessous (en supposant que le noeud maitre soit master).

/host=master:read-children-names(child-type=server)

Exemple de résultat avec 3 noeuds :

{
    "outcome" => "success",
    "result" => [
        "server-one",
        "server-three",
        "server-two"
    ]
}

Ensuite, pour chaque serveur (ici server-one), exécuter les deux commandes ci-dessous. Nous recommandons d’utiliser une copie distincte de nudge.jar pour chaque noeud.

/host=master/server-config=server-one/system-property=jboss.modules.system.pkgs:add(value="org.jboss.byteman,org.nudge")

/host=master/server-config=server-one/jvm=default:add(java-agent=/path/to/nudge.jar)

Il faut ensuite redémarrer le serveur.

Glassfish

La configuration se fait en deux étapes :

• ajout d’un paramètre de JVM, via la console d’administration (ou avec l’outil asadmin)

  

  • cliquer sur “Add JVM Option”
  • ajouter la valeur suivante dans le champ de saisie

    -javaagent:c:/full/path/to/nudge-x.y.z.jar
    

  • cliquer sur le bouton Save en haut à droite

• modification du fichier osgi.properties

  • rajouter la valeur org.nudge.* au paramètre org.osgi.framework.bootdelegation, les valeurs des paramètres sont séparés par des virgules.

WebLogic

Editer le fichier startWebLogic.sh (startWebLogic.bat sous Windows) dans le répertoire bin du domaine pour enrichir la variable d’environnement JAVA_OPTIONS :

Sous Unix/Linux :

export JAVA_OPTIONS="$JAVA_OPTIONS -javaagent:/full/path/to/nudge-x.y.z.jar

Sous Windows :

set "JAVA_OPTIONS=%JAVA_OPTIONS% -javaagent:c:/full/path/to/nudge-x.y.z.jar"

Java5 ou sondes < 3.0.10 uniquement

La configuration par défaut Weblogic ne permet pas de communiquer avec un site utilisant un certificat SSL/TLS wildcard comme *.nudge-apm.com. Il faudra donc configurer le serveur:

• se connecter à la console d’administration
• aller dans Environment
• sélectionner le serveur concerné
• aller dans l’onglet SSL
• cliquer sur Advanced
• choisir Hostname Verification = Custom Hostname Verifier
• saisir Custom Hostname Verifier = weblogic.security.utils.SSLWLSWildcardHostnameVerifier

Websphere

Procédure pour Websphere 9, sur les autres versions la navigation et/ou le nommage des éléments peut légèrement varier mais la procédure reste identique.

• se connecter à la console d’administration
• sélectionner dans le menu Servers > Server Type > Websphere Application Server
• sélectionner le serveur dans la liste
• dans l’onglet Configuration, cliquer sur Java and Process Management, puis sur Process Definition.
• cliquer sur Java Virtual Machine
• dans le champ Generic JVM arguments, rajouter le paramètre -javaagent
  • Unix/Linux : -javaagent:/full/path/to/nudge-x.y.z.jar
  • Windows : -javaagent:c:/full/path/to/nudge-x.y.z.jar

JOnAS 5.1

Extraire du fichier JAR $JONAS_ROOT/lib/bootstrap/felix-launcher.jar le fichier org/ow2/jonas/launcher/felix/default-config.properties.

Copier et renommer ce fichier en tant que $JONAS_BASE/conf/felix-config.properties puis éditer ce fichier felix-config.properties et renseigner les propriétés suivantes :

org.osgi.framework.bootdelegation= (...) \
    org.nudge, \
    org.nudge.*

org.osgi.framework.bundle.parent=app

Ajouter les valeurs suivantes à la propriété excluded_classpath du fichier nudge.properties :

excluded_classpath=org.ow2.carol.jndi,org.ow2.util,org.ow2.jonas.ee.jdbc,$Proxy

Modifier le fichier setenv.sh pour ajouter les paramètres suivants :

JAVA_OPTS=$JAVA_OPTS -Djonas.felix.configuration.file=$JONAS_BASE/conf/felix-config.properties`
JAVA_OPTS=$JAVA_OPTS -javaagent:/path/to/nudge-x.y.z.jar`

JOnAS 5.2

Editer le fichier gateway.properties et renseigner les propriétés suivantes :

org.osgi.framework.bootdelegation=${bootdelegation-packages},org.nudge.*
org.osgi.framework.bundle.parent=app

Ajouter les valeurs suivantes à la propriété excluded_classpath du fichier nudge.properties :

excluded_classpath=org.ow2.carol.jndi,org.ow2.util,org.ow2.jonas.ee.jdbc,$Proxy

Modifier le fichier setenv.sh pour ajouter le paramètre -javaagent :

JAVA_OPTS=$JAVA_OPTS -javaagent:/path/to/nudge-x.y.z.jar

Liferay

Configuration du bundle Wildfly/Tomcat

Voir sections correspondantes Tomcat et Wildfly.

Configuration OSGI (Liferay 7.x)

Extraire le fichierportal.properties de l’archive portal-impl.jar et ouvrir ce fichier avec un éditeur texte.

Copier la propriété module.framework.properties.org.osgi.framework.bootdelegation dans le fichier portal-ext.properties.

Ajouter org.nudge.* à la valeur module.framework.properties.org.osgi.framework.bootdelegation copiée.

module.framework.properties.org.osgi.framework.bootdelegation=\
	<... other lines ommited for clarity ..>
	sun.*,\
	org.nudge.*

Mise à jour de l’agent

Les nouvelles versions de l’agent Java apportent un lot d’améliorations (et quelquesfois de corrections). Ainsi, il est important de considérer sa mise à jour.

Procédure

La procédure de mise à jour dépend de la façon dont l’agent a été installé. Si la procédure d’installation de notre documentation a été suivie, la procédure de mise à jour devrait être similaire à ceci :

1. Télécharger la dernière version de l’agent (voir plus d’information ici à propos des possibilités de téléchargement).

2. [ Optionel ] Renommer le fichier de l’agent en rapport à ses contraintes de nommage. Il est possible d’utiliser un lien symbolique.

3. [ Optionel ] Déplacer le fichier de la nouvelle sonde dans le répertoire de l’agent actuel (si il n’est pas déjà dans ce répertoire). Si vous utilisez un lien symbolique, vous devrez plutôt mettre à jour ce dernier (avec la commande ln -s par exemple).

4. [ Optionel ] Vous pourriez éventuellement mettre à jour la configuration de l’agent. Les nouvelles options seraient ainsi disponible dès le redémarrage de la JVM avec la nouvelle version de la sonde. Une nouvelle version de l’agent pourrait accepter de nouvelles options.

5. [ Optionel ] Sauvegarder l’ancien agent.

6. [ Optionel ] Éventuellement modifier l’argument JVM javaagent. Cela n’est pas nécessaire si vous utilisez le nommage nudge.jar ou un lien symbolique. Sinon, veuillez suivre les instructions d’installation en rapport à votre conteneur afin de mettre à jour l’argument javaagent.

7. Redémarrez la JVM (ou serveur d’application); le nouvel agent est opérationnel !

Avertissements

Vous êtes informé de l’ancienneté de l’agent connecté à votre application depuis l’écran de la liste des applications. Un point d’exclamation apparaît dès lors que l’agent peut être mise à jour. Si la version majeure de l’agent est antérieure à la version majeure de la dernière version, alors le point d’exclamation est mis en évidence avec un fond rouge.

Compatibilité

La communication avec le portail sera toujours effective et fonctionnelle avec votre version de l’agent, même si celle-ci n’est pas la dernière version disponible.

Téléchargement

La dernière version de l’agent peut être téléchargée avec ce lien en étant connecté sur le portail support.

Contrainte de nommage

Le classpath que vous paramétrez pour votre application n’a pas besoin de considérer l’existence de l’agent. Il s’ajoute automatiquement lui-même dans ce classpath lors de l’initialisation. Toutefois, pour qu’il fonctionne, l’agent doit posséder un nom de fichier particulier. Ce nom de fichier doit être au choix :

• nudge-x.y.z.jar où x.y.z est l’identifiant de version de l’agent. L’identifiant de version du nom de fichier doit être exactement celui de la version de l’agent concerné. De plus, avec cette convention, l’argument JVM javaagent doit être changé à chaque mise à jour de la sonde.
• ou nudge.jar. Ce nom peut être utilisé avec toutes les versions de l’agent. Avec ce nom de fichier, une mise à jour de la sonde est facilitée puisqu’il n’y a plus besoin de connaître la version concernée. Vous n’avez pas besoin de changer d’option de JVM si la ligne de commande de la JVM fait déjà référence au nom de fichier nudge.jar.

Nous ne pouvons pas contourner cette limitation à propos du nommage de fichier (du moins sans enrichir le classpath de la JVM). En effet, l’agent java doit être inclus dans le classpath final et le nom de fichier doit être connu pour ce besoin. L’inclusion de l’agent dans le classpath est effectué automatiquement à l’aide du MANIFEST de l’agent. Pour plus d’information sur le sujet, veuillez vous référer à l’attribut Boot-Class-Path de la documentation du package java.lang.instrument.

Utilisation d’un lien symbolique

Vous pouvez utiliser un lien symbolique (avec un OS compatible UNIX) afin de configurer le chemin de l’agent pour la JVM. Dans ce cas, la destination du lien symbolique doit se conformer aux contraintes de nommage du fichier.

Vous pourriez aussi utiliser la commande readlink. Voici un exemple de configuration de la JVM avec Tomcat et un lien symbolique /usr/local/nudge/nudge.jar :

export CATALINA_OPTS="$CATALINA_OPTS -javaagent:$(readlink -f /usr/local/nudge/nudge.jar)"