Skip to main content

Census documentation

Census serves named inventories of network infrastructure, such as devices, assembled from several source systems. Infrahub and NetBox are the supported sources. Memgraph stores the cache that Census builds from them.

An administrator defines each inventory in a configuration file: the fields it holds, the source systems that supply them, which source wins each field, how source values map to a shared list of values, how long a value stays fresh and the hierarchy of locations. Census fetches the source data, groups the records that describe the same entity by their HFID (Human-Friendly ID), and stores one resolved entity per HFID.

A consumer, such as an automation script or a person in a browser, queries an inventory through a REST API or the read-only web UI. Each response states whether the inventory is complete and how each source is doing, and full detail traces every value to the source object and field that supplied it.

Sections of this documentation​

  • Getting started: run Census with Docker and send the first queries.
  • Concepts: the terms the rest of the documentation uses, such as inventory, contribution, HFID, completeness and freshness.
  • Administration: for the people who deploy Census and define its inventories. It covers connections, inventories, contributions, field priorities, vocabularies, location hierarchies, freshness budgets, webhooks and what each configuration change does when Census restarts.
  • Query API: for the people and programs that read inventories. It covers listing and filtering entities, HFIDs, completeness, contribution health, freshness, full detail, branch views, diagnostics and errors.
  • Architecture: how Census works internally, from a source system through the cache to an API response, and the decisions behind that design.

What Census does not do​

These limits apply to the current version:

  • Census reads from its sources and never writes changes back to them.
  • Census has no authentication or authorization. Run it on a trusted network.
  • Inventories are changed in the configuration file and the change applies when Census restarts. The API and the web UI are read-only.
  • Census does not match records by serial number, IP address or any attribute other than the HFID.