Monitors

Step 1 - Configure Your Monitor

While configuring your monitor, you can choose between two strategies:

• Running separate discovery and collect jobs. MetricsHub will run the discovery job first to identify the resources to monitor, then the collect job to gather metrics from those resources
• Using a single simple job that performs both steps. MetricsHub** will discover resources and collect their metrics in a single step.

connector:
  # ...
monitors:
  <monitorName>: # <object>
    keys: # <string-array> | Default: [ id ]
    discovery: # <object>
      executionOrder: # <string-array> | Optional
      sources: # <object>
    collect: # <object>
      type: # <string> | possible values [ multiInstance, monoInstance ]
      executionOrder: # <string-array> | Optional
      sources: # <object>

connector:
  # ...
monitors:
  <monitorName>: # <object>
    keys: # <string-array> | Default: [ id ]
    simple: # <object>
      executionOrder: # <string-array> | Optional
      sources: # <object>

monitors:
  enclosure:
    keys: [ id ]
    discovery:
      sources:
        source(1):
          type: ipmi
          computes:
          - type: awk
            script: ${file::enclosure.awk}
    collect:
      type: multiInstance
      sources:
        source(1):
          type: ipmi
          computes:
          - type: awk
            script: ${file::enclosure.awk}

Step 2 - Map Collected Metrics and Attributes

Paste the mapping section in your connector file:

connector:
  # ...

monitors:
  <monitorType>: # <object>
    <job>: # <object>
      # ...
      mapping:
        source: ${source::monitors.temperature.discovery.sources.source(1)}
        attributes:
          <key>: # <string>
        metrics:
          <key>: # <string>
        conditionalCollection:
          <key>: # <string> # Only collect if <key> evaluates to an non-empty value

This section allows mapping the collected data to MetricsHub’s monitoring model:

• Under attributes, define intrinsic information about the monitor (for example, its name, identifier, or serial number) using key–value pairs
• Under metrics, define the metrics collected from the resource
• Under conditionalCollection, specify the mapping keys that must have a non-empty value to enable the collection of their corresponding metrics.

You can also use the following mapping functions:

• fakeCounter to simulate a counter operation based on a value expressed as a rate
• rate to calculate a rate from counter values.

mapping:
  source: ${source::monitors.temperature.simple.sources.source(1)}
  attributes:
    id: $2
    sensor_location: $3
  metrics:
    hw.temperature: $5
  conditionalCollection:
    hw.temperature: $5 # Only collect if hw.temperature has a value

Step 3 - Define the OpenTelemetry Metrics Metadata to be Collected

Add the metrics section to your connector file to describe the OpenTelemetry metrics metadata (name, unit, description, and type) that your monitor will collect and export:

connector:
  # ...

metrics:
  <metricName>: # <object>
    unit: # <string>
    description: # <string>
    type: # oneOf [ <enum>, <object> ] | possible values for <enum> [ Gauge, Counter, UpDownCounter ]
      stateSet: # <string-array>
      output: # <enum> | possible values [ Gauge, Counter, UpDownCounter ] | Optional | Default: UpDownCounter

metrics:
  hw.temperature:
    description: Temperature of the component.
    type: Gauge
    unit: Cel
  hw.status:
    description: 'Operational status: 1 (true) or 0 (false) for each of the possible states.'
    type:
      stateSet:
      - degraded
      - failed
      - ok  

Step 4 - (Optional) Override Connector-Level metrics

If you want a monitor's metrics to override the default connector-level metrics, include the following section:

connector:
# ...

monitors:
  <monitorType>: # <object>
    metrics:
      <metricName>: # <object>
        unit: # <string>
        description: # <string>
        type: # oneOf [ <enum>, <object> ] | possible values for <enum> [ Gauge, Counter, UpDownCounter ]
          stateSet: # <string-array>
          output: # <enum> | possible values [ Gauge, Counter, UpDownCounter ] | Optional | Default: UpDownCounter

monitors:
  voltage:
    metrics:
      hw.voltage:
        unit: V
        description: Per-instance voltage with monitor override
        type: Gauge