Connect Geneos to ITRS Analytics

ITRS Obcerv is now ITRS Analytics

Beginning with Geneos 7.2.0, the Gateway Setup Editor (GSE) now displays Obcerv as ITRS Analytics to reflect the rebranding.

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 — the Gateway publishes monitoring data to ITRS Analytics. This is a write-only operation that uses gRPC over HTTP/2.
• Data pipeline — the 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.

Prerequisites Copied

Before configuring Gateway to publish data to ITRS Analytics, ensure the following:

• Upgrade the Gateway to version 7.0.0 or later, as earlier versions are not supported for publishing to ITRS Analytics.
• Ensure the network infrastructure supports HTTP/2 and gRPC.
• Provide valid ITRS Analytics ingestion service credentials.

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

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.

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

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 sanitized 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

ITRS Analytics connection configuration Copied

Understand publication limitations before connecting

Before enabling ITRS Analytics publishing, review the Controlling publishing and Best practices for ITRS Analytics publishing sections. Understanding publication limitations, filtering strategies, and best practices upfront will help you avoid publishing unnecessary or unsuitable data and ensure optimal performance and cost management.

Data from the Gateway is published 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 and minimize downstream data processing requirements in ITRS Analytics. To configure include and exclude filters, see Strategies and Dataview-level publishing.

The ITRS Analytics connection section of the Gateway Setup Editor provides the following options:

Statistics only mode Copied

Enable the statisticsOnly mode before publishing to ITRS Analytics. Running this mode is valuable for understanding data volume, throughput rates, and network bandwidth requirements before enabling actual publishing. This helps you determine the required ITRS Analytics cluster size.

Statistics are recorded to the self-monitoring dataviews and to the Gateway log file. Logs are generated every 10 minutes and include audit events, entity attributes, events, metrics, and the total number of messages sent and dropped.

Example Copied

Given the following Gateway log example:

• Data from the Gateway log: 22,486 total messages sent over the past 10 minutes
• Message rate: total messages sent ÷ 600 seconds (10 minutes) = 37.5 messages per second

Use the ITRS Analytics sizer tool to determine the cluster size that can accommodate the calculated message rate. In this case, the smallest cluster size, Micro, meets the requirement as it can handle up to 3,000 messages compared to the calculated rate of 37.5 messages per second.

Tip

After determining your ITRS Analytics cluster size, you can continue using the ITRS Analytics sizer tool to enter your configuration details, cluster type, and the ITRS Analytics apps you intend to install. Afterwards, click Calculate to determine the minimum requirements needed to set up your ITRS Analytics cluster.

Test small-scale Gateway publishing Copied

Important

Before enabling ITRS Analytics publishing across your entire environment, test publishing using a small number of Gateways first.

1. Start with a single Gateway — enable statisticsOnly mode on a single Gateway for a few days to establish a baseline and identify any issues.

2. Monitor vital statistics — review the self-monitoring dataviews regularly to check for early warning signs:

   • connectionStatus — check for Transient Failure or Shutdown status, indicating connection or ingestion issues.
   • messagesDroppedPerSample — increasing values indicate data loss or buffer issues.
   • metricsDropped — metrics dropped due to type mismatches between Geneos cells and schema definitions.
   • dataviewsWithErrors — dataviews experiencing publication errors.
   • messageRate and byteRate — verify these align with your expected data volume and ITRS Analytics cluster sizing.

3. Gradually scale — only after validating that the initial Gateway is publishing successfully with no red flags should you enable publishing on additional Gateways, scaling gradually while continuing to monitor the vital statistics.

This phased approach helps prevent overwhelming the ITRS Analytics system with unexpected data volumes and allows you to identify and resolve publication issues before they affect your entire environment.

Connection mode Copied

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

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

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

Basic configuration - Publishing Copied

To start the connection between Gateway and ITRS Analytics, you must configure the Publishing settings in the ITRS Analytics connection section in the Gateway Setup Editor.

Basic configuration - Data access 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 the 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, ensure that the default data source in your Active Console is set to ITRS Analytics. This can be viewed under Tools > Settings > General > Default data source.

You must also configure the Data access section in the ITRS Analytics connection setting in the Gateway Setup Editor.

Configuring the data access section also allows you to publish Gateway commands to ITRS Analytics and execute them directly from the ITRS Analytics Web Console. For more information, see Configure Geneos commands for ITRS Analytics.

Self-monitoring Copied

Gateway self-monitoring is enabled by default, displaying the current state of ITRS Analytics publishing if the ITRS Analytics connection has been configured. Self-monitoring statistics are reported in two dataviews under Gateway Info > ITRS Analytics.

Detail dataview Copied

Summary dataview Copied

Additional ITRS Analytics connection configuration Copied

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.

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.

Note

Not all Geneos dataviews are suitable for ingestion and analysis in ITRS Analytics. For example:

• The Top plugin uses a positional index as its primary key, so row identities change as processes start, stop, or reorder. This means historical samples cannot be reliably correlated to the same underlying process or entity, which prevents ITRS Analytics from building meaningful time series.
• The Processes plugin configured with a catch‑all regex such as .* will enumerate every process on the host, producing short‑lived rows whose keys and column set change frequently. This results in large, unstable data volumes not suited for efficient storage, aggregation, and analysis in ITRS Analytics.

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.

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.

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 Schemas > 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 does not publish the data row that contains the trigger information to ITRS 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 as shown in the images below. See FKM ITRS Analytics publishing for more information.

   • When ITRS Analytics publishing is enabled:

   • When ITRS Analytics publishing is disabled:

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 to identify data quality issues.
• Test with statisticsOnly mode to understand your data volume before enabling publishing.
• Define schemas for custom dataviews to 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 as many toolkit plugins were designed for real-time Active Console viewing, not long-term analytics storage.
• Consider data lifecycle as 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 to 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. This also allows data-twinning to multiple ITRS Analytics instances.

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.

Diagnostic checklist Copied

When experiencing any ITRS Analytics publishing issue, systematically check:

• Gateway version — Gateway 7.0.0 or later is required. Gateway versions prior to 7.0.0 are not supported for ITRS Analytics publishing and may cause connection failures.
• 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.
• 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: Connection failures or publishing errors with older Gateway versions Copied

• Cause: Gateway versions prior to 7.0.0 are not supported for ITRS Analytics publishing.
• Solution: Upgrade to Gateway version 7.0.0 or later.

Symptom: connectionStatus shows Transient Failure message 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.

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: Look for authentication errors in Gateway logs.
   • Solution: Verify credentials in publishing credentials.
   • Test: Try the same credentials via ITRS Analytics web console.
   • 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.