Connect Geneos to ITRS Analytics

Overview Copied

ITRS Analytics is an observability platform for data storage and analytics. You can configure Gateways and Netprobes to publish data to ITRS Analytics so you can store and analyze metrics, logs and events in ITRS Analytics.

The Gateway connects to ITRS Analytics via two separate pipelines:

• Ingestion pipeline — Gateway publishes monitoring data to ITRS Analytics. This is a write-only operation that uses gRPC over HTTP/2.
• Data pipeline — Gateway retrieves historical data from ITRS Analytics to display in Active Console, and publishes commands to ITRS Analytics for execution via the Entity Viewer. This connection uses standard HTTPS REST APIs.

Communication protocol and requirements Copied

Gateway publishes data to ITRS Analytics using gRPC (Google Remote Procedure Call), which requires HTTP/2 as the underlying transport protocol.

Important

HTTP/1.x is not supported for Gateway to ITRS Analytics connection.

The technical decision to use gRPC and HTTP/2 provides several critical advantages for high-volume telemetry data:

• Multiplexing — HTTP/2 enables multiple concurrent streams over a single TCP connection, significantly reducing connection overhead when publishing metrics, events, and logs simultaneously.
• Binary protocol — gRPC uses Protocol Buffers (protobuf) for efficient binary serialization, reducing payload sizes and network bandwidth compared to text-based protocols.
• Bidirectional streaming — the full-duplex communication of HTTP/2 allows for efficient back-pressure mechanisms and flow control, essential for handling variable data volumes.
• Header compression — the HPACK compression of HTTP/2 reduces overhead from repeated headers, important when sending thousands of metrics per second.
• Performance at scale — for environments with hundreds of dataviews and high-frequency sampling intervals, gRPC with HTTP/2 provides superior throughput and lower latency compared to traditional REST APIs over HTTP/1.

Network infrastructure requirements Copied

Critical: Verify HTTP/2 and gRPC support for ingestion pipeline

The ingestion pipeline uses gRPC and requires network infrastructure that supports HTTP/2. All network infrastructure between Gateway and the ITRS Analytics ingestion endpoint must support HTTP/2 and gRPC. This includes:

• Load balancers
• Reverse proxies
• API gateways
• Web application firewalls (WAF)
• Ingress controllers (Kubernetes environments)
• Network proxies

The data pipeline can use normal proxies and does not require HTTP/2 or gRPC support. The data pipeline uses a different endpoint (for example, test.itrslab.com) than the ingestion pipeline (for example, ingestion-test.itrslab.com).

gRPC is not always enabled by default on many network devices and cloud services. Failure to verify this can result in connection failures or silent data loss.

Common infrastructure that requires explicit gRPC enablement Copied

The following infrastructure typically requires explicit configuration to support gRPC:

• Cloud load balancers

  • AWS Application Load Balancer (ALB) — supports gRPC starting from AWS ALB with HTTP/2 enabled. See Application Load Balancers now Support gRPC Workloads.
  • AWS Network Load Balancer (NLB) — transparent to gRPC as it operates at Layer 4.
  • Azure Application Gateway — Requires HTTP/2 configuration. See Azure Application Gateway configuration overview.
  • Azure Load Balancer — transparent to gRPC as it operates at Layer 4.
  • Google Cloud Load Balancing — supports gRPC natively. See gRPC load balancing on GCP.

• Ingress Controllers (Kubernetes)

  • NGINX Ingress Controller — requires gRPC annotations. See NGINX gRPC support.
  • Traefik — supports gRPC with HTTP/2. See Traefik gRPC example.
  • HAProxy Ingress — requires HTTP/2 backend configuration. See HAProxy HTTP/2 documentation.
  • Istio — supports gRPC natively. See Istio traffic management.

• Reverse Proxies

  • NGINX — requires grpc_pass directive. See NGINX gRPC proxying.
  • HAProxy — requires ALPN and HTTP/2 configuration. See HAProxy gRPC documentation.
  • Apache HTTP Server — limited gRPC support; consider alternatives.
  • Envoy Proxy — native gRPC support. See Envoy gRPC documentation.

Legacy infrastructure compatibility

Old network devices, particularly those manufactured before 2015, may not support HTTP/2 or gRPC. This includes:

• Older hardware load balancers (F5 versions prior to v12.0, NetScaler versions prior to v11.0)
• Legacy firewalls without application-layer protocol support
• Outdated proxy servers

If your infrastructure includes such devices, they must be upgraded or bypassed for ITRS Analytics connectivity.

Connection test and validation Copied

Before deploying Gateway to ITRS Analytics publishing in production, verify that:

1. Your network path supports HTTP/2 and gRPC.
2. No intermediate proxies or firewalls are blocking or downgrading the connection.
3. TLS/SSL certificates are properly configured for HTTP/2 negotiation (ALPN).

You can test gRPC connectivity using the grpcurl tool:

grpcurl -v your-ingestion-endpoint.com:443 list

For ALPN verification, use openssl:

openssl s_client -alpn h2 -connect your-ingestion-endpoint.com:443 < /dev/null

The response should include ALPN protocol: h2, confirming HTTP/2 support.

ITRS Analytics concepts Copied

ITRS Analytics adopts a data model that includes many features that may sound familiar to Geneos users. However, it is important to recognise that these concepts are fundamentally different.

Entities Copied

Unlike the user-defined Managed Entities in Geneos, in ITRS Analytics an Entity is automatically created based on the dimensions that describe the data points. See the Data model for more information.

Entities can also have associated attributes but this does not affect the definition of an Entity. ITRS Analytics allows users to search for Entities metrics using both dimensions and attributes.

Geneos structures are mapped to ITRS Analytics entities, attributes, and metrics.

Consider an example:

In general, traditional data generates the following entities:

• An entity to represent each Geneos Managed Entity.
• An entity to represent each Geneos sampler.
• An entity to represent each dataview (where headline metrics exist).
• An entity to represent each row in a dataview (or column if the dataview is pivoted).

Cells in dataview rows (and headlines) are mapped to metrics that exist on these ITRS Analytics entities according to the following rules:

• If the cell is marked as having a numeric data type in its schema then its contents will be published to ITRS Analytics as a GAUGE metric.
• If the cell is marked as having a non-numeric data type in its schema then its contents will be published to ITRS Analytics as a STATUS_METRIC.
• If no schema has been defined, the Gateway will attempt to convert the cell to a GAUGE metric. If this succeeds the value will be published as a GAUGE, otherwise, it will be published as a STATUS_METRIC.

For data that is sent to Geneos by a Collection Agent, the type of the metric will be preserved. As Collection Agent v2 does not use STATUS_METRIC, non-numeric data from Collection Agent will be sent and published as ATTRIBUTES.

ITRS Analytics closely follows the data model used by the Collection Agent. For more information, see Data collection in an orchestrated environment.

Data throttling Copied

To reduce data processed by ITRS Analytics, without compromising monitoring or investigation, the Gateway throttles publishing of fast-updating dataview cells that are not actively monitored. Cells are considered to be actively monitored if they have a severity of OK, Warning, or Critical.

Cells that are not actively monitored will be published at most once every 20 seconds by default. This rate can be adjusted in Advanced publishing settings > Throttle.

The throttling only applies to dataviews from samplers with a sample interval shorter than the Throttle setting. Dataviews in dynamically created samplers and API samplers (which have no sample interval) are not affected by throttling.

Example 1: Throttling applied

• Sample interval: 1 second
• Throttle setting: 20 seconds

Cells without severity are published once every 20 seconds. Cells with severity (OK, Warning, Critical) continue publishing every second.

Example 2: Throttling not applied

• Sample interval: 20 seconds
• Throttle setting: 10 seconds

No throttling is applied because the sample interval is already longer than the throttle setting. All updates are published as they occur.

Data labels Copied

Gateway sends two types of labels that allow you to search through ITRS Analytics entities:

• Dimensions: these are the name-value pairs used to uniquely identify an ITRS Analytics Entity.
• Attributes: these are observed pieces of information about an ITRS Analytics entity, such as the osType of a Geneos Managed Entity.

Every metric has a set of dimensions that uniquely identify it. These are derived from the Geneos hierarchy of gateway, managedEntity, sampler, type, dataview, and row.

Geneos Managed Entity attributes set in the Gateway Setup Editor are sent as ENTITY_ATTRIBUTE metrics on the corresponding ITRS Analytics entities in the itrsgroup.com/geneos/gse namespace. Gateway also sends each sampler’s Group and PluginName as ENTITY_ATTRIBUTE metrics on the ITRS Analytics entity representing that sampler.

Netprobe parameters, such as HostName, Port, ConState, OS, or Version, are sent as ENTITY_ATTRIBUTE metrics on each ITRS Analytics entity representing a Geneos Managed Entity running on that Netprobe. The Netprobe also sends a sanitised version of OS called osType.

Signals Copied

Gateway sends severity changes to ITRS Analytics as signals, and a signal stream is provided for every metric. Gateway sends the severity and the value on the cell at the time that the severity changed, and snooze events to ITRS Analytics.

Audit Copied

Gateway sends audit events to ITRS Analytics when a connection is established. Audit events originating from a Gateway will have a dimension of gateway. Audit events originating from a Netprobe (like running a command on a Netprobe) will have dimensions of both gateway and probe.

The Gateway will publish the following audit events to ITRS Analytics:

• User logon and logoff events
• Setup changes
• Triggering of commands
• Delegating of commands to other Gateways
• Triggering of REST endpoints
• Triggering of actions
• Triggering of alerts

Publish from Gateway to ITRS Analytics Copied

You can publish data from Gateway to ITRS Analytics via the Ingestion service. This service is installed as part of your ITRS Analytics installation.

By default, Gateway will publish all metrics, severity events, and audit events to ITRS Analytics. You can configure filtering strategies to control what data is published to ITRS Analytics. This can help minimise downstream data processing requirements in ITRS Analytics. To configure include and exclude filters, see Strategies.

To start the connection between Gateway and ITRS Analytics, you must configure the ITRS Analytics connection in the Publishing settings in the Gateway Setup Editor. For more information, see ITRS Analytics connection configuration.

Gateway self-monitoring, which is enabled by default, creates a dataview called ITRS Analytics Connection that shows the current state of ITRS Analytics publishing if the ITRS Analytics Connection has been configured. For more information, see Self-monitoring.

View ITRS Analytics data in Active Console Copied

If the Gateways connected to your Active Console publish data to ITRS Analytics, then those Gateways will share the ITRS Analytics connection details with Active Console so you can create history charts by querying data in ITRS Analytics.

To allow a connected Active Console to access ITRS Analytics data, you must configure the ITRS Analytics connection in the Data access settings in the Gateway Setup Editor.

In Active Console, you must also ensure that Tools > Settings > General > Default data source is set to ITRS Analytics.

Self-monitoring Copied

When ITRS Analytics publishing is configured on a Gateway, self-monitoring statistics are reported in two dataviews under Gateway Info > ITRS Analytics.

Detail dataview Copied

Summary dataview Copied

ITRS Analytics connection configuration Copied

Basic configuration Copied

The ITRS Analytics connection section of the GSE provides the following options:

Statistics only mode Copied

Enable the statisticsOnly mode before publishing to estimate the data volume that will be published to ITRS Analytics. This helps you determine the required ITRS Analytics cluster size.

Running this mode is valuable for understanding data volume, throughput rates, and network bandwidth requirements before enabling actual publishing.

Statistics are recorded to the self-monitoring dataviews and to the Gateway log file.

Connection mode Copied

The ITRS Analytics connection configuration is divided into two distinct functions:

Publishing — The Gateway acts as a data producer, sending metrics, events, and logs to ITRS Analytics via the ingestion service. This is a write-only operation using gRPC over HTTP/2.

Data access — The Gateway uses this connection to retrieve historical data from ITRS Analytics to serve to connected Active Consoles for charting and analysis, and to publish commands to ITRS Analytics for execution via the Entity Viewer. This connection uses HTTPS REST APIs. For more information, see publish and execute Gateway commands in ITRS Analytics.

These are independent configurations because:

• Different credentials may be required (ingestion service account vs data access user account) as different Gateways may publish data to ITRS Analytics, while only specific Gateways may need to read data from ITRS Analytics. This follows the principle of least privilege.
• Different network paths may be used (direct ingestion vs web console access).
• Different proxy configurations may apply.
• Publishing can be enabled without data access (one-way data flow).
• Data access can be enabled without publishing (using published data from another Gateway).

Connection mode configuration fields Copied

Proxy configuration Copied

ITRS Analytics connection settings support proxy configuration at both Gateway and Netprobe levels. This hierarchical configuration system allows for:

• Centralized defaults, as common settings are configured once at the Gateway level.
• Flexible overrides, as individual probes or groups of probes can be customized as needed.
• Network segmentation, as different probes can use different proxies or direct connections.
• Security flexibility, as probes in different environments can use different credentials.

Gateway-level proxy settings are configured in the ITRS Analytics Connection section of the GSE. These settings are automatically inherited by all Netprobes connected to the Gateway, unless specifically overridden at the individual probe or probe group level.

There are two types of proxy configurations available:

• Publishing proxy — for data publishing to ITRS Analytics.

  Expand table

  Setting	Description
  Host	Hostname or IP address of the proxy server.
  Port	Port number of the proxy server.
  Authentication	Optional proxy authentication. This can be set to None, or you can specify a username and password.

• Data access proxy — for accessing ITRS Analytics data.

  Expand table

  Setting	Description
  Host	Hostname or IP address of the proxy server.
  Port	Port number of the proxy server.
  Type	Proxy protocol type. Select from: HTTP — standard HTTP proxy HTTPS — secure HTTP proxy HTTP 1.0 — HTTP proxy using version 1.0 protocol SOCKS 4 — SOCKS version 4 proxy SOCKS 5 — SOCKS version 5 proxy SOCKS 4A — SOCKS version 4A proxy SOCKS 5 Hostname — SOCKS version 5 with hostname resolution
  Authentication	Optional proxy authentication. This can be set to None, or you can specify a username and password.

Probe-level configuration overrides Copied

ITRS Analytics connection settings configured at the Gateway level are automatically propagated to all connected Netprobes and Self-Announcing Netprobes (SAN probes). However, these settings can also be overridden at the probe and probe group level as needed.

If you do not need to override the Gateway settings, no configuration is needed in the GSE.

Probe-specific ITRS Analytics connection settings can be configured in the Probe > ITRS Analytics Connection section of the GSE. Enable Override IAX Connection and the specific connection settings you want to configure at the probe level.

Self-Announcing Netprobes (SAN probes) configuration Copied

Self-Announcing Netprobes (SAN probes) are Netprobes that can be deployed on any host without prior Gateway configuration. SAN probes have enhanced ITRS Analytics connection configuration capabilities:

• Inheritance of the ITRS Analytics configuration from the Gateway — SAN probes automatically receive the ITRS Analytics connection configuration from the Gateway, including proxy settings and credentials.
• Netprobe setup file configuration — SAN probes can read ITRS Analytics connection settings from their Netprobe setup file, allowing for probe-specific configuration that overrides Gateway defaults.
• Advanced settings propagation — advanced ITRS Analytics publishing settings configured at the Gateway-level are automatically propagated to SAN probes.

You can configure ITRS Analytics Connection settings once at the Gateway level, and they will automatically apply to all SAN probes in your environment. This ensures that SAN probes can fully participate in ITRS Analytics data publishing while maintaining the flexibility to use probe-specific configuration when needed.

Configuration examples Copied

The following examples demonstrate common ITRS Analytics connection configuration scenarios. You can also refer to these examples when configuring the setup file of a SAN probe to override specific settings.

Gateway with publishing proxy (authentication):

<iaxIngestionConnectionInfo>
  <serviceAddress>https://ingestion.example.com</serviceAddress>
  <credentials>
    <username>ingestion-api</username>
    <password>your-password</password>
  </credentials>
  <proxy>
    <proxyServer>
      <host>proxy.company.com</host>
      <port>8080</port>
      <authentication>
        <password>
          <username>proxy-user</username>
          <password>proxy-password</password>
        </password>
      </authentication>
    </proxyServer>
  </proxy>
</iaxIngestionConnectionInfo>

Data access with SOCKS proxy (with type selection and authentication):

<dataAccess>
  <serviceAddress>https://analytics.example.com</serviceAddress>
  <credentials>
    <username>data-access-user</username>
    <password>data-access-password</password>
  </credentials>
  <proxy>
    <proxyServer>
      <host>socks-proxy.company.com</host>
      <port>1080</port>
      <type>
        <socks_5/>
      </type>
      <authentication>
        <password>
          <username>proxy-user</username>
          <password>proxy-password</password>
        </password>
      </authentication>
    </proxyServer>
  </proxy>
</dataAccess>

Probe overriding Gateway credentials and proxy:

<probe name="special-probe">
  <iaxIngestionConnectionInfo>
    <credentials>
      <override>
        <username>probe-specific-user</username>
        <password>probe-specific-password</password>
      </override>
    </credentials>
    <proxy>
      <override>
        <host>different-proxy.company.com</host>
        <port>3128</port>
        <authentication>
          <none/>
        </authentication>
      </override>
    </proxy>
  </iaxIngestionConnectionInfo>
</probe>

Probe disabling inherited proxy:

<probe name="direct-connection-probe">
  <iaxIngestionConnectionInfo>
    <proxy>
      <none/>
    </proxy>
  </iaxIngestionConnectionInfo>
</probe>

Probe overriding advanced settings (block override):

<probe name="custom-advanced-probe">
  <iaxIngestionConnectionInfo>
    <advancedPublishingSettings>
      <override>
        <rpcTimeout>10000</rpcTimeout>
        <throttle>30</throttle>
        <batchSize>1000</batchSize>
        <batchTimeout>1000</batchTimeout>
        <queueSize>100000</queueSize>
        <auditQueueSize>5000</auditQueueSize>
        <statisticLogging>
          <filename>probe-specific-stats.log</filename>
          <maxSize>2048</maxSize>
          <interval>300</interval>
        </statisticLogging>
      </override>
    </advancedPublishingSettings>
  </iaxIngestionConnectionInfo>
</probe>

Advanced configuration Copied

The Advanced publishing settings allow you to fine-tune the Gateway’s publishing behavior for optimal performance and reliability. These settings control batching, queuing, timeouts, and diagnostic logging.

Note

Most users should start with default values. Only adjust these settings after understanding your specific requirements through monitoring the self-monitoring dataviews and analyzing publishing statistics.

Below are some possible situations when to adjust advanced settings:

• High-volume environments — environments with thousands of dataviews or sub-second sampling intervals.
• Network constraints — high-latency networks or bandwidth-limited connections.
• Reliability requirements — situations requiring guaranteed delivery or specific back-pressure handling.
• Troubleshooting — diagnosing publishing issues or capacity planning.

Data generation → Batching → Queue → Network transmission → ITRS Analytics

Audit event → Disk-persisted queue → Network transmission → ITRS Analytics

Probe-level advanced publishing settings overrides Copied

Advanced ITRS Analytics publishing settings configured at the Gateway level are automatically propagated to all connected Netprobes and Self-Announcing Netprobes (SAN probes). This ensures consistent configuration across the entire monitoring infrastructure while still allowing probe-specific overrides when needed.

No configuration is needed in the GSE if you do not need to override the Gateway settings.

If you need to override the inherited advanced ITRS Analytics publishing settings, enable Override IAX Connection and Advanced publishing settings from the probe configuration.

Individual probes can override the advanced publishing settings configured on the Gateway as a block override. Individual advanced settings cannot be selectively overridden. You need to configure all of the following settings:

• RPC Timeout
• Batch size
• Batch timeout
• Queue size
• Statistic Logging
  • Filename
  • Max size
  • Interval

Important

When overriding advanced publishing settings at the probe level, you must specify all advanced configuration values required. Any advanced settings not explicitly configured in the probe override will use their default values, not the configured values from the Gateway.

Controlling publishing Copied

By default, when ITRS Analytics publishing is enabled, all dataviews from all managed entities are published. However, you can control publishing at a granular level using several mechanisms.

Strategies Copied

The primary mechanism for controlling what data is published is through setting up strategies. Strategies allow you to:

• Include specific dataviews — publish only specific samplers, managed entities, or dataviews using XPath targets.
• Exclude specific dataviews — prevent specific data from being published while publishing everything else.
• Combine filters — use multiple strategies together for fine-grained control.

Note

If you specify both include filters and exclude filters, a data item is published if it is selected (directly or as an ancestor or descendant) by at least one include target and it is not selected (directly or as a descendant) by any exclude target.

Below are examples on using include and exclude filter strategies:

1. Use an exclude filter strategy targeting to prevent all test or development managed entities from publishing.

2. Use an include filter strategy to publish only production monitoring data from production managed entities.

3. Use an exclude filter to prevent publishing of a specific sampler that generates high data volumes but provides limited value in ITRS Analytics.

Strategy Group Copied

Strategies may be grouped for organisational purposes. This has no effect on their application but is useful for grouping categories and making them easier to find in the navigation tree.

You must specify a name when creating a strategy group.

Dataview-level publishing Copied

You can control publishing to ITRS Analytics at the dataview level by enabling publishing for each dataview that you want to publish. This is useful if you want to publish only specific dataviews with relevant data, rather than publishing everything.

Important

Not all Geneos dataviews are immediately suitable for ingestion and analysis in ITRS Analytics.For example, some plugins such as toolkit-like plugins (Toolkit, SQL Toolkit) have unknown columns and data types, requiring you to define the data schema before publishing. Data may not appear as expected if schemas are not explicitly defined.

Dataview schemas are defined under the Publishing tab of a sampler configuration in the Gateway Setup Editor.

1. Ensure you have configured the ITRS Analytics connection in your Gateway.

2. Navigate to the Publishing tab in your sampler configuration in the Gateway Setup Editor.

3. Click Add new in the Dataviews section.

4. Specify the name of the dataview that you want to publish to ITRS Analytics.

5. Select the data schema type.

   • If specifying a data schema, click the Data menu and ensure that the Publish option is checked.
   • If specifying a sampler schema static variable, ensure that the Publish option is checked in the sampler schema static variable configuration.

   

FKM-specific publishing Copied

The File Keyword Monitor (FKM) plugin often monitors log files that:

• Generate extremely high data volumes (millions of lines per day).
• Contain sensitive information that should not be sent to ITRS Analytics.
• Are relevant only for local troubleshooting, not long-term analytics.

The log data collected by the FKM plugin can be published directly to ITRS Analytics from the Netprobe. The data does not go via the Gateway. Publishing to ITRS Analytics can be controlled at the file level:

1. Configure the ITRS Analytics connection in your Gateway. The Netprobe uses the same connection parameters as the Gateway, unless overridden in the ITRS Analytics Connection section of the Probe or Probe group settings in the Gateway Setup Editor.

2. Enable publishing for each monitored FKM file in the Gateway Setup Editor. See FKM ITRS Analytics publishing.

   ITRS Analytics publishing is enabled:

   ITRS Analytics publishing is not enabled:

ITRS Analytics data governance and filters Copied

In addition to Gateway-side filtering strategies, ITRS Analytics provides its own data governance features.

The following features are available in the ITRS Analytics Ingestion app:

• Geneos filters — apply filters in ITRS Analytics to manage data points from Geneos after ingestion.
• Data retention policies — control how long different types of data are stored.
• Eviction rules — define when inactive entities and their data will be removed.

Consider using a combination of Gateway-side and ITRS Analytics-side controls for comprehensive data management.

Best practices for ITRS Analytics publishing Copied

• Start with exclude-by-default — use include filters to publish only what you need, rather than excluding what you do not need.
• Monitor self-monitoring dataviews — watch metricsDropped and metricsChanged to identify data quality issues.
• Test with statisticsOnly mode — understand your data volume before enabling publishing.
• Define schemas for custom dataviews — avoid type detection issues.
• Use Collection Agent for new integrations — Collection Agent provides explicit, well-defined data models optimized for ITRS Analytics.
• Review toolkit dataviews — many toolkit plugins were designed for real-time Active Console viewing, not long-term analytics storage.
• Consider data lifecycle — not all data needs the same retention period. Use ITRS Analytics data retention policies to age out high-volume, short-lived data.
• Coordinate with ITRS Analytics administrators — discuss cardinality limits, retention policies, and ingestion quotas before publishing large-scale data.

ITRS Analytics Ingestion Proxy Copied

Ingestion proxy can be used to funnel data from locally running Gateways and Netprobes to remote ITRS Analytics ingestion services.

By implementing a proxy server, Netprobes and Gateways can connect internally to the proxy, which facilitates a secure outbound connection to hosted ITRS Analytics instances. It can be used for your instance or to connect to the SaaS instance. This method improves security by reducing the risk involved in directly connecting the network to external connections.

The ingestion proxy consists of the Collection Agent and gRPC plugin which receive data from Gateways and Netprobes, and report it to one or more ITRS Analytics instances.

Set up the Collection Agent as a proxy server Copied

Configure the gRPC plugin Copied

Configure your gRPC plugin using the following reference configuration. For the proxy server to work, provide values on the collectors and reporters parameters. Ensure values for the following are provided:

- `collectors` > `port`
- `reporters` > `tcp` > `hostname` and `port`
- `reporters` > `ingestion-reporter` > `hostname`, `port`, `username`, and `password`

plugin-directory: ${env:COLLECTION_AGENT_DIR}/plugins

monitoring:

  # Optional. Defaults to true.
  enabled: true

  # Agent self metrics.
  self-metrics:

    # Whether to enable self metric collection (optional, defaults to true).
    enabled: true

    # Dimensions to add to all self metrics from this agent (optional).
    dimensions:
      app: ingestion-proxy

collectors:
  - name: internal-grpc
    type: plugin
    class-name: GrpcInternalIngestionServiceCollector
    port: ${env:GRPC_PORT}
    # Optional. Settings to allow password authentication of Gateway
    # Remove the authentication section if you do not require gateways to authenticate with the proxy
    authentication:
      iam:
        scheme: https
        hostname: ${env:IAM_HOST}
        # port:  ${env:IAM_PORT}
        client-id: ingestion
        client-secret: ${env:IAM_CLIENT_SECRET}
        # the following setting is required, even though it will not be used
        admin-realm: master
        client-realm: obcerv
      allowed-users: [ ingestion-api ]
    thread-pool-size: 2

    # Optional. Use to enable TLS.
    # Remove the tls-config section if you do not require TLS connections between the gateway and the proxy
    tls-config:
      cert-file: ${env:PROXY_CERTIFICATE}
      key-file: ${env:PROXY_KEY}

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

  - type: plugin
    class-name: GrpcInternalIngestionServiceReporter
    name: ingestion-reporter

    hostname: ${env:INGESTION_HOST}
    port: ${env:INGESTION_PORT}
    username: ${env:INGESTION_USER}
    password: ${env:INGESTION_PWD}

    # Optional. Switch compression on/off. Defaults to true.
    use-compression: true

    # Optional. gRPC call deadline in milliseconds. Defaults to 3000ms.
    call-deadline: 3000

    # use-plain-text: true

    # Optional. Used only when use-plain-text is false (the default) and mTLS is desired,
    # else the client trusts whatever public key it receives from the server during the
    # TLS handshake.
    tls-config:
    # # Optional. Used for mTLS and trusted server TLS (i.e. contains trusted server keys).
      trust-chain-file: ${env:OBCERV_CA_CERTIFICATE}
    #   # Optional. List of TLS protocols to enable. Defaults to TLSv1.3 and TLSv1.2 only.
    #   protocols: [ TLSv1.3, TLSv1.2 ]

    # Optional. Explicitly switch on/off grpc level retries. Defaults to no explicit setting and therefore grpc default.
    # Unable to find property 'grpcRetries' on class: com.itrsgroup.collection.plugins.grpc.reporters.ingestion.GrpcInternalIngestionServiceReporterConfig$Batch
    # grpc-retries: true

    # Optional. Set a grpc idle timeout. Default is to not explicit set an idle timeout which means the channel
    # inherits the default, which is currently 30 minutes.
    # grpc-idle-timeout: 100000000

    #
    # Batch configuration per endpoint type.
    #
    # It is not necessary to configure any batching at all (including the common-batch block)
    # in which case the defaults are as specified in the common-batch block.
    #
    # Endpoint specific batch configuration can be used to override the default and common-block
    # attributes.
    #

    # Optional. Common batch configuration for all endpoints unless overridden below.
    common-batch:
      # Optional. In memory buffer capacity. Defaults to 2 * the batch size. Must be greater than the batch size.
      # A larger in memory buffer gives some level of protection against a receiver that is either generally slow, or
      # is slow to recover after a transient outage AND the producer is not producing at a significantly higher rate than
      # can be handled by the receiver.
      # buffer-capacity: 2048

      # Optional. Switch on asynchronous reporting. Defaults to false.
      # In asynchronous mode batches are sent without awaiting completion of the previous batch which allows for
      # interleaved reporting. This results in higher throughput at the cost of batches potentially being received out
      # of order.
      # async-mode: false

      # Optional. Retry interval in milliseconds when in synchronous reporting mode. Defaults to 500 ms.
      # retry-interval: 500

    # Optional. Override metrics batch configuration.
    # If present then any common configuration is ignored (i.e. individual attributes are not inherited).
    metrics-batch:
      size: 500
      timeout: 200
      max-retries: 0

    # Optional. Override logs batch configuration.
    # If present then any common configuration is ignored (i.e. individual attributes are not inherited).
    logs-batch:
      size: 100
      timeout: 1000
      max-retries: 10

    # Optional. Override events batch configuration.
    # If present then any common configuration is ignored (i.e. individual attributes are not inherited).
    events-batch:
      size: 100
      timeout: 1000
      max-retries: 10

    # Optional. Override attributes batch configuration.
    entity-attributes-batch:
      size: 500
      timeout: 1000
      max-retries: 10

  - type: routing
    name: routing-table
    route-eviction-timeout: 2000
    route-restoration-timeout: 60000
    route-type: all
    ignore-no-matching-route: true
    routes:
      - reporter: ingestion-reporter
        do-not-evict: true
        match: any
        matchers:
          - type: property
            key: gateway
            pattern: .*
      - reporter: tcp
        do-not-evict: true
        match: all
        matchers:
          - type: dimension
            key: app
            pattern: ingestion-proxy
          - type: property
            key: gateway
            pattern: .*
            exclude: true

workflow:
  metrics:
    reporter: routing-table
    max-retries: 0
    pass-through:
      enabled: true
      concurrency: parallel
      fire-and-forget: true

  logs:
    reporter: routing-table
    max-retries: 0
    pass-through:
      enabled: true
      concurrency: parallel
      fire-and-forget: true

  events:
    reporter: routing-table
    max-retries: 0
    pass-through:
      enabled: true
      concurrency: parallel
      fire-and-forget: true

  attributes:
    reporter: routing-table
    max-retries: 0
    pass-through:
      enabled: true
      concurrency: parallel
      fire-and-forget: true
  traces:
    enabled: false

Start the ingestion proxy Copied

1. Use the include file ingestion-proxy.sh to start the proxy.

Note

Ensure that ingestion-proxy.sh and ingestion-proxy.yaml are in the same directory. Additionally, ensure that there is a Collection Agent directory that contains the Collection Agent and the Collection Agent plugin directory. This can be done by copying the collection-agent directory from the Netprobe package.

2. Edit the bash script:

OPTIONAL: Disable gateway authentication
Remove IAM_HOST and IAM_CLIENT_SECRET from ingestion-proxy.sh and remove the iam-config block in the internal-grpc collector in ingestion-proxy.yaml.

OPTIONAL: Disable TLS connections between gateway and the proxy
Remove PROXY_CERTIFICATE and PROXY_KEY. Additionally, remove the tls-config block in the internal-grpc collector in ingestion-proxy.yaml.

Set up Gateway to establish a connection with ITRS Analytics Copied

The include file obcerv-via-proxy.xml allows Gateways to connect to ITRS Analytics via the proxy. This file should be used by all Gateways that publish to ITRS Analytics. Refer to Include files for guidance on setting up include files in the Gateway Setup Editor.

Change the following settings based on the location and changes to the Collection Agent proxy:

• hostname and port of the ingestion service (Publishing > service address)
• location of the proxy server certificate (if required) (Publishing > Root certificates)

Note

Data access is either direct or via a normal HTTP proxy that supports HTTP/2 and needs to be set in the file.

To start the connection between Gateway and ITRS Analytics, configure the Publishing > ITRS Analytics connection settings in the Gateway Setup Editor. Refer to the ITRS Analytics connection configuration section.

You need to fill in the Data access section in order to use Gateway Commands, Adaptive Rules, or the Forecaster app in ITRS Analytics. Your ITRS Analytics connection settings should look like this:

Connect Netprobe to Collection Agent (Monitoring Proxy Service) Copied

The include file ingestion-proxy-monitoring.xml is for monitoring the ITRS Analytics proxy service. Only one Gateway needs this file, which will be the sole Gateway that will monitor the ITRS Analytics proxy. It also requires a Netprobe which will run on the server specified in ingestion-proxy.sh.

Note

• The probe host of the Netprobe should be updated to match the server used (TCP_REPORTER_HOST).
• The port where the Gateway connects to the Netprobe should match the port that the Netprobe listens on (-port flag).
• The port that the Netprobe listens to for tcp connections from the Collection Agent should be changed to match the port defined in ingestion-proxy.sh (TCP_REPORTER_PORT).

The include file ingestion-proxy-monitoring.xml contains the following sections:

1. Mapping — a Dynamic Entity mapping named Ingestion-proxy which processes the following custom mappings:

   • Filters — determine which datapoints are processed by which mapping. Values set are:

     • Label — app
     • Options — equals
     • Value — ingestion-proxy

       Note

       The values are similar to the TcpReporter you previously defined.

   • Geneos items — when a mapping is applied, the Geneos items fields determine how the labels of each datapoint are used to create Dynamic Entities and other items in the Geneos tree structure. Values set are:

     • Labels — hostname, app
     • Options — entity, sampler
     • Entity — when entity is set in options, value in this field is: Required: true, Use in display name: true

       Note

       The dimensions and properties of datapoints are both referred to as labels when creating custom mappings.

2. Collection Agent parameters — an unmanaged Collection Agent parameter named Ingestion Proxy which defines how the Collection Agent should run. The value of the Reporter port is 19137, which is the port the Netprobe should listen on to communicate with the Collection Agent using the TcpReporter.

3. Mapping type — a mapping type named Ingestion proxy, wherein the mapping Ingestion-proxy is specified.

Adding a new probe Copied

Set up a new probe following the steps below:

1. Create a new probe and provide the name, hostname, and port.

   

2. Select the Dynamic Entities tab. Specify the mapping type and Collection Agent parameters that the Netprobe must use.

   

You should now be able to check the data coming in from the Collection Agent Ingestion Proxy through your Active Console.

Troubleshooting ITRS Analytics connectivity Copied

This section provides systematic troubleshooting steps for common ITRS Analytics publishing issues. Every connectivity, data quality, or volume issue should be cross-checked against this documentation to identify potential misconfigurations or missing requirements.

Diagnostic checklist Copied

When experiencing any ITRS Analytics publishing issue, systematically check:

• Self-monitoring dataviews — review all metrics under Gateway Info > ITRS Analytics.
• Gateway logs — search for “ITRS Analytics”, “gRPC”, or “ingestion” errors.
• Connection status — connectionStatus should be Ready, not Transient Failure or Shutdown.
• Access token — accessTokenAvailable should be Yes.
• Infrastructure support — all network devices support gRPC and HTTP/2.
• Certificates — properly configured and not expired.
• Credentials — correct username/password with appropriate permissions.
• Proxy — if used, correctly configured and supports gRPC.
• Strategies — not filtering required data.
• Data types — explicit schemas defined for published dataviews.
• Data volume — within expected limits (use statisticsOnly mode to test).
• Network path — no firewalls blocking outbound HTTPS.
• ITRS Analytics health — ingestion service operational (check with ITRS Analytics administrator).

Common examples of connection issues Copied

Symptom: connectionStatus shows “Failed” Copied

Possible causes and solutions:

1. HTTP/2 or gRPC not supported by infrastructure

   • Check: Verify all load balancers, proxies, and network devices between Gateway and ITRS Analytics support HTTP/2 and gRPC.
   • Solution: Review network infrastructure requirements and enable gRPC on all intermediate devices.

2. Certificate issues

   • Check: Look for SSL/TLS errors in Gateway logs.
   • Solution: Verify certificate configuration in Root certificates.
   • Common issues:
     • Certificate expired
     • Wrong certificate (server cert instead of CA cert)
     • Certificate format incorrect (not PEM)
     • Certificate path incorrect
   • Verification: Check accessTokenAvailable in self-monitoring. No indicates authentication/certificate issues.

3. Network connectivity

   • Check: Can the Gateway host reach the ingestion service?
   • Firewall: Ensure outbound HTTPS (port 443) is allowed.
   • DNS: Verify the ingestion hostname resolves correctly.

4. Proxy misconfiguration

   • Check: If using a proxy, verify proxy configuration is correct.
   • Solution: Test proxy connectivity separately.
   • Common issues:
     • The proxy doesn’t support gRPC/HTTP/2.
     • The proxy authentication credentials are incorrect.
     • The proxy hostname or port is wrong.

5. Incorrect credentials

   • Check: accessTokenAvailable = No in self-monitoring summary dataview.
   • Solution: Verify credentials in publishing credentials.
   • Test: Try the same credentials via ITRS Analytics web console or API.
   • Common issues:
     • Wrong username/password
     • Account doesn’t have ingestion permissions
     • Account disabled or expired

Symptom: Data not appearing in ITRS Analytics Copied

Possible causes and solutions:

1. Publishing is disabled or in statisticsOnly mode

   • Check: Verify that the Mode is set to connection, not statisticsOnly.
   • Check: Verify that the Enabled setting is checked.

2. Data filtered by strategies

   • Check: Review strategies configuration.
   • Solution: Check if your dataviews match exclude filters or don’t match include filters.
   • Test: Temporarily remove all strategies to verify data flows without filters.

3. Data throttled

   • Check: dataviewsUnpublished in self-monitoring summary dataview. Dataviews without severity are throttled by default for 20 seconds.
   • Solution: Adjust throttle setting or add severity to cells you want published at full rate.

4. Schemaless dataview type mismatches

   • Check: metricsDropped > 0 in self-monitoring summary dataview. Dataview cells changing types (number ↔ string) cause metrics to be dropped.
   • Solution: Define explicit schemas for dataviews.

5. Messages dropped due to queue overflow

   • Check: messagesDroppedPerSample > 0 in self-monitoring detail dataview. If so, data generation rate exceeds the transmission rate.
   • Solutions:
     • Reduce data volume by using filters.
     • Increase queue size.
     • Investigate network bandwidth limitations.
     • Check ITRS Analytics ingestion rate limits.