This is documentation for EA software. It may contain information that is out of date and subject to change. Last updated: 3 October 2018.

Publish to Gateway Hub User Guide

Overview

To begin publishing to Gateway Hub after installing and verifying your installation, you need to connect a Geneos Gateway.

After connecting a Gateway to Gateway Hub, you may need to configure schemas for some of your dataviews. Schemas give Gateway Hub information about the type of data being published to it from Geneos.

For information on the installation and set up of Gateway Hub, see Gateway Hub Installation Guide.

This guide describes how to connect a Gateway to Gateway Hub, what schemas are, and how to add a schema definition to a dataview. See Configure the Gateway Technical Reference for the configuration of schemas in the Publishing tab of a sampler in the GSE.

Prerequisites

Ensure you have validated your Gateway Hub installation. See How to validate a Gateway Hub installation.

Existing Geneos Components

Ensure you have at least version 4.8.0. of both Active Console 2 and Gateway.

General Information

Connect a Gateway to Gateway Hub

Connecting a Gateway to Gateway Hub is performed using the Gateway Setup Editor. You need to provide a publishing address and REST address. See How to connect a Gateway to Gateway Hub for procedural information.

Note: Gateway Hub publishing is not available from shared Gateways. Instead, you must enable publishing from the source Gateways.

When you connect a Gateway to Gateway Hub, you may see errors in the form:

Additional <headline/column/row> '<name of headline/column/row> is defined for dataview '<name of dataview>' but no schema has been defined. This dataview will not be published using internal format.

This indicates that a schema definition is required for the sampler the dataview belongs to.

See Schemas for more information regarding schemas.

Schemas

Each dataview that is published to Gateway Hub requires a schema definition.

The schema for a dataview specifies:

There are Built-in schemas and User-defined schemas.

Built-in schemas

The Gateway is packaged with built-in schemas for plug-ins with dataviews containing a set of known column names and data types.

These schemas specify pivoting for dataviews containing rows that have only one value column and the data type of this column varies between the rows (for example, the Hardware Plug-in).

A message is displayed in the Publishing tab of a sampler if a built-in schema exists. See Sampler schema types for a list of samplers with built-in schemas.

You must define schemas if you make changes to the dataviews in these samplers. See Define and view schemas.

User-defined schemas

Schemas must be defined by you for:

Examples where a schema definition is required for pre-existing dataviews:

Schemas are defined in the Publishing tab of the sampler.

Defining schemas can be done entirely manually, or aided with the use of the Propose Schema command.

The Show Current Schema command can be used to view the schemas currently defined for dataviews on a sampler.

See Configure the Gateway Technical Reference for the configuration of schemas in the Publishing tab of a sampler in the GSE.

Special case: pivoted dataviews

Rows added to pre-existing pivoted dataviews must be defined in the Publishing tab of the sampler as if they were additional columns. You do not need to specify the pivot option if there is a built-in schema for the sampler. If you do, and it conflicts with the built-in schema, it is discarded in favour of the user-defined schema.

Define and view schemas

Propose Schema command

The Propose Schema command can be used to aid the generation of schemas. It is useful for adding the schema for:

  • Samplers with dataviews with additional columns and/or rows added using the Compute Engine.
  • Plug-ins where the content is user controlled. For example, the SQL-TOOLKIT, JMX, and TOOLKIT plug-ins.

For a step-by-step guide, see Procedure .

The command generates a suggested XML schema definition for headlines and columns in every dataview in the sampler that are not described in a built-in schema.

Examples of the output of the command:

  • If two columns are added to the CPU sampler, this command generates only the schema definition for those additional columns.
  • A toolkit-like sampler does not have a built-in schema, and therefore the command generates a complete schema definition for the sampler.

It is important to note the following regarding the use of the Propose Schema command:

  • The command attempts to deduce the data types of columns and headlines from each dataview.
  • Units of measure must be supplied post-generation.
  • Any types or units of measure already defined by you in the Publishing tab of a sampler take precedence over those inferred from dataviews by the command.
  • Tables with only two columns are pivoted in the generated XML schema. A comment is included in the XML highlighting this.

The Propose Schema command is available :

  • As a button in the Publishing tab of a sampler in the GSE.
  • By right-clicking on a sampler or dataview in the Active Console 2.

    Note: Running the command on a dataview gives the same result as running on the parent sampler.

Show Current Schema command

The Show Current Schema can be used to view the schemas currently defined for dataviews on a sampler. This can be accessed via the Active Console 2 or in the GSE.

The command opens a window that shows a table per dataview describing the schema defined on the sampler. There is a table for every dataview that has a defined schema, irrespective of whether the dataview is in use. Only dataviews that have a schema definition are shown.

Each table combines information from the built-in schema shipped with the Gateway and any additional information added in the GSE.

A description of the columns shown in each table is below:

Column Name Description
Component Describes if this component is a headline or a column.
Name Name of the headline or column.
Type Data type of the headline or column. The data types are: boolean ; date ; dateTime ; float32 ; float64 ; int32 ; int64 ; string .
Units Unit of measure assigned to this headline or column (if present). For a list of units of measure, see .
Source

Origin of the headline or column and the schema. Cells in this column display one of the following:

  • Base — The built-in schema shipped with the Gateway.
  • Overridden — A built-in schema exists for this headline or column, but has been superseded by the user-defined schema in the Publishing tab of the sampler.
  • Enriched by Compute Engine — Headline or column added to the dataview via the Compute Engine. Schema has been defined in the Publishing tab of the sampler.
  • Defined by User in plugin configuration — Headline or column added to the dataview via a method other than the Compute Engine e.g. a toolkit plug-in. Schema has been defined in the Publishing tab of the sampler.

An example of the output of this command is shown below:

Procedure

How to connect a Gateway to Gateway Hub

To connect the Gateway to the Gateway Hub, follow these steps:

  1. Open Active Console 2.
  2. Double-click the gateway you wish to configure with Gateway Hub. This opens the GSE.
  3. In the GSE, double-click Gateway Hub in the Navigation tree.
    • This creates the Gateway Hub section.
  4. In the Gateway Hub section, add the Publishing address and REST address corresponding to Gateway Hub. See Configure the Gateway Technical Reference for more information about these fields.
  5. Note: The REST address uses https. The default REST address is https://<hostname>:8080/

  6. Click Validate.

    Note: If you see errors in the form:
    Additional <headline/column/row> '<name of headline/column/row> is defined for dataview '<name of dataview>' but no schema has been defined. This dataview will not be published using internal format.
    A schema definition is required for the sampler.


  7. Click Save.

How to use Propose Schema in the GSE

To generate an XML schema definition using the Propose Schema command in the GSE, follow these steps:

  1. Select the desired sampler in the GSE.
  2. Navigate to the Publishing tab of the sampler.
  3. Select Propose Schema.

    Note: If user-defined schema is already present for the sampler, a dialog opens asking you to if you wish to overwrite the schema information.

The generated schema is directly added to the Publishing section. Any existing schema definitions are overwritten.

After using the command, perform the following:

  1. Select Schema > Dataviews > Data.
  2. Review the schema for errors because the data types and pivoting inferred by the Propose Schema command may be incorrect.

    Note: If the value for Pivot is incorrect you must create the schema manually.

  3. Add any units of measure to the headlines and/or columns.

For more information about types, units of measure, and pivoting, see Publish to Gateway Hub - Technical Reference.

It is important to note the following when using the Propose Schema command in the GSE:

  • The command runs against all the samplers with same name on the Gateway. This process can take some time if you have many identically-named samplers.
  • The command times out after 30 seconds.
  • You can cancel waiting for the command result, but this does not stop the command running on the Gateway.

How to use Propose Schema in the Active Console 2

To generate an XML schema definition using the Propose Schema command in the Active Console 2, follow these steps:

  1. Right-click on a sampler or dataview.
  2. Select Propose Schema.

The generated XML schema definition for the sampler appears in a new window.

This use of Propose Schema should be combined with Paste Schema to aid in the generation of schemas for dataviews.

How to use Paste Schema on a sampler

When using the Propose Schema command in the Active Console 2, the generated XML output should then be copied and pasted into the corresponding sampler in the GSE:

  1. Right-click on the window with the generated XML in the Active Console 2 and select Copy All.
  2. Navigate to the GSE, right-click the correct sampler and select Paste Schema.
  3. Warning: No checks are performed when using Paste Schema on a sampler. Any existing schema is overwritten, and any copied schema can be pasted on to any sampler.

After using Paste Schema, perform the following:

  1. Navigate to the Publishing tab of the sampler to view the schema definition.
  2. Select Schema > Dataviews > Data.
  3. Review the schema for errors because the data types inferred by the Propose Schema command may be incorrect.
  4. Add any units of measure to the headlines and/or columns.
  5. (Optional) Specify pivoting.

See Configure the Gateway Technical Reference for more information about types, units of measure, and pivoting.

Note: Paste Schema is only available when valid XML has been copied to the clipboard.

How to use Paste Schema to create static variables

The generated XML output of the Propose Schema command in the Active Console 2 can also be used to create sampler schemas as static variables. Schemas saved as static variables can be selected in the Publishing tab of a sampler. For more information, see Publish to Gateway Hub - Technical Reference.

To use the output of the Propose Schema command to produce schemas as static variables, follow these steps:

  1. Right-click on the window with the generated XML in the Active Console 2 and select Copy All.
  2. Navigate to the GSE.
  3. Right-click on Static variables > Sampler-schemas and select Paste Schema.
    • A static variable containing a schema definition for each dataview in the copied sampler is created. The name used for the static variable is the name of the dataview.

After using Paste Schema, perform the following for each static variable:

  1. Review the schema for errors because the data types inferred by the Propose Schema command may be incorrect.
  2. Add any units of measure to the headlines and/or columns.
  3. (Optional) Specify pivoting.

See Publish to Gateway Hub - Technical Reference for more information about types, units of measure, and pivoting.

Note: Paste Schema is only available when valid XML has been copied to the clipboard.

How to view sampler schemas

To use the Show Current Schema command in the Active Console 2, follow these steps:

  1. Right-click on a sampler or dataview.
  2. Navigate to Sampler Schema.
  3. Select Show Current Schema.

The command opens a new window in the foreground.

Note: Running the command on a dataview gives the same result as running on the parent sampler.

To use the Show Current Schema command in the GSE, follow these steps:

  1. Select the sampler you want to view the schema for.
  2. Navigate to the Publishing Tab.
  3. Select Show Current Schema.

The command opens a window on the right side.

How to view metrics in Active Console 2

This step assumes you have already installed and verified a Gateway Hub installation, and connected a Gateway to Gateway Hub.

To can view historical metrics using data from the Gateway Hub via the Active Console, follow these steps:

  1. In the Active Console 2, navigate to a dataview.
  2. In the dataview, right-click a cell you want to view historical data for.
  3. Navigate to History Chart.
  4. Create a new chart by selecting New Chart followed by the chart's range. The options are:
    • Last Minute
    • Last Hour
    • Past Working Day (6am to 8pm)
    • Last 24 Hours
    • Last Week
    • Last Month
    • Last Year
    • Chart Range
    • User Defined
  5. The chart appears in Active Dashboards.
    • If your Active Dashboards window is not open, navigate to View and select Active Dashboards.