Run and Debug Locally

Basic Invocation

metricshub <hostname> -t <type> <protocol flags> [-u <user> [-p <password>]] [options]

• <hostname> — the resource to monitor (localhost works, see below).
• -t / --type — the resource type. Accepted tokens include linux (lin), windows (win), network (switch), storage (san, array), management (mgmt, oob), aix, hpux, solaris, tru64, vms, other. Abbreviations like sto or net are not accepted.
• Protocol flags enable and configure each protocol: --snmp [1|2] (--community, --snmp-port), --snmpv3, --http/--https (--http-port), --ssh, --wmi, --winrm, --wbem, --ipmi, --jdbc, --jmx — each with its own --<protocol>-username/--<protocol>-password/--<protocol>-timeout variants. At least one protocol is required.
• -u/--username and -p/--password set the global credentials; -p with no value prompts interactively.

Developer Essentials

The standard development invocation, from the repository root:

metricshub my-device --type storage --https --http-port 8443 -u admin -p \
  -pd src/main/connector -c +MyConnector -vvv

This forces your work-in-progress connector (+MyConnector) from your source tree (-pd) with DEBUG logging.

For a connector that declares variables^[2], pass values with --additional-connector:

metricshub my-host -t linux --ssh -u monitor -p \
  --additional-connector systemdProcess --uses LinuxProcess -F matchName=systemd

What to Verify in the Output

• metricshub.connector.status is ok — detection passed and jobs ran.
• Discovered instances are coherent: expected count, stable id values, no self-referential hw.parent.id, real serial numbers.
• Metric names, units, and attributes follow the naming rules^[3].
• Status metrics resolve to ok / degraded / failed — if you see raw vendor codes, a translation table is missing or misreferenced.
• Re-run twice: the second discovery must find the same instances (no duplicates from unstable keys).

If detection fails, run with -vvv and read the criteria evaluation: each criterion logs what was executed, what came back, and why it matched or failed.

Testing Without the Real Device

metricshub localhost -t linux --ssh -u any -p any -pd src/main/connector -c +MyConnector

# Terminal 1: serve the recorded data
snmpsim-command-responder --data-dir=./snmp-data --agent-udpv4-endpoint=127.0.0.1:1161

# Terminal 2: point MetricsHub at the simulator
metricshub localhost -t network --snmp 2 --community public --snmp-port 1161 \
  -pd src/main/connector -c +MyConnector -vvv

snmpcli my-device --walk 1.3.6.1 --community public --version v2c > snmp-data/my-device.snmpwalk

# emulator.py — run with: uvicorn emulator:app --host 0.0.0.0 --port 8080
from fastapi import FastAPI
app = FastAPI()

@app.get("/api/v1/inventory/fans")
def fans():
    return {"fans": [
        {"id": "fan-01", "name": "Fan 1", "status": "ok", "rpm": 7230},
        {"id": "fan-02", "name": "Fan 2", "status": "failed", "rpm": 0},
    ]}

metricshub localhost -t storage --http --http-port 8080 -u guest -p guest \
  -pd src/main/connector -c +MyConnector -vvv

Record and Replay

Once the connector works, capture the real protocol exchanges so they can replay forever without the device:

• metricshub ... -rec (--record) writes every source and criterion result as YAML into protocol subfolders (http/, ssh/, wmi/, …) under the MetricsHub logs directory.
• metricshub ... -e <dir> (--emulate) replays a recorded directory instead of contacting the device.
• SNMP walks are captured with snmpcli --walk (above), not with --record.

These recordings become the src/it/resources/<ConnectorId>/emulation/ content of your replay integration test — the full workflow is on the Integration Testing^[1] page.

Common Pitfalls

• Forgetting -pd src/main/connector: the bundled copy of the connector runs instead of your edited one, and your changes seem to have no effect.
• Using -t sto or -t net: not accepted — write storage / network.
• Testing detection only with +MyConnector: forcing skips auto-detection, so also run once with -c MyConnector (bare id) to verify the criteria actually match.
• Unstable instance ids that create duplicates on the second run — watch for it before recording test resources.