Deploy germainAPM Engine

Downloads

APM 8.6.11 - Windows - Linux
APM 8.6.9 - Windows - Linux
APM 8.6.8 - Windows - Linux
APM 8.6.7 - Windows - Linux
APM 8.6.6 - Windows - Linux
APM 8.6.2 - Windows - Linux

Prerequisites

Ports:
- Germain APM Server (Often port 80, or 8080)
- If using ActiveMQ (Often Port: 61616)

HowTo: Test Port Connectivity Using Telnet

HowTo: Test Port Connectivity Using Telnet

On the Command Prompt, use telnet to verify you can access the servers you need to reach

Usage: telnet <germainAPM server> 80

JRE 8, JDK 8, or OpenJDK8+

HowTo: Validating the correct java installation responds

HowTo: Validating the correct java installation responds

On your command line use java -version

Note: If the wrong version for java comes up, you likely have multiple version of java installed. Uninstall the unneeded versions, or check your path and remove the one you do not wish to be invoked.

JAVA_HOME is set

HowTo: Check the JAVA_HOME Variable:

HowTo: Check the JAVA_HOME Variable:

You can echo JAVA_HOME from your command line
- Windows: echo %JAVA_HOME%
- Bash: echo $JAVA_HOME
- PowerShell: echo $env:JAVA_HOME

Note: If the value is incorrect: Follow steps for setting a system environment variable for your OS.

Initial Configuration

Create a new directory for the engines
- Example: D:\GermainAPM\engines or /germainapm/engines
  - (we'll refer to this as $ENGINE_HOME)
  - Setting this as an environment variable can simplify later steps
Extract engine distribution into $ENGINE_HOME
- (e.g. GermainAPMEngine-8.5.x.zip)
Copy JDBC jars to $ENGINE_HOME/lib/ for the databases that you are planning to monitor:
- Examples. These will differ with your database version
  - MySQL: mysql-connector-java-5.1.20.jar
  - Oracle: ojdbc6.jar
Update initial configuration in $ENGINE_HOME/config/germain-bootstrap.properties:
- germain.bootstrap.configService - Set to the URL of your Germain APM server
- germain.bootstrap.configUser - Specify the Germain APM user you are planning to use to connect (by default, admin)
- germain.bootstrap.configPassword - Specify the corresponding password
- germain.bootstrap.node - 2 options here:
  - A) If you leave this value empty, the engine will automatically register a new node configuration on the Germain APM server (preferred)
  - B) Specify the hostname of an existing node under germain.apm.monitoringNodes
    - Screenshot of this setting located in Workspace
- germain.activemq.url - update hostname:port to the location where ActiveMQ service is running (usually same hostname as Germain APM Server)

Running the Germain APM Engines as a foreground process

Windows

Go to $ENGINE_HOME\bin
Edit startEngine.bat and validate/set JVM memory settings.
- Screenshot of settings in script:

Open a Command Window.
Navigate to $ENGINE_HOME
Run .\bin\startEngine.bat
- Screenshot of Engine Running:

Linux

Navigate to $ENGINE_HOME
Use vim ./bin/startEngine.sh and set JVM memory settings
As root run ./bin/startEngine.sh
- Screenshot of starting the script:

Running the Germain APM Engines as a service

Windows

Edit $ENGINE_HOME\bin\GermainEngineStandalone.xml and set the JVM memory settings
- XML contexts:
  - 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17<service> <id>GermainEngineStandalone</id> <name>Germain APM Engine Standlone</name> <description>This runs a Germain APM Engine.</description> <env name="APM_HOME" value="%BASE%\.."/> <logpath>%BASE%\..\logs</logpath> <logmode>roll</logmode> <workingdirectory>%BASE%\..</workingdirectory> <executable>java</executable> <argument>-Xms256m</argument> <argument>-Xmx1024m</argument> <argument>-XX:-CreateMinidumpOnCrash</argument> <argument>-XX:+CrashOnOutOfMemoryError</argument> <argument>-Dgermain.engine=standalone</argument> <argument>-jar</argument> <argument>bin/apm-engine-spring.jar</argument> </service>

Open and Administrator Command Prompt
Navigate to the $ENGINE_HOME\bin\WinSW directory
Run the appropriate .bat file for your hosts systems .NET version( set-dotnet-2.bat, set-dotnet-4.bat, or set-dotnet-461.bat )
Go up one directory cd ..
Run the command GermainEngineStandalone.exe install:
- Screenshot of Service Install:

Check the service list to validate that the service was created:
- Screenshot of service in ‘Windows Services’:

Linux Distributions using System V

To install the Germain APM engines as a service, create a symlink to the following executable:

$ sudo ln -s $ENGINE_HOME/apm-engine-spring.jar /etc/init.d/germain-engine

To control the new service, the following commands can be used:

1
2
3

  $ sudo service germain-engine start
  $ sudo service germain-engine stop
  $ sudo service germain-engine restart

Linux Distributions using systemd

To install the Germain APM engines as a service, adjust the provided service file (germain-engine.service) to match the location of the $ENGINE_HOME directory on your system:

  [Unit]
  Description=germain-engine
  After=network-online.target
  Wants=network-online.target

  [Service]
  User=root
  ExecStart=/opt/germainapm/apm-engine-spring.jar
  SuccessExitStatus=143

  [Install]
  WantedBy=multi-user.target

Then, copy the file into your service directory:

$ cp $ENGINE_HOME/bin/germain-engine.service /etc/systemd/system/

To control the new service, the following commands can be used:

1
2
3

  $ sudo service germain-engine start
  $ sudo service germain-engine stop
  $ sudo service germain-engine restart

To automatically start the server on restart, run the following command:

$ systemctl enable germain-engine.service

Troubleshooting

Check the $ENGINE_HOME\log directory validate that the engines have started correctly. You can also check for the "java" processes activity.
Wait for monitored data to appear on the germain APM Dashboard (use the "Drill Through" button on the O.S. Metrics portlets: Server Availability, CORE, Mem... or DB Availability; these come in faster)
Troubleshoot
- Review the log files' contents ($ENGINE_HOME/logs)
- If data doesn't get through but the engine logs don't show problems, check the Tomcat logs ($CATALINA_HOME/logs) and germain APM service logs ($SERVICE_HOME/var/logs)
- If the screen above doesn’t show up, please zip entire folder ($ENGINE_HOME/logs) and send it to us. Either email the person you are working with or contact through ticket or email: https://germainapm.atlassian.net/wiki/spaces/germainAPM/pages/9798052/Support

Further configuration/tuning of germain APM engine

Don't use Names longer than 20 chars; some DB columns are limited to that size but the Config dashboard's UI doesn't check this.
Make sure each engine is set up with the recommended default parameters:
-server
-Xms256m (you may need to adjust Xms based on the number of components running inside the engine)
-Xmx1024m (you may need to adjust Xmx based on the number of components running inside the engine)
-XX:+CrashOnOutOfMemoryError means that the JVM will crash / exit when there is not enough memory to continue; otherwise the JVM will continue running code in a potential faulty state.
-XX:-HeapDumpOnOutOfMemory means that the JVM will not create a heap dump when it has an out of memory crash. These are large and unnecessary as the logs will have enough data to determine the cause.
-XX:-CreateMinidumpOnCrash means that the JVM will not create a Minidump when it crashes. These are unnecessary as the logs will have enough data to determine the cause.
Screenshot of these settings located in Workspace