Obcerv Quickstart

Caution: This page describes a pilot feature.

Overview

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.

Obcerv is currently available as a beta release and any features associated with it should also be considered subject to change.

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

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. 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	HostName=itrspc101.itsgroup.com
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 ObcervEntity.
Attributes: these are observed pieces of information about a 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 itrsgroup.com/geneos/gse 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.

Signals

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

Audit

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:

INGESTION_EXTERNAL_HOSTNAME: ingest.hub.local

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 certificate used by the ingestion service is required.

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

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

Log into the Web Console as a user with the admin role.
Open the Certificates tab of the Admin page.
Copy the 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.

Under the View menu, select Show pilot features.
Click the Obcerv connection node in the navigation tree and select yes when asked to create the section.
Specify the Service address in the Publishing section. This is the ingestion DNS name with the http:// prefix, so in this example http://ingest.hub.local.
Under Root certificates select Pemstring, and provide the Ingress Certificate PEM string.
Under Application key in the Publishing section, set Options to data.
Enter the ingestion username as the Username and the ingestion password as the Password.
Click Save current document.

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.

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.

Select Samplers in the navigation tree, then click New Sampler.
Specify a Name for the sampler.
Set the destination field to Obcerv.
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.

Under the View menu, select Show pilot features.
Click the Obcerv connection node in the navigation tree and select yes when asked to create the section.
Specify the Service address in the Data access section. This is the DNS name with the https:// prefix, so in this example https://hub.local.
Under Application key in the Publishing section, set Options to data.
Enter the ingestion username as the Username and the ingestion password as the Password.
Click Save current document.

Self-monitoring

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