Connector Structure

Top-Level Sections

extends: []
constants: {}

connector: {}
sudoCommands: []

metrics: {}
beforeAll: {}
monitors: {}
translations: {}
afterAll: {}

How MetricsHub Executes This YAML

This YAML is compiled when the project is built, shipped with MetricsHub, and loaded by the runtime.

For one configured resource, MetricsHub uses the sections in this order:

1. Detection phase: connector.detection decides whether the connector applies to the resource.
2. Discovery phase: beforeAll, then every monitor discovery job or simple job, then afterAll.
3. Collect phase: beforeAll, then every monitor collect job or simple job, then afterAll.

Discovery runs less often and is the right place for heavy inventory work. Collect runs repeatedly and should stay lightweight. Monitor jobs within discovery and collect can run in parallel.

Section Responsibilities

extends, constants, connector.variables, translations, and sudoCommands are covered in depth in Reuse and Configuration^[1].

connector Object (Core Metadata)

connector:
  displayName: Example Device (SNMP)
  platforms:
  - SNMP
  - VendorX
  reliesOn: SNMP
  version: 1.0
  information: Monitors enclosure and network ports.
  variables: {}
  detection: {}

detection Object

detection:
  connectionTypes: [ remote, local ]
  appliesTo: [ Network ]
  supersedes: [ LegacyConnector ]
  criteria:
  - type: snmpGetNext
    oid: 1.3.6.1.2.1.2.2.1

monitors Object

Each monitor can define either:

• simple job (single workflow executed in both discovery and collect), or
• discovery + collect jobs (two-phase workflow)

monitors:
  network:
    keys: [ id ]
    simple:
      type: multiInstance
      sources: {}
      mapping: {}

See Monitors and Jobs^[2] for the complete job model: discovery/collect splits, multiInstance vs monoInstance, instance identity (keys), conditionalCollection, and legacyTextParameters.

Table Data Model (Important)

Connector pipelines are table-based end to end.

• A source typically outputs rows and columns.
• Computes generally transform rows/columns.
• Mapping expects a table and uses column references ($1, $2, …).

Internally, a table is represented as List<List<String>>. The example below shows the same data in its internal form, as a logical table, and as serialized text:

[
  ["eth0", "Uplink 1", "ok", "1000000000"],
  ["eth1", "Uplink 2", "degraded", "1000000000"]
]

eth0;Uplink 1;ok;1000000000
eth1;Uplink 2;degraded;1000000000

This serialization detail explains why operations that append semicolon-delimited strings can effectively materialize extra columns after parsing.

mapping Block Inside Jobs

mapping is the bridge between a source table and exported telemetry. Each row of the mapped table represents one monitor instance. That instance is exported as one OpenTelemetry Resource, with attributes from attributes and metrics from metrics.

mapping:
  source: ${source::ports}
  attributes:
    id: $1
    name: $2
  metrics:
    hw.status{hw.type="network"}: $3
    hw.network.io{direction="receive"}: $4
  conditionalCollection:
    hw.network.io{direction="receive"}: $4

Recommended Ordering in Real Files

1. extends
2. constants
3. connector
4. optional metrics
5. optional beforeAll
6. monitors
7. optional translations
8. optional afterAll

This ordering improves review speed and consistency.

Common Mistakes

• mixing monitor-specific constants into global section without reuse
• creating multiple near-identical sources instead of branching from copy
• writing mapping before normalizing values in computes