The contract is deliberately trivial, because the point is that you can read it in one sitting and
implement it in whatever language your team already runs. HostTracker requests your URL; your endpoint
answers with a JSON object carrying the value:
{ "v": 42.7 }
That is the whole required surface. Two optional members make the result more useful: e
carries an error string when the value could not be read this time - a much better outcome than
reporting a misleading zero - and vs carries a version string of your own, which shows up in
the result so you can tell which build of the collector answered.
{ "v": 91.4, "e": "", "vs": "collector-2.1" }
Because you write the reader, you are not limited to what a generic agent knows how to collect. Queue
depth, cache hit ratio, the number of jobs waiting, the age of the oldest unprocessed record, free
inodes, the size of a directory that must never grow - anything you can express as a number becomes a
monitored value with thresholds, history and alerting attached to it.
Protect the endpoint. It has to be reachable by the checkers that call it, so treat it
like any other public URL: put it on an unguessable path, keep it read-only, and expose only the
numbers you are comfortable being read. It accepts no parameters that change anything, which keeps the
exposure to exactly one value.