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

Run Collection Agent with Netprobe

Overview

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

This topic walks you through the setup and configuration on the Netprobe to start running the Collection Agent with it.

The following Collection Agent resources are included in a new 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 — resource to run the StatsD plug-in.

Setup and configuration

You can run the Collection Agent with Netprobes running in the normal, floating, and self-announcing modes. The Collection Agent runs as a Java process.

Java requirements

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

Normal and floating Netprobes

For normal and floating Netprobes, you can start the Collection Agent through the Probe configuration:

Probe Collection Agent options

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

For more information, see Dynamic Entities tab in Probes.

Self-Announcing Netprobes

For Self-Announcing Netprobes, you can start the Collection Agent through 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>MT1</mappingType>
</dynamicEntities>

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

The Collection Agent follows the configuration provided in collection_agent/collection-agent.yml packaged with the Netprobe binary:

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.

Collection Agent log file

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

<configuration>
<appender name="stdout" class="ch.qos.logback.core.ConsoleAppender">
<encoder>
<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger - %msg%n</pattern>
</encoder>
</appender>
<appender name="FILE" class="ch.qos.logback.core.FileAppender">
<file>collection_agent/collection-agent.log</file>
<append>true</append>
<!-- set immediateFlush to false for much higher logging throughput -->
<immediateFlush>true</immediateFlush>
<!-- encoders are assigned the type
ch.qos.logback.classic.encoder.PatternLayoutEncoder by default -->
<encoder>
<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger - %msg%n</pattern>
</encoder>
</appender> <logger name="org.apache.kafka" level="info" />
<logger name="org.apache.kafka.clients.producer.KafkaProducer" level="info" />
<logger name="net.openhft" level="error" />
<logger name="com.itrsgroup.collection" level="info" />
<logger name="io.kubernetes.client" level="off" /> <!-- Configure level for a specific reporter:
<logger name="com.itrsgroup.collection.ca.reporters.tcp.TcpReporter(stdout)" level="debug" />
--> <root level="info"> <appender-ref ref="FILE" />
</root>
</configuration>

By default, the log is saved in 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.

Start conditions

The Collection Agent will not start in the following scenarios:

  • JAVA_HOME 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
  • Collection Agent ports are not available:
    • Health port
    • Reporter port

Netprobe connection

  • 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 a downed 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.
  • A Collection Agent started independently of the Netprobe is not managed by 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:

  • CA_HEALTHCHECK_INTERVAL
  • CA_MAX_HEALTHCHECK_ATTEMPTS
  • CA_HEALTHCHECK_TIMEOUT
  • CA_MAX_RESTARTS

For more information on these variables, see Variables in Netprobe variables.

Collection Agent behaviour

  • As long as the start option is enabled on the probe, a managed Collection Agent will run even without its dynamic mapping set from 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 Collection Agent-related changes in the Netprobe setup file or the Gateway Setup Editor. For more information on the Collection Agent-related settings, see Setup and configuration.

Detached mode

A Collection Agent running in detached mode refers to one that is started from the Netprobe configuration with the detached setting set to true.

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