Geneos ["Geneos"]

Obcerv Quickstart Guide


You can configure Gateway to publish data to Obcerv.

Obcerv is the successor product to Gateway Hub, however there are important conceptual differences between Gateway Hub and Obcerv.

Intended audience

This guide is intended for Geneos users that want to connect to an existing Obcerv instance.

For a more complete reference for Obcerv publishing, see Obcerv Connection.

Obcerv concepts

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


In Obcerv an Entity is defined as an object that contains metrics with identical dimensions and metrics are each uniquely defined by a set of dimensions and a metric name. The following metric types exist: GAUGE, ENTITY_ATTRIBUTE, COUNTER, HISTOGRAM, STATUS_METRIC.

Entities can also have attributes associated with them but this does not effect the definition of an entity. Obcerv allows users to search for entities metrics using both dimensions and attributes.

Geneos structures are mapped to Obcerv entities, attributes and metrics.

Consider an example:

Geneos item Entity dimensions Attributes Metrics
Managed Entity probe=itrspc101 ConState=Up  
Managed Entity managedEntity=pc101  
Managed Entity   COUNTRY=UK  
Managed Entity   OS=Linux  
Managed Entity   DEPT=SALES  
Sampler probe=itrspc101 Plugin Name=CPU  
Sampler managedEntity=pc101 Group Name=Infra  
Sampler sampler=CPU    
Sampler type=LinuxInfra    
Dataview probe=itrspc101   numCpuCores
Dataview managedEntity=pc101   numOnlineCpus
Dataview sampler=CPU   loadAverage1Min
Dataview type=LinuxInfra   loadAverage5Min
Dataview dataview=CPU    
Row probe=itrspc101   type
Row managedEntity=pc101   clockSpeed
Row sampler=CPU   percentUtilisation
Row type=LinuxInfra   percentUserTime
Row dataview=CPU   percentIdle
Row row=cpu_0    

In general, traditional Geneos data generates the following Obcerv 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 Obcerv 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 Obcerv 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 Obcerv 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 published as ATTRIBUTES.

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

Data labels

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

  • Dimensions: these are the name-value pairs used to uniquely identify an Obcerv Entity.

  • Attributes: these are observed pieces of information about an Obcerv 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 Obcerv entities in the namespace. Gateway also sends each sampler's Group and PluginName as ENTITY_ATTRIBUTE metrics on the Obcerv entity that represents that sampler.

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


Gateway sends severity changes to Obcerv 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 Obcerv


Gateway sends audit events to Obcerv 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.

Publish from Gateway to Obcerv

You can publish data from Gateway to Obcerv via the Ingestion service. The DNS name used to access this service is provided as part of the Obcerv configuration file.

In the following examples we use:


TLS certificates

The ingestion service is exposed via the cluster’s ingress service which provides a secure HTTPS connection. For a Gateway to connect to Obcerv, a PEM file or string of the root CA certificate used to sign the ingestion service certificate is required.

If the root CA certificate is already trusted by the Gateway's host then this step can be skipped.

Otherwise, the CA certificate must be fetched from Obcerv. To do this:

  1. Log in to the Web Console as a user with the admin role.

  2. Open the Certificates tab of the Admin page.

  3. Copy the CA certificate.

Ingress authentication

The ingestion service requires a username and a password to be provided. By default, the username is ingestion-api and the password is ingestion.

The Obcerv administrator should change the default using Keycloak. A user configuring Gateway should contact their administrator for the correct credentials.

Configure Gateway to Obcerv publishing

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

  1. Click the Obcerv connection node in the navigation tree and select yes when asked to create the section.

  2. Specify the Service address in the Publishing section. This is the ingestion DNS name with the https:// prefix, so in this example: https://ingest.hub.local:443.

  3. Under Credentials in the Publishing section, set the ingestion username as the Username and the ingestion password as the Password.

  4. Under Root certificates select pemString, and provide the CA Certificate PEM string.

  5. Click Save current document.

Note: The service address field defaults to https and port 443, so that https://ingest.hub.local:443 can be entered as ingest.hub.local.

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

Publish from Netprobes to Obcerv

You can publish data from a Netprobe to Obcerv via the Ingestion service. To do this, you must first configure the Obcerv connection in your Gateway then configure a Publisher sampler. The Publisher sampler will inherit all required ingestion service settings from the Gateway.

  1. Select Samplers in the navigation tree, then click New Sampler.

  2. Specify a Name for the sampler.

  3. Set the destination field to Obcerv.

  4. Add this sampler to the Managed Entities of your choice.

View Obcerv data in Active Console

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

  1. Click the Obcerv connection node in the navigation tree and select yes when asked to create the section.

  2. Specify the Service address in the Data access section. This is the DNS name with the http:// prefix, so in this example http://hub.local.

  3. Under Credentials in the Publishing section, set the ingestion username as the Username and the ingestion password as the Password.

  4. Click Save current document.


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

Detail dataview

Name Description
name Name of the data type.
sendState Either SENDING or BUFFERING.
deliveryStatus Delivery status of the last message. This can be either NONE, SUCCEEDED, RETRYING or FAILED.
byteRate Transfer rate in bytes per second.
messagingRate Total transfer rate in messages per second across all three queues.
maxBufferSize Maximum number of buffered messages.
messagesInBuffer Current number of messages in the buffer.
messagesDroppedPerSample Number of messages dropped in the last sampler.

Summary dataview

Name Description
enabled The Obcerv connection can be either Enabled or Disabled
connectionStatus Shows the connection status. This can be either Statistics only, Idle, Ready, Connecting, Transient Failure, or Shutdown.
messageRate Transfer rate per queue in messages per second.
byteRate Transfer rate in bytes per second.
messagesDroppedPerSample Average number of messages dropped per sampler.
dataviewsPublished Number of dataviews published.
dataviewsUnpublished Number of dataviews unpublished.
dataviewsWithErrors Number of dataview with errors.

Obcerv user associated with the access token used to connect to Obcerv.

Note, this is not an application key. Access tokens are short lived tokens used to secure connections.

accessTokenAvailable Status of access tokens.