Agent Installation (for Central Collector) - glowroot/glowroot GitHub Wiki

• Java 6+ (Note: Java 7+ is required if you want to use HTTPS between the agent and central collector)

1. Download and unzip glowroot-0.14.4-dist.zip.

2. Add -javaagent:path/to/glowroot.jar to your JVM args [where are my application server's JVM args?].

3. Check that the user account that runs the JVM has write access to the glowroot directory [if you are running on Windows and don't know how to check this, it probably means you can skip this step safely].

4. Create a file named glowroot.properties in the agent directory (the same directory that contains the glowroot.jar file):

   agent.id=
   collector.address=
   

   where:

   agent.id defaults to the hostname where the agent is running. It can be set to any text, and must be unique across all agents. This is also the default display name for the agent in the central UI. The display name for the agent can be modified later in the central UI if needed, without modifying the agent.id which is used for storing and querying the agent's data.

   collector.address must be set to http://hostname:port, where hostname is the hostname (or IP address) of the central collector, and port is the central collector's grpc.httpPort (as configured in the glowroot-central.properties file).

5. If you want to minimize disk space (e.g. for a container image), you can delete lib/glowroot-embedded-collector.jar. You can also delete the lib/glowroot-central-collector-https-<osname>.jar files that are not applicable to your O/S (if you are not connecting to the central collector over https then you don't need any of them).

If you want to roll up data across multiple agents (e.g. across a cluster), you need to prefix the agent.id with a rollup id, e.g. agent.id=My Cluster::ABC. The rollup id portion of the agent.id can be set to any text. The rollup id portion of the agent.id will also be the display name for the rolled up data in the central UI. The display name for the rolled up data can be modified later in the central UI if needed, without modifying the rollup id portion of the agent.id which is used for storing and querying the roll up data.

The uniqueness requirement for agent.id applies to the full agent.id (including the rollup id portion), e.g. it's fine to have one agent My Cluster::ABC and another agent My Other Cluster::ABC.

Specifying a rollup id only, e.g. agent.id=My Cluster::, will cause the hostname where the agent is running to be dynamically appended to form the full agent.id.

Multiple rollup levels are supported, e.g. My Cluster::Amazon West (Oregon)::ABC or My Cluster::Amazon West (Oregon)::.

Note: This is only supported from agents running under Java 7 or later.

1. Set grpc.httpsPort in the glowroot-central.properties file.

2. Place your certificate and private key in the glowroot-central directory, with filenames grpc-cert.pem and grpc-key.pem, where grpc-cert.pem is a PEM encoded X.509 certificate chain, and grpc-key.pem is a PEM encoded PKCS#8 private key without a passphrase.

   Note: A private key and self signed certificate can be generated at the command line meeting these requirements using OpenSSL 1.0.0 or later: openssl req -new -x509 -nodes -days 365 -out grpc-cert.pem -keyout grpc-key.pem.

   Note: For tips on converting an existing private key and X.509 certificate chain to the required format, see Private key and X.509 certificate chain tips.

   Note: If you want to use the same certificate and private key files for both the UI and agent communication, name them cert.pem and key.pem.

3. Set collector.address to https://hostname:port in the agent glowroot.properties file, where port is the central collector's grpc.httpsPort (as configured in step 1 above).

4. If the certificate's Common Name, is different from the hostname used in the collector.address, then add collector.authority to the agent glowroot.properties file and set it to the Common Name.

5. If the certificate is self-signed, or signed by a Certificate Authority that is not in the JVM's cacerts file, then you will need to do one of the following:

   • Create a file named grpc-trusted-root-certs.pem in the glowroot agent directory that contains the certificate (or the CA certificate), or

   • Import the certificate (or the CA certificate) into the JVM's default trust store (e.g. keytool -import -alias glowroot-grpc -file grpc-cert.pem -keystore "$JAVA_HOME/jre/lib/security/cacerts" -storepass changeit, where the alias can be anything you want). See

The location of config files, log files and temp files can be changed by adding these to the agent glowroot.properties file:

conf.dir=
log.dir=
tmp.dir=

If you want to run multiple agents on a single box, you need to add this to the agent glowroot.properties file:

multi.dir=true

and you need to add -Dglowroot.agent.id=... to your JVM args so that each agent can create and use a separate directory under the glowroot directory to store its local configuration (the subdirectory name is based on the glowroot.agent.id property).

The specified glowroot.agent.id is then used instead of the agent.id property in the agent glowroot.properties file.

collector.address is still read from the agent glowroot.properties file, but can be overridden per agent if needed by adding -Dglowroot.collector.address=... to your JVM args.

When the agent starts, if there is no config.json file, it will look for a config-default.json file in the following locations:

• The agent configuration directory (the same directory where the config.json file would be created)
• The parent of the agent configuration directory if you are running multiple agents on a single box
• The glowroot installation directory if it is different from the two directories above

If a config-default.json file is found, then that file is used to populate the initial config.json.

If a config-default.json file is not found, then the factory default agent configuration is used to populate the initial config.json.

You could also define glowroot properties directly on Java command line, next to javaagent

-javaagent:/path/to/glowroot.jar \
-Dglowroot.conf.dir=/path/to/glowroot/confdir \
-Dglowroot.data.dir=/path/to/glowroot/datadir \
-Dglowroot.log.dir=/path/to/glowroot/logdir \
-Dglowroot.tmp.dir=/path/to/glowroot/tmpdir \
-Dglowroot.multi.dir=true \
-Dglowroot.agent.id=web-service \
-Dglowroot.agent.rollup.id=production \
-Dglowroot.collector.address=central.example.org:8181