Run Collection Agent as a standalone Java process

Overview Copied

This page describes how to run the Collection Agent as an unmanaged standalone Java process that you start and stop yourself. The Netprobe does not supervise the process, so you can run the Collection Agent on a different host from the Netprobe or treat it like any other Java service.

Use this path when the Netprobe and Collection Agent run on different hosts, or when you manage the Java process yourself. If they run on the same host, see Run Collection Agent via Netprobe instead.

Caution

Make sure to read Upgrading Collection Agent, which outlines the breaking changes that may have an impact on your upgrade, before you upgrade to the latest version of Geneos and Collection Agent.

For information on running the Collection Agent in an orchestrated environment, see Data collection in an orchestrated environment.

Note

Beginning Geneos 5.1, the Collection Agent is included in the Netprobe binaries for Windows and generic Linux platforms.

Prerequisites Copied

System requirements Copied

The following requirements must be met on the machine where the Netprobe and Collection Agent are installed:

• Linux operating system (CentOS, RHEL, or SUSE), or
• Windows operating system

Java requirements Copied

• Java 21 or higher.

  Note

  Starting with Geneos 7.1.0, the Collection Agent has been upgraded to version 5.x and requires Java 21 as the minimum supported version.

• A minimum Java heap size of 512MB is recommended for Collection Agent.

  If the agent is performing garbage collection too frequently as the volume increases, a larger heap size should be allocated.

• Once you have Java installed, configure the environment variables required by the Netprobe so that it can locate the required resource files. For guidance, see Configure the Java environment.

  Caution

  Java installation and environment configuration is a common source of errors for users setting up Java-based components and plug-ins. You should read Configure the Java environment to help you understand your Java installation.

Run the Collection Agent as a standalone Java process Copied

To run the Collection Agent as a standalone Java process, follow these steps:

1. Download the Collection Agent binary (collection-agent-<version>-exec.jar) from the ITRS Resources page.
2. Create a YAML configuration file for the Collection Agent (collection-agent.yml). Refer to Sample configuration for an example minimum configuration required for the Collection Agent to work. For a sample YAML configuration and section descriptions, see the Collection Agent configuration reference.
3. If the standalone Collection Agent uses a reporter that publishes to a Netprobe, configure that Netprobe as follows:

• In the Gateway Setup Editor, open Dynamic entities > Collection agent parameters > New Collection agent parameters.

• Choose Unmanaged as the Collection Agent type and set Reporter port to the TCP reporter port from your YAML.

  When that is in place, datapoints from the TCP reporter can flow into Geneos as expected.

4. Download any additional plugins from the ITRS Resources page and install them under pluginDirectory.

Starting the Collection Agent via command line Copied

Run the following command to start the Collection Agent. Pass the path to your YAML as the last argument.

java -jar collection-agent-<version>-exec.jar /path/to/collection-agent.yml

Note

To validate configuration and exit without running the pipelines, add -DtestConfig before -jar. An exit code 0 means the configuration loaded successfully.

Stop the standalone Collection Agent by stopping that Java process. For example, you can interrupt the terminal or stop the service wrapper you use.

Sample configuration Copied

At minimum, you must set pluginDirectory, define collectors, define at least one reporters entry, and wire workflow pipelines to the reporter name.

• Define CA_PLUGIN_DIR, HEALTH_CHECK_PORT, and TCP_REPORTER_PORT on the host or replace ${env:...} with actual values.
• Replace hostname with the host where the Netprobe listens, and align port with the Reporter port you set in the Gateway for an unmanaged Collection Agent.

pluginDirectory: ${env:CA_PLUGIN_DIR}

monitoring:
  healthProbe:
    listenPort: ${env:HEALTH_CHECK_PORT}
  selfMetrics:
    dimensions:
      app_name: collection-agent

reporters:
  - type: tcp
    name: tcp
    hostname: localhost
    port: ${env:TCP_REPORTER_PORT}

collectors:
  - name: statsd
    type: plugin
    className: StatsdServer

workflow:
  storeDirectory: .
  metrics:
    reporter: tcp
  events:
    reporter: tcp

Note

For a secure TCP connection, add tlsConfig under the TCP reporter in your YAML and ensure the Netprobe is configured for secure Collection Agent access. For more information, see Collection Agent configuration reference.