Geneos ["Geneos"]
["Geneos > Netprobe"]["User Guide"]

Collection Agent setup

Overview

This guide outlines the step-by-step procedures you need to start running the Collection Agent in a standard environment.

For information on running the Collection Agent in an orchestrated environment, see Overview in Prerequisites.

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

Prerequisites

System requirements

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

  • Java 1.8 or higher.

  • 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 haveJava 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.

Geneos components requirements

  • Geneos Netprobe version 5.1.0 or higher.

  • Ensure that your Gateway and Netprobe are running.

Caution: If you are using a Gateway version 5.2, then any Netprobe running in normal or floating mode must also be version 5.2. Otherwise, the Collection Agent will not start.

Setup and configuration

You can run the Collection Agent in two ways:

Regardless of how you run your Collection Agent, it will always run as a Java process.

Run Collection Agent via Netprobe

You can run the Collection Agent with Netprobes running in the normal, floating, or self-announcing modes on the same host.

To run the Netprobe and the Collection Agent on different hosts, you must Run Collection Agent as a stand-alone Java process.

To run the Collection Agent via Netprobe, follow these steps:

Configure Collection Agent and plugins

  1. Download the Netprobe package from the Resources page.

    The following Collection Agent resources are included in collection_agent directory with the Netprobe package:

    • collection-agent.ymlCollection Agent configuration file.
    • logback.xml — sets the log settings for the Collection Agent.
    • collection-agent-2.x.x-exec.jarJava resource library for the Collection Agent.
    • statsd-plugin-2.x.x.jar — a resource to run the StatsD plug-in.
  2. The Collection Agent follows the default configuration provided in collection_agent/collection-agent.yml packaged with the Netprobe binary.

    Note: If you are starting the Collection Agent using the Netprobe, all the ports configured in the Gateway Setup Editor will automatically apply to the running Collection Agent.

    plugin-directory: ${env:CA_PLUGIN_DIR}
    monitoring:
      health-check:
        listen-port: ${env:HEALTH_CHECK_PORT}
      metrics:
        dimensions:
          app_name: collection-agent
    reporters:
      - type: tcp
        name: tcp
        hostname: localhost
        port: ${env:TCP_REPORTER_PORT}
    collectors:
      - name: statsd
        type: plugin
        class-name: StatsdServer
    workflow:
      store-directory: .
      metrics:
        reporter: tcp
      events:
        reporter: tcp

    For more information on configuring the Collection Agent, see Collection Agent configuration reference.

  3. If you need to setup a new plugin that is not yet included in the package, you can download it on the Resources page and add it to the collection_agent directory.

    Note: If you set up a new plugin, then you must also update the collection-agent.yml with the necessary fields.

    For Kubernetes plugin, see Configuration reference in Kubernetes.

    For Azure Monitor plugin, see Azure Monitor plugin documentation.

Create Dynamic Entities

Netprobes receive datapoints from Collection Agents. Each datapoint can have a different set of dimensions, attributes, and properties. You should create mappings to construct a Geneos hierarchy from datapoints. This Geneos hierarchy determines how data is displayed in your Active Console. You should also create a mapping type, which allows you to easily deploy the same configuration on multiple probes.

  1. Open Gateway Setup Editor.

  2. Click Dynamic entitiesMapping, and then click New Mapping.

  3. Enter a mapping name in the Name field.

  4. In Options, choose custom or builtin. For more information, see Dynamic entities > Mapping > Options in Dynamic Entities.

    Note: A builtin Collection Agent V2 mapping is packaged with the Netprobe, which automatically sets up the default mappings needed to display the Collection Agent self-monitoring metrics.

  5. Click Dynamic entitiesMapping types, and then click New Mapping type.

  6. In the Mappings field, click Add new to add the name of the mapping created in Step 4.

  7. To monitor the logs collected by the Collection Agent plugin, you can add an FKM plugin sampler in the Samplers field. The FKM plugin consumes these logs as streams. To configure your FKM plugin to monitor these streams, see files > file > source > stream in File Keyword Monitor configuration.

  8. Click Save current document.

Start Collection Agent

  1. Open Gateway Setup Editor.

  2. Click Probes, and then select your Netprobe.

  3. Click Dynamic Entities tab.

  4. In Collection Agent, tick Start.

  5. To specify additional JVM options, enter the options in Jvm args. For more information, see probes > Dynamic Entities > Collection Agent > JVM args in Probes.

  6. To specify the Collection Agent port that the Netprobe communicates with for health checks, enter a new port in Health port.

  7. To specify the TCP port where the Netprobe should listen to communicate with the Collection Agent, enter a new port in Reporter port.

  8. If you want to stop the Collection Agent process when the Netprobe stops, disable the detached mode by unticking Detached. For more information, see Detached mode.

    Note: If the Detached mode is disabled, Collection Agent will stop when the Netprobe stops even if Start is checked.

  9. In Mapping type, select the mapping type you created in Create Dynamic Entities section.

For more information on Dynamic Entities, see Dynamic Entities tab in Probes.

Self-Announcing Netprobe

For Self-Announcing Netprobes, you can start the Collection Agent by adding the following configuration in the selfAnnounce settings in the Netprobe setup file:

<collectionAgent>
	<start>true</start>
	<jvmArgs>-Xms512M -Xmx512M -Dlogback.configurationFile=collection_agent/logback.xml</jvmArgs>
	<healthPort>9136</healthPort>
	<reporterPort>9137</reporterPort>
	<detached>true</detached>
</collectionAgent>
<dynamicEntites>
	<mappingType>DynamicEntitiesMapping</mappingType>
</dynamicEntities>
					

For more information, see Self-announce settings in Netprobe setup.

Run Collection Agent as a stand-alone Java process

Running the Collection Agent as a stand-alone Java process allows you to run the Netprobe and the Collection Agent on different hosts.

If you wish to run the Netprobe and the Collection Agent on the same host, you must Run Collection Agent via Netprobe.

To run Collection Agent as a stand-alone Java process, follow these steps:

Configure and start the Collection Agent

  1. Download the Collection Agent jar file, collection-agent-<version>-exec.jar, from the Resources page.
  2. Create a configuration file in YAML format, for example collection-agent.yml.

    Ensure the following:

    • The following fields for the tcp reporter are configured:

      • hostname: - host where the Netprobe is running.
      • port: - a unique port number.
    • The environment variables in the collection-agent.yml are defined on your host.

    plugin-directory: ${env:CA_PLUGIN_DIR}
    monitoring:
      health-check:
        listen-port: ${env:HEALTH_CHECK_PORT}
      metrics:
        dimensions:
          app_name: collection-agent
    reporters:
      - type: tcp
        name: tcp
        hostname: localhost
        port: ${env:TCP_REPORTER_PORT}
    collectors:
      - name: statsd
        type: plugin
        class-name: StatsdServer
    workflow:
      store-directory: .
      metrics:
        reporter: tcp
      events:
        reporter: tcp

    For more information on configuring the Collection Agent, see Collection Agent configuration reference.

  3. If you need to set up a new plugin, download it from the Resources page and put in the same directory as collection-agent-<version>-exec.jar.

    Note: If you set up a new plugin, then you must also update the collection-agent.yml with the necessary fields.

    For Kubernetes plugin, see Configuration reference in Kubernetes.

    For Azure Monitor plugin, see Azure Monitor plugin documentation.

  4. Run the Collection Agent using the following command:

    java -jar collection-agent-<version>-exec.jar collection-agent.yml
  5. To stop the Collection Agent, stop the Java process you started in Step 4.

    Caution: The only way to start or to stop the Collection Agent as a stand-alone Java process is to run the Java command in Step 4 and to stop the Java process in the terminal, respectively.

Create Dynamic Entities

Netprobes receive datapoints from Collection Agents. Each datapoint can have a different set of dimensions, attributes, and properties. You should create mappings to construct a Geneos hierarchy from datapoints. This Geneos hierarchy determines how data is displayed in your Active Console. You should also create a mapping type, which allows you to easily deploy the same configuration on multiple probes.

  1. Open Gateway Setup Editor.

  2. Click Dynamic entitiesMapping, and then click New Mapping.

  3. Enter a mapping name in the Name field.

  4. In Options, choose custom or builtin. For more information, see Dynamic entities > Mapping > Options in Dynamic Entities.

    Note: A builtin Collection Agent V2 mapping is packaged with the Netprobe, which automatically sets up the default mappings needed to display the Collection Agent self-monitoring metrics.

  5. Click Dynamic entitiesMapping types, and then click New Mapping type.

  6. In the Mappings field, click Add new to add the name of the mapping created in Step 4.

  7. To monitor the logs collected by the Collection Agent plugin, you can add an FKM plugin sampler in the Samplers field. The FKM plugin consumes these logs as streams. To configure your FKM plugin to monitor these streams, see files > file > source > stream in File Keyword Monitor configuration.

  8. Click Save current document.

Connect the Collection Agent

  1. Open Gateway Setup Editor.

  2. Click Probes, and then select your Netprobe.

  3. Click Dynamic Entities tab.

  4. Input the port: value from yourcollection-agent.yml in the Reporter port field.

  5. In Mapping type, select the mapping type created in Create Dynamic Entities section.

Collection Agent self-monitoring Metrics

If you started the Collection Agent with the builtin Collection Agent V2 mapping, then the following Collection Agent self-monitoring metrics are displayed in your Active Console:

  • collection-agent view

  • collection-agent by jvm_memory_gc_name

  • collection-agent by jvm_memory_pool_name

  • collection-agent by thread_state

Dynamic Entities Health

The Dynamic Entities Health plugin monitors the performance of Collection Agent and Netprobe communication. It tracks the state of all metrics received by a Netprobe from the Collection Agent, and all Dynamic Entities associated with a Netprobe.

For guidance on how to setup the Dynamic Entities Health sampler, see Dynamic Entities Health.

Collection Agent log file

The Collection Agent uses a separate log file from the Netprobe. The log settings for Collection Agent uses Logback and is stored in logback.xml:

By default, the Collection Agent log file is collection_agent/collection-agent.log.

If the Collection Agent cannot access logback.xml for any reason, then it writes to standard output (stdout) and standard error (stderr), and outputs the log file in the Netprobe's working directory.

Caution: This fallback behaviour is not supported on Windows.

Connection and lifecycle

When run with the Netprobe, Collection Agent runs as a Java process alongside the Netprobe process.

Common failure modes

The Collection Agent will not start in the following scenarios:

  • JAVA_HOME is not set in the Netprobe's environment. For more information, see Configure the Java environment.
  • Collection Agent resource files are missing, or are not the same version packaged in the collection_agent directory:
    • collection-agent-2.x.x-exec.jar
    • collection-agent.yml
  • The following Collection Agent ports are not available:
    • Health port
    • Reporter port
  • StatsD UDP port is not available

    Note: The StatsD plugin uses the default which is specified in the collection-agent.yml. If there are two Netprobes that are running with one Collection Agent, then an error message, Address bind already in use., is displayed in the Collection Agent log file.

Netprobe connection

The following describes the behaviour of the Netprobe connection depending on the state of the Collection Agent:

  • Netprobe restarts the managed Collection Agent if the latter goes down, or cannot be detected after having been detected before.
  • Netprobe will attempt to restart an unreachable Collection Agent three times. If on the third time, the Netprobe still cannot detect the Collection Agent, then it no longer attempts to restart the Collection Agent.
  • If the Netprobe restarts, it resumes its connection with the managed Collection Agent.

Note: A Collection Agent started independently of the Netprobe is not managed by the Netprobe.

Collection Agent behaviour

The following describes the behaviour of the Collection Agent depending on the Netprobe setup or the Gateway Setup Editor configuration:

  • If the Start option is enabled on the Netprobe, a managed Collection Agent will run without a dynamic mapping set in the Gateway Setup Editor. For guidance in adding the dynamic mapping, see Dynamic Entities.
  • A managed Collection Agent does not restart when there are no changes in the Netprobe setup file or the Gateway Setup Editor related to the Collection Agent.

Detached mode

A Collection Agent running in detached mode is one that is running as stand-alone Java process or that is started from the Netprobe configuration with the detached setting set to true.

When running a Netprobe in detached mode, consider the following:

  • By default, a managed Collection Agent runs in detached mode. This means that it keeps running even when the Netprobe stops.
  • Netprobe does not perform health checks on a Collection Agent running in detached mode.
  • In detached mode, the Collection Agent only stops when you disable the run option in the Collection Agent configuration.
  • If you disable detached mode, then the Collection Agent stops when the Netprobe is stopped intentionally. For example:
    • Netprobe service is stopped in Windows.
    • Netprobe process is stopped in Linux and other platforms.
    • Other intentional termination of the Netprobe.

Health checks

The Netprobe periodically pings the managed Collection Agent through the defined health check port, except when the managed Collection Agent is running in Detached mode.

The health checks are governed by the following variables:

Name Description
CA_HEALTHCHECK_INTERVAL

Time in seconds between pings from the Netprobe to a managed Collection Agent.

Default value: 20

CA_MAX_HEALTHCHECK_ATTEMPTS

Maximum number of attempts that the Netprobe makes to contact a managed Collection Agent.

Default value: 3

CA_HEALTHCHECK_TIMEOUT

Time in seconds that the Netprobe waits for a response from the Collection Agent during a health check.

Default value: 5

CA_MAX_RESTARTS

Maximum number of attempts that the Netprobe makes to restart an unresponsive managed Collection Agent.

If the Netprobe fails to communicate with the managed Collection Agent after the maximum number of attempts, then the Netprobe stops monitoring the managed Collection Agent.

Default value: 3