Reuse and Configuration

Load-Time Resolution Order

When a connector is parsed, the engine resolves its building blocks in this order:

1. extends — parent connectors are merged in
2. ${var::name} — connector variables are substituted (defaults or user-configured values)
3. ${source::...} and other references are resolved to absolute paths
4. ${constant::name} — constants are inlined, then the constants section is dropped

All of the above happens once, at load time. Runtime credential macros (%{USERNAME}, %{PASSWORD}, …) are different: they are resolved at execution time, per request — see References and Expressions^[1].

extends: Connector Inheritance

A connector can inherit from one or more parent connectors:

extends:
- ../../semconv/Hardware          # metric metadata dictionary
- ../MIB2-header/MIB2-header      # shared detection + monitors

Paths are resolved relative to the connector's own directory, and .yaml is appended automatically. Parents may themselves extend other connectors (chained inheritance is fully resolved). The extends key is stripped from the compiled connector.

# MIB2.yaml
extends:
- ../../semconv/Hardware
- ../MIB2-header/MIB2-header
connector:
  displayName: MIB-2 Standard SNMP Agent
  platforms: SNMP
  detection:
    appliesTo: [ Network ]
    supersedes: [ ... ]

constants

Top-level map of reusable literals, referenced as ${constant::name} anywhere in the connector:

constants:
  GLOBAL_COMMAND_LINE: /sbin/ip a
  COLLECT_COMMAND_LINE: /sbin/ip -s link show dev ${attribute::id}

Constants are inlined at load time by plain text substitution, and the constants section is then removed from the compiled connector.

The flagship use case is parameterizing a header connector: LinuxNetwork-header runs ${constant::GLOBAL_COMMAND_LINE}, and each child (LinuxIPNetwork with ip, LinuxIfConfigNetwork with ifconfig) supplies its own command through constants.

connector.variables

Variables make a connector user-configurable. Declare them under connector.variables, each with a description and a defaultValue, and reference them as ${var::name} anywhere in the connector or its embedded files:

connector:
  displayName: Linux - Processes
  variables:
    matchName:
      description: Regular expression pattern to match process names for monitoring.
      defaultValue: .*
  detection:
    disableAutoDetection: true
    ...

monitors:
  process:
    simple:
      sources:
        processes:
          type: commandLine
          commandLine: /usr/bin/ps -e -o comm,args | grep -E "${var::matchName}"

Variables are resolved once, at connector load time:

• A default instance of the connector always exists with the defaultValues applied, so forcing the connector (connectors: [ +LinuxProcess ]) works without any variable configuration.
• Users create additional configured instances in metricshub.yaml with additionalConnectors:

resources:
  prod-web:
    attributes: { host.name: prod-web, host.type: linux }
    protocols:
      ssh: { username: monitor, password: "..." }
    additionalConnectors:
      systemdProcess:          # new connector instance id
        uses: LinuxProcess     # base connector
        variables:
          matchName: systemd

Community examples: LinuxProcess^[7], LinuxService^[8], LinuxFile^[9]. Note that all of them pair variables with disableAutoDetection: true: a connector whose behavior depends on user input is usually meant to be selected explicitly.

translations

Top-level map of translation tables, consumed by the translate^[10], arrayTranslate^[11], and perBitTranslation^[12] computes via ${translation::TableName}:

translations:
  PhysicalDiskStatusTranslationTable:
    "3": ok
    "4": degraded
    "5": failed
    default: UNKNOWN

Authoring rules:

• Keys are matched case-insensitively against the cell value; quote numeric keys so YAML treats them as strings.
• The default key is the fallback for unmatched values (translate and arrayTranslate honor it; perBitTranslation ignores it).
• Translate into the exact state names your metric's stateSet declares (ok, degraded, failed), so mapping can use the column directly.
• Declare each table once and reference it from every source that needs it; tables inherited via extends merge key by key.

sudoCommands

Some Linux/Unix commands need elevation. Declare the commands under top-level sudoCommands and prefix their invocations with the %{SUDO:command} macro:

sudoCommands:
- /usr/bin/sensors

monitors:
  temperature:
    simple:
      sources:
        sensors:
          type: commandLine
          commandLine: "%{SUDO:/usr/bin/sensors} /usr/bin/sensors"

At runtime, %{SUDO:/usr/bin/sensors} expands to the configured sudo command (sudo by default) only if the user enabled sudo in their OS-command protocol configuration (useSudo: true) and whitelisted the command. Otherwise the macro silently expands to an empty string and the command runs without elevation — so the command line must remain valid without the prefix (note the pattern above: the macro is a prefix, the real command follows).

Community examples: lmsensors^[13], LinuxMultipath^[14], SmartMonLinux^[15].

Common Mistakes

• Expecting a child connector to remove a parent's detection criterion or compute — object-arrays only append; restructure the hierarchy instead.
• Chaining constants or embedding ${var::} in a constant value — substitution is a single pass.
• Declaring a variable without defaultValue, leaving ${var::name} unresolved for users who force the connector without configuration.
• Forgetting to whitelist a command in sudoCommands while using %{SUDO:...} — the macro silently disappears and the command runs unprivileged.
• Duplicating metric definitions locally instead of extending the right semconv/* dictionary.