Collectors (Read)

List Collectors

GET /api/v1/collectors?limit=100&offset=0
GET /api/v1/collectors?enabled=true&limit=100&offset=0

List all collector configurations. Supports pagination. Operator role: credentials in the config JSONB are redacted — SNMP community strings and v3 auth/priv passwords, plus OSPF (ospf.auth.key / ospf.auth.password) and IS-IS (isis.authentication.key) authentication keys, are masked.

Query parameters:

• enabled (optional) — If "true", returns only enabled collectors
• limit (optional) — Max items to return (default 100, max 1000)
• offset (optional) — Items to skip (default 0)

Response: 200 OK — Paginated envelope

{
  "data": [
    {
      "id": "uuid",
      "name": "collector-1",
      "description": "Primary collector",
      "config": { ... },
      "area_id": "uuid",
      "enabled": true,
      "status": "running",
      "last_seen": "2024-01-01T12:00:00Z",
      "last_data_at": "2024-01-01T12:00:00Z",
      "last_error": null,
      "config_version": 3,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 1,
  "limit": 100,
  "offset": 0
}

Notes:

• The config field is an opaque JSONB blob transformed into the runtime collector config by the collector-manager. There is no top-level router_id field — the OSPF adjacency router-id lives inside the blob at config.ospf.router_id and must be a valid IPv4 address (router IDs are 32-bit per RFC 5340, even for OSPFv3). IS-IS collectors carry config.isis.* instead.
• config_version is always present; it is bumped on any config change or hierarchy rename to trigger a collector-manager restart. last_data_at (omitempty) is the timestamp of the most recent published snapshot, distinct from the last_seen liveness heartbeat.
• status values: pending | starting | discovering | running | degraded | stopped | error. degraded means the collector process runs but its protocol adjacency is down (no data feed) — GRE collectors report it within seconds of adjacency loss (hold-timer expiry) and flip back to running on recovery; the transition is flap-damped on the IS-IS path.
• Managed rows are read-only through collector CRUD when they have their complete Osprey-owned shape. BGP-LS uses managed_by: "bgpls" and name bgpls:<source-uuid>; IS-IS bootstrap children use managed_by: "isis-bootstrap", managed_parent_id, strict crawl_abrs: false, and name isis-snmp-managed:v1:<protocol-instance-uuid>:<canonical-area>. PUT, toggle, and DELETE return 409 with the owning surface. POST and merged PUT reject the two reserved managed_by values and name prefixes with 400. Partial marker sets remain operator-owned and can be repaired or deleted.
• At successful IS-IS handoff, generation-managed children lose managed_by and managed_parent_id and gain complete provisioned_* audit metadata. Their response has bootstrap_provisioned: true; target, credentials, poll interval, description, toggle, and delete are operator-controlled. Name, area_id, the complete hierarchy identity, discovery_mode, snmp.crawl_abrs, and provenance are immutable (400). Create and update cannot forge either the reserved name or any provisioned_* field.
• An IS-IS SNMP parent may carry boolean config.snmp.bootstrap_recorders. Automatic lifecycle work requires this persistent opt-in and the startup-latched server setting snmp.isis_bootstrap_enabled: true (set in the shipped configuration; a missing key leaves it off). POST /collectors adds bootstrap_recorders: true to a new isis-snmp config with crawl_abrs: true when the key is absent; an explicit false is kept, and updates never add the key, so existing crawlers are never promoted. With both enabled on an enabled level-2, crawl_abrs: true parent, a complete crawl reconciles one strict IS-IS SNMP recorder per canonical L1 area. Existing enabled strict operator recorders can satisfy a scope; otherwise Osprey creates temporarily read-only managed children. The parent remains multi-area until every exact child config version has produced an engine-persisted snapshot after the database acknowledgement boundary. The final parent scope change, cross-area coverage cleanup, completion record, state invalidation, and audit entry are one transaction, including transfer of generated children to operator ownership without a child version bump. Removing either gate before that transaction prevents handoff; managed children already created remain enabled for operator inspection or rollback.

Get Collector

GET /api/v1/collectors/{collectorID}

Get a single collector configuration by ID. Operator role: credentials in the config JSONB are redacted (SNMP community / v3 passwords and OSPF / IS-IS auth keys masked).

Response: 200 OK (single collector object)

Error: 404 Not Found

Get Collector Status

GET /api/v1/collectors/{collectorID}/status

Get the runtime status of a collector (subset of full config).

Response: 200 OK

{
  "status": "running",
  "last_seen": "2024-01-01T12:00:00Z",
  "last_error": null,
  "enabled": true
}

Error: 404 Not Found