JavaPulse Agent for CommandBox

Attach the JavaPulse APM agent to a CommandBox server with a single command. No manual JVM argument editing: the module downloads the agent jar and writes the -javaagent line into your server's jvm.args for you.

JavaPulse is application performance monitoring built for the JVM, first-class on Lucee and Adobe ColdFusion as well as Spring Boot, Tomcat and any Java application. It captures every request, its timing, the queries it ran and the errors it threw.

Install

box install commandbox-javapulse

This installs globally, so the javapulse commands are available from any server directory.

Usage

From your server's web root (where server.json lives):

# Attach the agent (downloads the jar the first time)
javapulse enable key=YOUR_SERVER_KEY

# Restart so the JVM picks up the agent
server restart

Your server key comes from the install screen in the JavaPulse console (creating an application and key is free).

Commands

Command	What it does
javapulse enable key=<key>	Download the agent (once) and add the -javaagent line to this server's jvm.args.
javapulse update	Download the latest agent jar, upgrading every server that uses it. Restart to apply.
javapulse disable	Remove the -javaagent line from this server. The shared jar is left in place.
javapulse status	Show whether the agent jar is cached and whether this server has it enabled.

Run javapulse help enable (or disable / status) for the full options, including serverConfigFile for servers that use a non-default config file and --update to refresh the cached jar.

How it works

• The agent jar is downloaded once to ~/.CommandBox/javapulse/javapulse-agent.jar and shared across every server on the machine.
• enable writes -javaagent:<jar>=key=<your key> into jvm.args in server.json, preserving any JVM args you already have. Re-running enable replaces the existing entry rather than stacking duplicates, so it is safe to run again to change the key.
• Nothing is committed to your application; the change lives in server.json.
• The server key is written into jvm.args in plain text. If you commit server.json to source control, keep the key out of version control.

Requirements

• CommandBox 5+ (Lucee or Adobe ColdFusion servers).
• Outbound HTTPS from the server to javapulse.io (to download the agent jar on enable) and to agent.javapulse.io (for the agent to report).

Documentation

Full guide: javapulse.io/docs/install/commandbox

Licence

MIT, Host Media Ltd.