How APM agents work

How APM agents work

How APM Insight Collects Data

Technology
The agent runs inside the application process and uses in-memory instrumentation. It times the application's own calls and sends summary data to your Applications Manager server.
Write operations
None in your databases, application data or other systems. On the host, the agent writes only its own logs and state, inside its own folder.
Read operations
The agent observes requests, SQL, outbound calls, errors and runtime metrics as the application performs them. It runs no queries or commands of its own.
Network
One-way, outbound HTTPS from the application host to your own Applications Manager server. No inbound connections.

1. Architecture at a glance

The agent runs inside the application process and initiates every connection to Applications Manager. Applications Manager never connects to the agent. For .NET, PHP and Python, data is routed through the Data Exporter on the same host.

Application host
Your network
Application process
Tomcat, JBoss, WebLogic, IIS, Node.js, ...
APM Insight agent
in-process instrumentation
Agent folder
the agent writes its logs and state here only
HTTPS
outbound only
replies only
Applications Manager server
Your network, on-premises
Web server
HTTPS 8443 / HTTP 9090 (defaults)
Applications Manager database
All collected data is stored here

The application host accepts no inbound connection. Collected data stays in your network.

Component Where it runs Role
APM Insight agent Inside the monitored application process Collects traces, errors and runtime metrics
Data Exporter (.NET, PHP, Python; optional for Node.js) A separate local process on the application host Receives data from the agent and forwards it to Applications Manager
Applications Manager server Your on-premises server Receives, stores and displays the data
Applications Manager database Your on-premises database Stores all collected data. Nothing is stored outside your environment.

How the agent and the server communicate

APM Insight agent
Applications Manager
1. Register: license key, app name, host, agent version
License checked, monitor added automatically
Repeats every minute
2. Metrics every 60 s, plus traces of slow requests
3. Status code, with an instruction if one is pending

Applications Manager never opens a connection to the agent.

  1. Register. When the application starts, the agent connects to Applications Manager. It sends the license key, application name, host name, application server port and agent version. Applications Manager validates the license and adds the monitor automatically.
  2. Send data. The agent sends aggregated metrics every 60 seconds. It also sends transaction traces for slow requests, over the same outbound HTTPS connection.
  3. Receive instructions. Applications Manager answers each agent request with a status code. That reply is the only way the server talks to the agent. It can tell the agent that its configuration has changed, ask it to take a thread dump, or tell it to stop sending data (unmanage or delete). The agent fetches any changed settings on its next call.

2. How the agent collects data

The agent loads into the application's own runtime when the application starts. It adds hooks to a fixed set of well-known framework and library entry points. Your custom code is not instrumented unless you configure custom instrumentation.

Instrumented by default:

  • web framework entry points (servlets, controllers, routes)
  • database access libraries (for example JDBC, ADO.NET or Entity Framework)
  • common HTTP and web-service clients
Language How the agent attaches Change made to the application
Java (8 and later) Standard Java agent (-javaagent:apminsight-javaagent.jar). Classes are instrumented in memory as the JVM loads them. One JVM startup argument. Class and JAR files on disk are not modified.
.NET / .NET Core Microsoft CLR Profiling API, plus a Windows service and the Data Exporter Installer registers the profiler for IIS / the application. Binaries on disk are not modified.
Node.js apminsight npm module loaded first by the application. It wraps supported modules at load time. A require line at the application entry point, or a startup flag
Python apminsight package. It wraps supported libraries when they are imported. The application is started through the agent's launcher or import
PHP PHP extension loaded by the PHP runtime, plus the Data Exporter Extension entry in php.ini
Ruby Ruby gem that wraps supported Rails and library calls Gem added to the application
What "instrumentation" means here: at each hooked call, the agent records when the call started and ended, plus a few identifying details. Examples are the URL path, the SQL statement, the remote host, and any exception thrown. The application's own logic, inputs and outputs pass through unchanged.

Runtime metrics such as Java heap, garbage collection and threads come from the runtime's built-in management interfaces (for Java, the platform MXBeans). The agent reads them in-process.

3. What the agent writes

The agent writes only inside its own folder on the application host. It never writes to your databases, your application data or any other system.

Writes, inside its own folder only
  • Agent log files
  • Agent state: the instance ID assigned at registration, and settings received from Applications Manager
  • Configuration file apminsight.conf (created by your administrator)
Never writes
  • Inserts, updates or deletes in your databases. The agent runs no SQL of its own.
  • Application data, files, sessions or business transactions
  • Class files, JARs, DLLs or source code on disk. Java bytecode changes exist only in memory.
  • Other servers or systems in your organisation
What Where When
Agent log files apminsight/logs under the agent folder (Java default; set with apminsight.log.dir) Continuously, rotated by the agent
Agent state Agent folder At registration and when the configuration changes
Agent configuration file (apminsight.conf) Agent folder Written by your administrator at install time
Startup change (JVM argument, profiler registration, php.ini entry, require line, Windows service) Application server or OS configuration Once, at installation, by your administrator

Optional features that change something (all off unless enabled)

Feature What it changes Default
RUM script auto-injection (Java, .NET) Adds a browser-monitoring JavaScript snippet to HTML pages that the application serves Off. You must enable it and set URL patterns.
Agent auto-upgrade Downloads a new agent package from your Applications Manager server and replaces the agent files. Needs an application restart (Java) or IIS reset (.NET). Off
Manual upgrade from the console Same as auto-upgrade, started by an administrator Only when an administrator runs it

4. What the agent reads

The agent reads only what passes through the instrumented calls in the application process. It does not scan the file system, databases or network.

Collected by default
  • URL path, method, status, response time
  • Call tree of slow requests
  • SQL statements and their timing
  • Outbound call host, path and timing
  • Exceptions and stack traces
  • Runtime metrics (memory, GC, threads, CPU)
  • Host and runtime details
  • Library names and versions
Off unless an administrator enables it
  • HTTP request parameters
  • HTTP request and response headers
  • Headers on outbound calls
  • Custom JMX MBeans (Java)
  • Thread dump (on request from the console)
Never collected
  • Request or response bodies
  • Database result sets (rows returned)
  • File contents
  • User passwords or session contents
  • Data from other processes

Collected by default: details

Category Data Source
Web transactions URL path, HTTP method, status code, response time, throughput, Apdex score Instrumented request entry point
Transaction traces (slow requests only, default threshold 2 s) Call tree of instrumented methods with execution times Instrumented methods
Database calls SQL statement text, operation type (SELECT/INSERT/...), table name, database host and port, execution time. Stack trace for slow SQL (default over 3 s). Database driver calls made by the application
External calls Remote host, URL path, response time, status Instrumented HTTP and web-service clients
Errors and exceptions Exception class, message, stack trace, HTTP error codes Instrumented calls
Runtime metrics (Java) Heap and non-heap memory, garbage collection, thread counts, class loading, process CPU JVM platform MXBeans, in-process
Environment Host name, IP address, OS, application server type and version, runtime version, agent version Read once at startup
Library inventory (Java, PHP, Python) Names and versions of libraries loaded by the application, used for the vulnerable-dependency report Application class path / installed packages

Off by default: settings

Data Setting Default
HTTP request parameters webtransaction.trace.input.params.record Off. When enabled, names such as password and authKey are excluded by default.
HTTP request / response headers webtransaction.trace.request.headers.record, ...response.headers.record Off. For Java, Cookie is in the default exclude list.
Headers on outbound calls webtransaction.trace.external.request.headers.record Off
Custom JMX MBeans (Java) capture.jmx.metrics Off
Thread dump Taken only on request from the Applications Manager console On demand

5. Network and security footprint

One firewall rule is enough: allow the application host to reach the Applications Manager web port. Nothing needs to reach the application host.

Item Detail
Direction Outbound only: application host → Applications Manager server
Protocol HTTPS (apm.protocol.https=true). Plain HTTP is supported but not recommended.
Destination port Applications Manager web port: 8443 (HTTPS) or 9090 (HTTP) by default, or the port you configured
Firewall rule needed Allow application host → Applications Manager host on that one port. No inbound rule on the application host.
Proxy Supported (behind.proxy, proxy.server.host, proxy.server.port, optional proxy credentials)
Authentication Each agent identifies itself with the Applications Manager license key in apminsight.conf. Applications Manager rejects agents with an invalid key.
Frequency Metrics every 60 seconds, plus traces when slow transactions occur
Data location Applications Manager is an on-premises tool. All data resides only in your environment, in your Applications Manager database.

6. Performance impact

ManageEngine measured the Java agent under sustained load: at most 2% extra CPU and about 3.5–3.7% added response time.

≤ 2%
CPU
Additional CPU load could be in this range
3.5–3.7%
Response time
Added response time with default instrumentation
100–800 MB
Memory
Depends on load and configuration. The peak (around 800 MB) occurs when full transaction tracking (traces, exceptions) is enabled.
≈ 5 MB/hour
Network
Maximum bandwidth, one-way HTTPS once a minute

Test setup: Spring Framework e-commerce application, Java 11, MySQL, 2,000 HTTP requests per minute, 1 hour. Source: APM Insight Java agent performance report.

Protection under load

  • Smart sampling (Java, on by default): the agent adjusts how much detail it captures to the current traffic, so its overhead stays bounded as load grows.
  • Self-limiting: if the application is overloaded, the agent automatically scales back its own data collection instead of adding to the load.
  • Tunable: overhead grows with the number of instrumented methods, so extensive custom instrumentation raises it. Trace capture is limited to slow transactions, and the thresholds can be tuned.

7. Controls for restricted environments

Most settings can be changed centrally from APM Insight > Agent Configuration Profile in Applications Manager. They reach the agent on its next call.

Goal Setting / action
Replace literal values in captured SQL with ? Turn on SQL parameterization (transaction.trace.sql.parametrize=true) in the agent configuration profile. Recommended where SQL can contain sensitive values.
Do not capture SQL statements at all sql.capture.enabled=false
Exclude specific URLs from monitoring transaction.skip.patterns
Keep parameters and headers out Leave the *.record settings off (default). If enabled, extend the *.ignore lists.
Keep the agent version fixed Leave auto-upgrade disabled (default)
Prevent HTML changes Leave RUM auto-injection disabled (default)
Stop data collection temporarily Unmanage the monitor in Applications Manager. The agent stops sending data.
Remove the agent Remove the startup change (for example the -javaagent argument), restart the application, and delete the agent folder. Nothing else is left on the host.

8. Prerequisites and permissions

  • Outbound network access from each application host to the Applications Manager host on its web port (8443 by default).
  • File system: read access to the agent folder for the application's service account, and write access to the agent's logs folder.
  • Application change window: one restart of the application to load the agent (and again to remove it).
  • Supported runtime: see the agent download page for current versions. For example, the Java agent supports Java 8 and later.
  • No database credentials, OS administrator rights or domain accounts are needed by the agent itself. The installer may need administrator rights to register the .NET profiler or Windows service.

9. FAQ

Does the agent run any queries against our database?

No. It times the SQL your application already runs. It does not open its own database connections.

Can Applications Manager run commands on our application server through the agent?

No. Applications Manager cannot open a connection to the agent. It can only reply to the agent's own requests with fixed instructions: change monitoring settings, take a thread dump, stop sending data, or (only if enabled) download an agent upgrade.

What is the performance impact?

Low. In ManageEngine's Java agent test, the agent added at most 2% CPU and about 3.5–3.7% to response time. Smart sampling and self-limiting keep the overhead bounded under heavy load. See section 6.

Can we review exactly what is sent?

Yes. Set apminsight.log.level to a detailed level on a test system and review the agent logs. You can also inspect traffic at your proxy.

References