package PB.Facts

Get desktop application:
View/edit binary Protocol Buffers messages

One fact set - the first level of the document - as a producer reports it. Not mentioning a set at all is the third state, and the important one: it leaves whatever the core already has, so a transient failure never blanks the inventory. `removed` is the explicit "stop holding this" (the docker socket went away), and `error` says a set this module produces could not be collected this round, which keeps the previous value and is reported next to the document so a consumer can show the reason rather than silence.

Used in: FactsMessage.Response

• string id = 1

• optional Object facts = 2

• bool removed = 3

• string error = 4

• string gathered = 5

  When the producer actually read these values off the machine, ISO 8601 UTC. Distinct from the round that delivered them: a producer whose collection is expensive hands back a snapshot it took earlier, and this is what says how old that snapshot is. Empty when the producer did not say, and the core then falls back to the time of the round. Deliberately not a field inside `facts`: the repository decides "did anything change" by comparing the encoded document, so a timestamp in there would make every round a change and bump the revision hourly forever.

Facts message. Module -> core: what this module produced this round.

• optional Common.Header header = 1

• repeated FactsMessage.Response payload = 2

Used in: FactsMessage

• int64 id = 1

• optional Common.Result result = 2

  A result other than STATUS_OK is "this round failed", which is not the same as "I no longer produce any of this": the core keeps every set it holds for this module and prunes nothing.

• repeated FactSet sets = 3

Facts query message. Core -> module: collect the fact sets you are configured to produce.

• optional Common.Header header = 1

• repeated FactsQueryMessage.Request payload = 2

Used in: FactsQueryMessage

• int64 id = 1

• string reason = 2

  Why the core is asking: startup, scheduled, reload or manual. All the core has to say - which sets to collect is the module's own configuration - and enough for an expensive collector to hand back its last snapshot instead of collecting again.

Facts request message. Consumer (REST, the `nscp test` console) -> core: read the document. There is no set command on purpose. Facts are produced by fetchFacts on the core's schedule from what each module's own configuration enables, so a module cannot push inventory the operator did not ask for.

• optional Common.Header header = 1

• repeated FactsRequestMessage.Request payload = 2

Used in: FactsRequestMessage

• int64 id = 1

• Request.Command command = 2

• string path = 3

  A dotted path into the document ("os", "software.installed"). Empty is the whole document.

Used in: Request

• GET = 0

• REFRESH = 1

  Run a collection round now, then answer as GET does.

Facts response message. The document (or the subtree asked for) and what a consumer needs to render and cache it.

• optional Common.Header header = 1

• repeated FactsResponseMessage.Response payload = 2

Used in: FactsResponseMessage

• int64 id = 1

• optional Common.Result result = 2

• uint64 revision = 3

  Monotonic change counter: 0 is the empty document a fresh install reports, and it only moves when the stored facts actually change.

• string collected = 4

  When the last round completed, ISO 8601 UTC; empty until one has.

• repeated string enabled = 5

  What the producers said they are collecting at their last completed round - including a set that is enabled and currently failing.

• repeated Common.KeyValue errors = 6

  Per-set collection errors from the last round.

• repeated Common.KeyValue gathered = 10

  When each set's values were read off the machine, keyed by set id. A consumer shows this rather than `collected`: the latter says when the core last asked, which for a cached producer is not when the numbers were true.

• string path = 7

  Echoed back when the request carried one, with `found` saying whether anything produced it. A path the document does not have is not an error: "no such subtree" and "the call failed" are different answers.

• bool found = 8

• optional Value facts = 9

  The document, or the subtree at `path`. A Value rather than an Object because a path may address any node: `os` is an object, but `os.family` is a string and `storage.volumes` a list. The whole document is always an object_value.

One key/value pair of an object. Spelled out as a message in a `repeated` rather than a protobuf `map` because the order is ours to decide: the core stores the fields of every object sorted by key, which is what makes two collections of the same inventory compare equal byte for byte (and, through that, what keeps the revision from moving when nothing changed).

Used in: Object

• string key = 1

• optional Value value = 2

Used in: Value

• repeated Value values = 1

Used in: FactSet, Value

• repeated Field fields = 1

One value in the document. The oneof is the value's type, and there is no null member on purpose: an unknown value is omitted from the document, never written as null, so a consumer never has to tell "absent" from "present but nothing".

Used in: FactsResponseMessage.Response, Field, List

• oneof kind

  • string string_value = 1

  • int64 int_value = 2

    Signed and unsigned are kept apart so a producer holding a DWORD or a 64-bit byte count does not have to squeeze it through int64.

  • uint64 uint_value = 3

  • double double_value = 4

  • bool bool_value = 5

  • Object object_value = 6

  • List list_value = 7