Read diagnostics

Diagnostics list the source records Census excluded and the values it could not use, each with the source reference needed to find and fix it in the source system. An administrator uses them after a configuration change; a consumer uses them to understand why an inventory is incomplete or why a field is null.

curl -s 'localhost:8080/v1/inventories/devices/diagnostics?kind=unmapped&kind=duplicate_hfid'

{
  "items": [
    { "kind": "duplicate_hfid", "contribution": "infrahub", "hfid": "fw-01",
      "source_ref": "1808d32d-a503-701a-d0eb-c51654327f06",
      "native_id": "1808d32d-a503-701a-d0eb-c51654327f06", "object_type": "InfraDevice",
      "references": [ … ] },
    { "kind": "unmapped", "contribution": "netbox", "hfid": "sw-07", "field": "status",
      "original": "retired", "path": "status.value",
      "source_ref": "https://netbox.example.net/api/dcim/devices/9/", "native_id": "9",
      "object_type": "dcim/devices", "references": [ … ] }
  ],
  "total": 2,
  "next_cursor": null
}

Kinds of diagnostics

kind	What it reports	Makes the inventory incomplete
missing_hfid	A record with no HFID. It takes no part in any entity.	Yes
duplicate_hfid	A record that shares its HFID with another record of the same contribution. Both take no part in that entity.	Yes
unmapped	A value with no mapping in the field's vocabulary, and no default. Also a location that matches no declared location, with the field location.	No
wrong_type	A value whose JSON type is not the field's type.	No
ambiguous_location	A location that matches several declared locations.	No

field, original and path are present for value diagnostics. For a location, original holds the name of each level and path lists the path of each level, for example rack=rack.name,site=site.slug.

source_ref identifies the source object: the NetBox API URL, or the Infrahub node id. object_type is the NetBox API path or the Infrahub node kind, and references lists the links to the object, as in full detail.

Parameters

Parameter	Meaning
kind	Only these kinds. Repeat it for several. Default: every kind.
contribution	Only this contribution's records.
branch	Diagnostics of a branch view.
limit	Page size, 1 to 1,000. Default 100.
cursor	The next_cursor of the previous page.

An unknown kind, or a contribution the inventory does not have, returns 400 invalid-query.

Fix what diagnostics report

kind	Fix
missing_hfid, duplicate_hfid	Correct the HFID field of the object in the source. The next refresh or webhook makes the record eligible again.
unmapped	Add the value to the contribution's values table, or to the field's vocabulary, and restart Census. Census recomputes the inventory from stored data.
wrong_type	Correct the value in the source, or change the field's type or the source path.
ambiguous_location	Map more levels in the contribution's location table, so that the source's names match one location.