The script needs bash plus the usual userland (ps, find, grep, sed, stat). Whether the image has them decides the approach, so check the image rather than assuming.

Do not install bash into a production container to work around this. It mutates a running workload to obtain a read-only diagnostic, and the change disappears on the next restart. Both options below get the same answer without touching the container.

Option 1: run the script on the Linux container host. The host's process list already contains the containerised JVM with its full -javaagent argument, and the container's files are reachable at /proc/<pid>/root/<path-inside-container>.

sudo ps -eo pid,args | grep apminsight-javaagent

sudo ls /proc/<pid>/root/<agent_dir>/

sudo ./apminsight_onboarding_check_v2.sh /proc/<pid>/root/<agent_dir>

Needs a Linux container host. On Docker Desktop for Mac or Windows the containers run inside a VM, so the laptop's process table and /proc do not contain them — use Option 2 there.

Option 2: copy the evidence out and read it. Three files answer most onboarding questions, and none needs a shell inside the container. Section 5 shows what each one looks like.

docker cp <container>:<agent_dir>/apminsight.conf .

docker cp <container>:<agent_dir>/<AppName>_<Port>/ ./instance/

You can run the script against the copied directory. The on-disk checks — configuration, instance folders, collector response — are all valid. The process-based rows (attachment, permissions, conflicts) will find nothing, because the JVM is not on this host. Read those as not measured, not as failures.

FSO in containers: the Auto Profiler is a host service that instruments processes it detects on that host. Whether it reaches a JVM inside a container depends on the runtime and the deployment, and the script cannot determine it. Confirm the supported approach with the APM Insight team before concluding the profiler is faulty — for containers the agent is commonly baked into the image and added to the JVM arguments the standalone way.

<agent_dir>/
├── apminsight-javaagent.jar
├── apminsight.conf
└── <AppName>_<Port>/          <- instance folder
    ├── apminsight_startup_<ts>_<pid>.log
    └── apminsight_agent_<ts>_<pid>.log

C:\ProgramData\ManageEngine Applications Manager APM Auto Profiler\
├── autoprofilerconf.ini
├── apm_process_monitoring_config.json
├── JAVA\
│   ├── apminsight-javaagent.jar          <- the JAR lives HERE
│   ├── apminsight.conf                   <- master conf
│   ├── apminsight_startup_<ts>_<pid>.log <- OLD runs (see table below)
│   ├── apminsight-javaagent\             <- empty placeholder, NOT an instance
│   ├── APM_Java_Instances\
│   │   └── <signature>.json              <- one per registered instance
│   └── <AppName>_<Port>\                 <- an instrumented instance, e.g. myapp_8080
│       ├── apminsight.conf
│       ├── apminsight_startup_<ts>_<pid>.log
│       └── apminsight_agent_<ts>_<pid>.log
└── Logs\
    └── AutoProfilerService.log           <- profiler's own log

How to read this when triaging FSO:

  APM Insight Java Agent — Onboarding Check  v2.0
  appserver01 · Linux · 2026-10-13 17:49
  Deployment: FSO — APM Insight Auto Profiler   Agent directories checked: 1

  Attachment         FAIL  Auto Profiler attached to nothing
  Compatibility      ok    v7.8.1 · Java 17.0.17 · openjdk
  Configuration      ok    licence set · host https://apm-host:8443
  Connectivity       ok    Applications Manager reachable at https://apm-host:8443
  Data collection    WARN  connected, no transaction yet
  Instance folders   FAIL  no instance folder created
  Conflicts          ok    none

  What to act on — 2 blocking · 1 to review, most important first
  ────────────────────────────────────────────────────────────────────

  1  FAIL  A7  Auto Profiler is running but has not attached to the application
        profiler saw 1 process(es) and logged 4 attach attempt(s), but instrumented none
     why   The Auto Profiler instruments a process only at process start. Anything
           already running when it was installed stays un-profiled.
     fix   Restart the application process from a NEW shell or session, so it
           inherits the Auto Profiler's injection environment:
             sudo systemctl restart <your-app>.service
     KB    §3-A · Agent Loading & Attachment

Each row shows the worst result in its area. Informational notes never pull a row below ok — they are listed below but do not headline a passing check.

A normal start, from a v7.7.2 agent. Nine lines out of roughly seventy — these are the ones worth finding:

[02 Apr 2026 19:42:49.146][main][INFO]: Logging initialized successfully.
[02 Apr 2026 19:42:49.147][main][INFO]: Agent Java Home Path : /opt/apminsight
[02 Apr 2026 19:42:49.147][main][INFO]: INFO: APM Insight javaagent v7.7.2 successfully hooked up with JVM (PID:12345)
[02 Apr 2026 19:42:49.147][main][INFO]: JVM started using command: /opt/myapp/myapp.jar
[02 Apr 2026 19:42:49.147][main][INFO]: All auto-configurations applied
[02 Apr 2026 19:42:49.191][main][INFO]: Application name is updated from  to MyApp
[02 Apr 2026 19:42:49.191][main][INFO]: apm.host configured: https://apm-host:8443
[02 Apr 2026 19:42:49.242][main][INFO]: APM Insight agent initialized successfully.
[02 Apr 2026 19:42:55.335][apminsight-services-starter][INFO]: [JavaAgentService] URL to be executed: https://apm-host:8443/arh/connect?license.key=**

Line by line:

The same agent, running steadily. The pattern repeats once a minute:

[02 Apr 2026 19:42:55.931][apminsight-services-starter][INFO]: Logging updated to APMInsight-Agent successfully.
[02 Apr 2026 19:44:00.943][apminsight-2-thread-2][INFO]: [JavaAgentService] URL to be executed: https://apm-host:8443/arh/data?instance_id=10000001&license.key=**
[02 Apr 2026 19:44:00.980][apminsight-2-thread-2][INFO]: Collector Response Code: 920(Agent config updated.)
[02 Apr 2026 19:45:00.940][apminsight-2-thread-2][INFO]: [JavaAgentService] URL to be executed: https://apm-host:8443/arh/data?instance_id=10000001&license.key=**
[02 Apr 2026 19:45:01.038][apminsight-2-thread-2][INFO]: Collector Response Code: 911(Manage the agent.)

Line by line:

Response codes are listed in full in Section 12. 911 and 920 are both healthy; everything else needs action.

Two more files you may be asked for.

The instance registry — APM_Java_Instances/<signature>.json, one entry per instance folder:

{"CreationTime":"1775139175923","RegisteredPort":"8080","InstanceDir":"/opt/apminsight/MyApp_8080","AppName":"MyApp"}

The filename of this file embeds the application's full path, which usually includes a username. Redact it before attaching one to a ticket. The health-check script prints only the AppName and port for this reason.

The diagnostics dump — apminsight_agent_diagnostics_<pid>.log, first lines:

		JavaAgent Diagnostics Information - Thu Apr 02 19:47:55 IST 2026
========================================================================

Classpath
************************
/opt/myapp/myapp.jar

From the application server, when you want an answer in one command.

Did the agent attach at all?

grep -l 'hooked up with JVM' <agent_dir>/*/apminsight_startup_*.log

What did the collector last say?

grep -h 'Response Code:' <agent_dir>/*/apminsight_agent_*.log | tail -1

Which agent and Java version?

grep -hE 'javaagent v|java.version' <agent_dir>/*/apminsight_startup_*.log | head -2

Any load or instrumentation errors?

grep -hE '\[(FATAL|ERROR)\]' <agent_dir>/*/apminsight_*.log | tail -5

Collect everything for a ticket (licence keys are already masked by the agent):

tar czf apm-logs.tgz <agent_dir>/apminsight.conf <agent_dir>/*_*/

Or just run the health-check script with -v and attach its log — it already collects and interprets all of the above.

Script says:

A1 The -javaagent argument was never added

Cause: Without that JVM argument nothing instruments the application, so no monitor can ever appear.

Resolution:

Add the argument to the startup file for your server type, then stop and start the application (a reload is not enough):

  Tomcat        Linux   <tomcat>/bin/setenv.sh
                        CATALINA_OPTS="$CATALINA_OPTS -javaagent:<agent_dir>/apminsight-javaagent.jar"
                Windows <tomcat>\bin\setenv.bat
                        set CATALINA_OPTS=%CATALINA_OPTS% -javaagent:<agent_dir>\apminsight-javaagent.jar
  JBoss/WildFly Linux   <jboss>/bin/standalone.conf      JAVA_OPTS="$JAVA_OPTS -javaagent:..."
                Windows <jboss>\bin\standalone.conf.bat  set "JAVA_OPTS=%JAVA_OPTS% -javaagent:..."
  WebLogic      Linux   <domain>/bin/setDomainEnv.sh     JAVA_OPTIONS="$JAVA_OPTIONS -javaagent:..."
                Windows <domain>\bin\setDomainEnv.cmd    set JAVA_OPTIONS=%JAVA_OPTIONS% -javaagent:...
  Standalone            java -javaagent:<agent_dir>/apminsight-javaagent.jar -jar app.jar

Script says:

A2 The -javaagent line exists but is commented out

Cause: A leading # (or <!-- -->) makes the line inert — the JVM never sees it.

Resolution:

Remove the leading # (or the <!-- --> wrapper) from the line reported above, then fully stop and start the application.

Script says:

A3 Config has the agent, but no JVM has loaded it

Cause: The edit is correct but the JVM is still running the pre-edit command line.

Resolution:

Fully stop and start the application — not a reload or a redeploy. Then re-run this script.

Script says:

A4 Agent is loaded, but not from any documented config file

Cause: Not a fault on its own — it means the argument comes from an environment variable, a systemd unit or a container entrypoint. Worth knowing when you later try to change it.

Resolution:

No action needed while the agent is attached. To change the argument later, look in: JAVA_TOOL_OPTIONS, _JAVA_OPTIONS, the systemd unit's Environment=, or the container ENTRYPOINT / Dockerfile.

Script says:

A5 apminsight-javaagent.jar is missing from the agent directory

Cause: The JVM argument points at a JAR that is not there, so the JVM starts without instrumentation (and may log an error).

Resolution:

Re-extract the agent archive into the agent directory, keeping the folder layout intact, then restart the application. Unzip on the target host rather than copying an already-extracted folder, so file permissions survive.

Script says:

A6 Auto Profiler service is not running

Cause: The Auto Profiler is what injects the agent under FSO. While it is stopped, newly started processes are never instrumented.

Resolution:

Start the Auto Profiler service, then restart the application processes you want monitored:

  Linux    sudo systemctl start  applicationsmanagerapmautoprofiler.service
           sudo systemctl status applicationsmanagerapmautoprofiler.service
  Windows  Services → "ManageEngine Applications Manager APM Auto Profiler" → Start

If the service is absent, the FSO agent was installed without APM Insight: re-deploy it from Settings → FSO Agent → Deploy Agent with "Application Performance Management" ticked.

Script says:

A7 Auto Profiler is running but has not attached to the application

Cause: The Auto Profiler instruments a process only at process start. Anything already running when it was installed stays un-profiled.

Resolution:

Restart the application process from a NEW shell or session, so it inherits the Auto Profiler's injection environment:

  Linux    sudo systemctl restart <your-app>.service
           or stop and start the server with its own scripts:
             Tomcat         <tomcat>/bin/shutdown.sh  then  <tomcat>/bin/startup.sh
             JBoss/WildFly  <jboss>/bin/standalone.sh
  Windows  Restart-Service <your-app-service>
           or, if the server is not installed as a service:
             Tomcat         <tomcat>\bin\shutdown.bat  then  <tomcat>\bin\startup.bat
             JBoss/WildFly  <jboss>\bin\standalone.bat

Then send a request to the application and wait about a minute. A process that was already running when the Auto Profiler was installed is never instrumented retroactively.

Script says:

A8 Host runs both Auto Profiler and manually installed agents

Cause: Not double instrumentation: the Auto Profiler skips a process that already carries an agent, so these are different JVMs. It does mean the deployment is half migrated — the manually instrumented JVMs sit outside the profiler's control and will not follow its configuration or upgrades.

Resolution:

Nothing is broken — decide whether the split is deliberate. To bring everything under FSO, remove the manual -javaagent line from each affected startup config and restart those applications. The Auto Profiler instruments them on their next start. To keep some applications on a manually installed agent, leave them as they are and exclude them under Settings → FSO Agent → APM Insight AutoProfiler, so the split stays deliberate rather than being rediscovered later.

Script says:

B1 Agent version needs a newer Java than the application runs

Cause: Agent v7.x needs Java 8 or newer. On an older JVM it cannot load at all.

Resolution:

Either upgrade the application to Java 8+ (recommended), or use the legacy v5.5 agent for Java 5-7, from APM → Add New Monitor → Java → pick the Java version.

Script says:

B2 IBM J9 / OpenJ9 requires -javaagent before any -X flag

Cause: IBM J9 silently ignores a -javaagent that appears after -Xms/-Xmx, so the agent never loads.

Resolution:

Move -javaagent so it comes BEFORE every -X flag in the startup arguments, then restart. Suspect this whenever the config looks right but no JVM loads the agent.

Script says:

B3 GraalVM native-image is not supported

Cause: A native-image binary has no JVM to attach to; the agent needs JVM mode.

Resolution:

Run the application on the JVM rather than as a native-image binary. The agent cannot instrument an ahead-of-time compiled image.

Script says:

B4 Agent or Java version could not be determined

Cause: Compatibility cannot be confirmed, so a version mismatch may still be hiding here.

Resolution:

Confirm by hand:

  Both     java -jar <agent_dir>/apminsight-javaagent.jar -version
  Linux    grep 'javaagent v' <agent_dir>/*/apminsight_startup_*.log
  Windows  Select-String 'javaagent v' <agent_dir>\*\apminsight_startup_*.log

Script says:

C1 apminsight.conf not found

Cause: The agent reads its licence key and server address from this file. Without it the agent loads and then stops.

Resolution:

Restore apminsight.conf to the agent directory. Download a fresh agent archive from APM → Add New Monitor → Java if you no longer have it — the bundled conf already carries the correct licence key and host.

Script says:

C2 license.key is missing or still a placeholder

Cause: The collector rejects the agent, so data is discarded even though the agent is attached.

Resolution:

Copy the licence key from APM → Add New Monitor → Java (right-hand panel) into license.key in apminsight.conf, then restart the application.

Script says:

C3 apm.host is missing

Cause: The agent has no address to send data to.

Resolution:

Set apm.host in apminsight.conf to the Applications Manager address, for example apm.host=http://appmanager-host:9090 — then restart.

Script says:

C4 apm.host contains escape characters

Cause: A backslash-escaped URL is sent literally and never resolves — a frequent cause of apparent network failure.

Resolution:

Remove the backslashes so the value reads as a plain URL (apm.host=https://host:8443, not https\://host\:8443), then restart.

Script says:

C5 application.name is still the generic default

Cause: Every instance reports under the same name, so several applications collapse into one monitor.

Resolution:

Set a distinct name per application, either in apminsight.conf (application.name=...) or as a JVM flag -Dapminsight.application.name=...

Script says:

C6 agent.server.port is missing

Cause: The instance folder name and the monitor identity both derive from this port.

Resolution:

Set agent.server.port in apminsight.conf to the application's HTTP port, or pass -Dapminsight.agent.server.port=<port>, then restart.

Script says:

C7 The application user cannot write to the agent directory

Cause: The agent cannot create its instance folder or write logs, which looks exactly like the agent never starting.

Resolution:

Give the application user write access to the agent directory:

  Linux    sudo chown -R <app_user> <agent_dir>
           # or, if several users need it:  sudo chmod -R 775 <agent_dir>
  Windows  icacls "<agent_dir>" /grant "<app_user>:(OI)(CI)M" /T

Then restart the application so the agent retries creating its instance folder.

Script says:

D1 Applications Manager is unreachable (no TCP connection)

Cause: The agent buffers and then discards data it cannot deliver.

Resolution:

Validate in this order from the application server, per the KB article "APM Insight monitor not getting added to Applications Manager":

1. Is the host reachable?

       Linux    ping <apm-host>
       Windows  Test-Connection -ComputerName <apm-host> -Count 1

2. Is the port open?

       Linux    nc -zv <apm-host> <apm-port>
       Windows  Test-NetConnection -ComputerName <apm-host> -Port <apm-port>

3. Once the port is open, confirm Applications Manager is what answers:

       Linux    curl '<apm.host>/index.do' | grep 'Applications Manager'
       Windows  (Invoke-WebRequest -Uri '<apm.host>/index.do').Content |
                  Select-String 'Applications Manager'
     Output containing "Applications Manager" means the address is correct.
     Empty output means something else is on that port.

4. If a proxy is required, add to apminsight.conf and restart the agent:

       behind.proxy=true
       proxy.server.host=<proxy_host>
       proxy.server.port=<proxy_port>

Any change to the agent configuration needs an agent restart to take effect.

Script says:

D2 The address answered, but it is not Applications Manager

Cause: The address accepts a connection but does not identify itself as Applications Manager, so the agent is posting data to the wrong service — usually a proxy, a load balancer, or the OpManager port.

Resolution:

Something answered, but it did not identify itself as Applications Manager. Confirm what is actually on that address:

  Linux    curl '<apm.host>/index.do' | grep 'Applications Manager'
  Windows  (Invoke-WebRequest -Uri '<apm.host>/index.do').Content |
             Select-String 'Applications Manager'

Empty output means apm.host points at something else - a proxy, a load balancer, or the OpManager port instead of the Applications Manager web port. Read the correct Web Server Port / SSL Port from Settings -> Tools -> Support -> Installation Information, correct apm.host, then restart the agent.

Script says:

D3 TLS handshake with Applications Manager failed

Cause: Data never leaves the agent, though the TCP connection succeeds.

Resolution:

Pick whichever applies:

1. add the JVM flag -Djdk.tls.namedGroups="secp256r1,secp384r1,secp521r1"

2. upgrade the JVM to Java 11+

3. import the Applications Manager certificate into the JVM truststore

Script says:

D4 The agent has never received a collector response

Cause: The agent has not completed a single handshake, so the monitor will not appear in the UI.

Resolution:

Clear the connectivity findings above first — this one usually resolves with them. If connectivity is already clean, send traffic to the application: the agent opens its first connection only when it has something to report.

Script says:

D5 Collector code 901 — invalid licence key

Cause: Data is refused. The agent keeps retrying for a 3-day grace period, then stops.

Resolution:

Replace license.key with the key from APM → Add New Monitor → Java (right-hand panel), then restart the application. Grace period: 3 days.

Script says:

D6 Collector code 701 — licence expired

Cause: Data is refused after a 15-day grace period.

Resolution:

Renew the APM Insight Java add-on licence, then restart the application. Grace period: 15 days.

Script says:

D7 Collector code 702 — licence instance limit reached

Cause: New instances are refused until a slot frees up (15-day grace).

Resolution:

Either raise the licensed instance count, or unmanage/delete monitors you no longer need in Applications Manager. Grace period: 15 days.

Script says:

D8 Collector code 900 — monitor was deleted in Applications Manager

Cause: The agent keeps sending for 3 days to a monitor that no longer exists.

Resolution:

Re-add the monitor from the APM tab. If the 3-day grace period has already lapsed, restart the application afterwards.

Script says:

D9 Collector code 910 — monitor is unmanaged

Cause: Collection is paused by choice in the UI; nothing is broken.

Resolution:

Manage the monitor again from the APM tab. The agent resumes on its own — no restart needed.

Script says:

D10 Agent is connected but has recorded no transaction yet

Cause: Metrics are only produced by real traffic. A healthy but idle application reports nothing, which is indistinguishable from a broken agent until you check this.

Resolution:

Generate real traffic and re-check — this is expected on an idle application:

1. open the application in a browser, or replay a known request

2. wait about a minute, then re-run this script

APM Insight records web transactions, so a service with no inbound requests reports nothing even when the agent is perfectly healthy. Only treat this as a fault if the application IS receiving traffic — in that case check that the framework is supported, and that the entry point is not excluded by a transaction filter in apminsight.conf.

Script says:

E1 No instance folder was created

Cause: The instance folder is created on the agent's first successful start. Its absence means the agent never got that far.

Resolution:

This is a downstream symptom: fix the agent-loading and configuration findings above, restart the application, then re-run. The folder appears on the agent's first successful start.

Script says:

E2 The expected instance folder is missing

Cause: The agent is running under a different name or port than the configuration implies, so you may be reading the wrong monitor.

Resolution:

Check whether -Dapminsight.application.name / -Dapminsight.agent.server.port on the command line override apminsight.conf — the folder is named from whichever value actually wins.

Script says:

E3 Legacy or stale instance folder present

Cause: Harmless, but it makes log hunting confusing and can mislead the next person.

Resolution:

Safe to delete once no live PID is using it:

  Linux    rm -rf <agent_dir>/<stale_folder>
  Windows  Remove-Item -Recurse -Force "<agent_dir>\<stale_folder>"

Script says:

E4 The agent hit an error while instrumenting classes

Cause: Classes that fail to transform are left un-instrumented, so parts of the application go unmeasured.

Resolution:

Read the full exception in the startup log, then:

  • if it names an application class, report it to support with that log
  • if it names a JDK/framework class, upgrade to the latest agent build

The application keeps running; only the affected classes go un-instrumented.

Script says:

E5 Many restarts recorded in a short span

Cause: Repeated restarts usually mean the application is crashing, which keeps the agent from ever settling.

Resolution:

Investigate why the application keeps restarting — the agent cannot settle until it does. Check the application's own logs first, not the agent's.

Script says:

E6 No data-dispatch confirmation in the agent log

Cause: The agent started but has not confirmed a successful upload.

Resolution:

Clear the connectivity findings above, then re-run. If they are already clean, see D10 — an idle application has nothing to dispatch.

Script says:

F1 A third-party APM agent is attached to the same JVM

Cause: Multiple bytecode agents in one JVM is unsupported and causes crashes, ClassNotFoundException and deploy hangs.

Resolution:

Remove the other agent's -javaagent / -agentpath argument from the startup config and restart. Running two instrumentation agents is not supported.

Script says:

F2 Two live JVMs share one instance folder

Cause: Two JVMs writing one folder interleave their logs and overwrite each other's state.

Resolution:

Give each application its own identity so each gets its own folder:

  -Dapminsight.application.name=<unique_name>
  -Dapminsight.agent.server.port=<unique_port>