Skip to content

The answer's metric names identify the document - #178

Merged
torstei merged 1 commit into
mainfrom
timbergraph/infer-the-document
Sep 7, 2026
Merged

The answer's metric names identify the document#178
torstei merged 1 commit into
mainfrom
timbergraph/infer-the-document

Conversation

@torstei

@torstei torstei commented Sep 7, 2026

Copy link
Copy Markdown
Owner

--using was the only route to a unit when the window held no !meta — which
meant typing the name of a document whose metrics are already listed in the
answer. facts_for looks it up instead.

Three sources, in order of authority: the document using named (an
instruction), then a !meta in the window (the producer's own word about these
numbers), then the documents installed here. So using becomes the
override rather than the normal path.

Live, with no !meta and no --using — the inferred requests reaches the
right axis and splits the plot, which is the unit-decides-the-axis rule working
off inference alone:

                    http_bytes, http_requests
 4000 +--------------------------------------------+ 4
 2500 |-+........:..........:.........:.....##.+-| 2.5
 1500 |-+........:..........:.........:...##..count (requests)
    0 +------------------------------------------+ 1
    12:01      12:02      12:03     12:04      12:05
         http_bytes *******  http_requests (right) #######

⚠ Inference degrades to NO unit, never a wrong one. Where two documents
declare one metric in different units, both are named and the unit is left
blank. The unit decides which axis a series lands on, so guessing between ms
and s would not mislabel a plot — it would regroup it.

That is not hypothetical. The shipped set today:

http_bytes     timberfs-apache-combined=B  timberfs-nginx-combined=B    <-- several
http_latency   timberfs-nginx-combined=s
http_requests  timberfs-apache-combined=requests  timberfs-nginx-combined=requests

The two overlapping metrics agree, so the ambiguity is currently harmless — and
checkable rather than assumed. But http_latency is nginx's alone at s
while apache logs %{ms}T in milliseconds, so the first time
timberfs-apache-combined grows a latency metric (the field is already in the
log format it parses) a mistyped using would silently re-axis the plot.

Two things now said that were silent: a using naming a document that
declares none of the answer's metrics, and a using that disagrees with a
!meta.

Nothing new in the bark, nothing that travels, no dependency on the producing
host being alive — the only requirement is the one this rests on anyway: the
local documents resemble the server's. When they don't it degrades to no units,
which is exactly today's behaviour.

The harness bug this turned up

tests/timbergraph/test-timbergraph's main() called fn() unguarded, so one
test raising aborted the whole run and every test after it never ran — the
failure mode a suite exists to prevent. It hid the first draft of this PR's own
test (a KeyError that read as a clean pass in a truncated check). Now caught
per test, as the timbersh suite already does. Verified by sabotaging
declaring():

FAIL test_the_documents_installed_here_identify_the_metric: KeyError: 'unit'
timbergraph: 1 failure(s) of 16 test(s)

New in timbergraph.py: declaring(metric) and facts_for(metrics, markers, using), which replaces the three-line facts/units dance duplicated in
timbergraph's main() and timbersh's graph.

`--using` was the only way to get a unit when the window held no `!meta`,
which meant typing the name of a document whose metrics are already
listed in the answer. So `facts_for` looks it up instead: for each metric,
which locally installed documents declare it.

Three sources, in order of authority — the document `using` NAMED, then a
`!meta` (the producer's own word about these numbers), then the local
documents. `using` becomes the override.

⚠ Inference degrades to NO unit, never a wrong one. Two documents
declaring one metric in different units are both named and the unit is
left blank, because the unit decides which axis a series lands on:
guessing between `ms` and `s` would not mislabel a plot, it would regroup
it. Live today — `timberfs-apache-combined` and `-nginx-combined` share
`http_requests` and `http_bytes` at identical units, while `http_latency`
is nginx's alone at `s` and apache logs `%{ms}T` in milliseconds.

Two things it now says that were silent: a `using` naming a document that
declares none of the answer's metrics, and a `using` that disagrees with
a `!meta`.

And the test harness catches per test, as the timbersh one does. Unguarded
it aborted the whole run on an exception, so every test after the raising
one never ran — which is the failure mode a suite exists to prevent, and
it hid this test's own first draft.
@torstei
torstei merged commit f722116 into main Sep 7, 2026
7 checks passed
@torstei
torstei deleted the timbergraph/infer-the-document branch September 7, 2026 10:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant