Deploy germainAPM Engine
Downloads
Prerequisites
Ports:
Germain APM Server (Often port 80, or 8080)
If using ActiveMQ (Often Port: 61616)
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 |
---|
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: |
---|
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:
1
$ 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:
1
2
3
4
5
6
7
8
9
10
11
12
[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:
1
$ 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:
1
$ 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