Why: The startup log is created when the agent loads into the Java application. If it doesn't exist, the agent was never loaded.

What to check: Look for a file named apminsight_startup_<timestamp>_<PID>.log in the agent directory.

How to check:

🐧 Linux

⊞ Windows

🐧 Linux

ls -lt apminsight_startup_*.log

⊞ Windows

Get-ChildItem "apminsight_startup_*.log" | Sort-Object LastWriteTime -Descending

Expected result: One or more startup log files should exist. Check the latest one (most recent timestamp).

Why: Even if the startup log exists, the agent may have failed during initialization.

What to check: Open the latest apminsight_startup_*.log and look for the success message.

How to check:

🐧 Linux

⊞ Windows

🐧 Linux

grep -i "hooked up with JVM" apminsight_startup_*.log

⊞ Windows

Select-String -Path "apminsight_startup_*.log" -Pattern "hooked up with JVM"

Expected result:

[INFO]: APM Insight javaagent v7.x.x.x successfully hooked up with JVM (PID:xxxxx)

Why: The agent only loads when the JVM starts. A "hot reload" or "redeploy" through the application server admin console does NOT reload the agent.

What to check: Confirm the customer performed a full application server restart (stop + start) after adding the -javaagent argument.

How to verify:

Check the timestamp on the latest apminsight_startup_*.log — it should be after the most recent restart time.

🐧 Linux

⊞ Windows

🐧 Linux

ls -lt apminsight_startup_*.log | head -1

⊞ Windows

Get-ChildItem "apminsight_startup_*.log" | Sort-Object LastWriteTime -Descending | Select-Object -First 1

Why: The current agent (v7.x) requires Java 8 or above. Older Java versions need a legacy agent.

What to check: The Java version of the application (not just what's installed on the system — the application may use a different Java).

How to check (from startup log — easiest method):

🐧 Linux

⊞ Windows

🐧 Linux

grep -i "java version\|java.version\|JVM Version" apminsight_startup_*.log

⊞ Windows

Select-String -Path "apminsight_startup_*.log" -Pattern "java version|java.version|JVM Version"

Alternative — check from command line:

java -version

Note: The java -version command shows the system default Java. The application may use a different Java version. Always prefer checking from the startup log.

Supported JVM list: JVM / JDK Supported

Why: The agent needs four key settings to connect to Applications Manager. If any of them are wrong, empty, or missing, the agent cannot onboard.

What to check: Open apminsight.conf in the agent directory and verify these four values:

How to check (quick view):

🐧 Linux

⊞ Windows

🐧 Linux

grep -E "^(license\.key|apm\.host|application\.name|agent\.server\.port)" apminsight.conf

⊞ Windows

Select-String -Path "apminsight.conf" -Pattern "^(license\.key|apm\.host|application\.name|agent\.server\.port)"

Why: From agent v7.x onwards, the agent creates an instance subdirectory named <application.name>_<port> (e.g., MyApp_8080) inside the agent directory. All runtime logs (apminsight_agent_*.log) and instance-specific data are maintained in this folder. If this folder doesn't exist, the agent never completed registration.

What to check: Look for a subdirectory matching the pattern <app-name>_<port> (or <app-name>:<port>) inside the agent directory.

How to check:

🐧 Linux

⊞ Windows

🐧 Linux

ls -ld */

⊞ Windows

Get-ChildItem -Directory

Expected result: A folder named like MyApp_8080 (matching the application.name and agent.server.port from apminsight.conf). Inside it, you should find apminsight_agent_*.log files.

Why: The agent needs to communicate with Applications Manager over the network. If there's a firewall, proxy, or incorrect URL, the agent cannot send data.

What to check: From the customer's application server machine (where the agent is installed), test if Applications Manager is reachable.

How to check:

🐧 Linux

⊞ Windows

🐧 Linux

curl -ks <apm.host value from conf>/index.do | grep -i 'Applications Manager'

⊞ Windows

add-type 'using System.Net;using System.Security.Cryptography.X509Certificates;public class TrustAllCertsPolicy : ICertificatePolicy {public bool CheckValidationResult(ServicePoint a,X509Certificate b,WebRequest c,int d){return true;}}';[System.Net.ServicePointManager]::CertificatePolicy=New-Object TrustAllCertsPolicy;(Invoke-WebRequest -Uri '<apm.host value from conf>/index.do').Content -split "`n" | Where-Object {$_ -match 'Applications Manager'}

Note: Replace <apm.host value from conf> with the actual URL from apminsight.conf (e.g., https://appmanager.example.com:8443). Use https:// if SSL is enabled, otherwise http://.

Also check the startup log for connection errors:

🐧 Linux

⊞ Windows

🐧 Linux

grep -i "Connection.*failed\|SSL handshake\|endpoints failed" apminsight_startup_*.log

⊞ Windows

Select-String -Path "apminsight_startup_*.log" -Pattern "Connection.*failed|SSL handshake|endpoints failed"

Why: When the agent connects to Applications Manager, the server sends back a response code. This code tells us exactly what's happening.

How to check:

🐧 Linux

⊞ Windows

🐧 Linux

grep -i "Response Code" apminsight_startup_*.log

⊞ Windows

Select-String -Path "apminsight_startup_*.log" -Pattern "Response Code"

What the response codes mean and what to do:

For detailed response code information, see Section 3.

Why: Running multiple bytecode instrumentation agents (like Dynatrace, New Relic, AppDynamics, Glowroot) alongside APM Insight is NOT supported and can cause JVM instability, application crashes, WAR deployment failures, excessive memory usage, and unpredictable monitoring behavior.

What to check: See if other monitoring agent arguments are present in the Java process.

How to check (from startup log — easiest):

🐧 Linux

⊞ Windows

🐧 Linux

grep -i "Java Arguments" apminsight_startup_*.log | grep -iE "dynatrace|appdynamics|glowroot|newrelic|agentpath|elastic.*apm"

⊞ Windows

Select-String -Path "apminsight_startup_*.log" -Pattern "Java Arguments" | Select-String -Pattern "dynatrace|appdynamics|glowroot|newrelic|agentpath|elastic.*apm"

Alternative — check the running process directly:

🐧 Linux

⊞ Windows

🐧 Linux

ps -ef | grep java | grep -iE "javaagent|agentpath"

⊞ Windows

Get-WmiObject Win32_Process -Filter "name='java.exe'" | Select-Object CommandLine | Format-List

How to identify each competitor agent:

Important: Dynatrace, New Relic, AppDynamics, and Glowroot all use bytecode instrumentation — the same technique as APM Insight. Running two bytecode agents simultaneously causes class transformation conflicts leading to: JVM crashes (hs_err_pid*.log), WAR deployment hangs, intermittent 500 errors, and excessive memory consumption. This is confirmed by all major APM vendors' documentation — co-existence is NOT supported by any of them.

Known symptoms when multiple agents are loaded:

• ClassNotFoundException or NoClassDefFoundError during application startup
• JVM crashes with hs_err_pid*.log files generated
• Application server hangs during WAR/EAR deployment
• Intermittent HTTP 500 errors under load
• Significant increase in JVM memory usage

Why: The agent needs to write log files and temporary data into its directory. If the user running the application doesn't have write access to the agent folder, the agent will fail silently.

What to check:

1. Find out which user account is running the application.
2. Check if that user has read/write permission on the agent directory.

How to check:

🐧 Linux

⊞ Windows

🐧 Linux

Find the application user:

ps -ef | grep java

(The first column shows the username running the process.)

Check agent folder ownership:

ls -la <agent_directory>

Fix permissions if needed:

chown -R <app_user>:<app_group> <agent_directory>

⊞ Windows

Find the application user:

Open Task Manager → Details tab → find the java.exe process → note the "User name" column.

Check agent folder permissions:

Right-click the agent folder → Properties → Security tab → check if that user has Read & Write access.

Fix permissions if needed:

Right-click agent folder → Properties → Security → Edit → Add the user → Allow Read & Write.

This is one of the most common onboarding failures!

Why: If the customer runs multiple Java applications (e.g., microservices) on the same server and they all point to the same agent folder, the configuration file gets corrupted because multiple processes try to write to it at the same time.

Signs of this issue:

• The apminsight.conf file is completely empty or has garbled/truncated content
• Multiple applications show with "license.key is invalid" errors
• Different applications appear as the same instance in Applications Manager
• Port shown in AppManager doesn't match what the customer configured

How to verify:

Ask the customer: "Are you running multiple Java applications on this server?" If yes, check if they all reference the same -javaagent path.

🐧 Linux

⊞ Windows

🐧 Linux

ps -ef | grep java | grep -o "\-javaagent:[^ ]*\|\-Dapminsight.home=[^ ]*"

⊞ Windows

Get-WmiObject Win32_Process -Filter "name='java.exe'" | Select-Object CommandLine | Format-List

Look for multiple processes using the same agent JAR path without a -Dapminsight.home argument.

-javaagent:/opt/apminsight-agent/apminsight-javaagent.jar
-Dapminsight.home=/opt/apminsight-agent/<app_name>
-Dapminsight.application.name=<app_name>
-Dapminsight.agent.server.port=<app_port>
-Dapminsight.license.key=<license_key>
-Dapminsight.apm.host=<appmanager_url>