PROMESCOPE — Look Inside Any Prometheus Endpoint
777 Software · version 1.0 · Linux · TEST BUILD (for Steven's test)

WHAT IT IS
Prometheus is the program a lot of servers use to watch themselves:
it collects numbers — memory, load, requests, temperatures, anything —
called metrics. PROMESCOPE is a window into those numbers. Paste the
address of a Prometheus server, or of any single program's metrics
page (an "exporter"), and PROMESCOPE shows you every metric it has,
sorted and filtered the way you want, in plain words.

IT ONLY EVER LOOKS. PROMESCOPE asks read-only questions and nothing
else. There is no button, no code path, and no hidden option that can
change, delete, reload, or restart anything on the other end. It has
no account, no telemetry, and it never phones home: the only address
it ever talks to is the one you type.

THE TWO KINDS OF ADDRESS
  * A Prometheus SERVER — the collector itself. PROMESCOPE reads its
    whole catalogue in chunks (you'll see honest progress), plus its
    targets list: what's being scraped, whether each one is UP or
    DOWN, and the server's own error words when one is down.
  * An EXPORTER / metrics page — one program's own list of numbers,
    like a node_exporter page. PROMESCOPE reads the page directly.
You can leave KIND on Auto-detect and PROMESCOPE will work out which
one you pasted. If it truly can't tell, it asks you — it never guesses
silently.

THE BOARD
Every metric is a row: NAME, TYPE, VALUE, its LABELS, and the first
words of its help text. Values are shown the way people read them
(812,345.67 — and GB for byte counts). Rows refresh on a timer you
pick (5 / 15 / 30 / 60 seconds, or Pause — a real pause).

  * SORT — click NAME, TYPE or VALUE. VALUE sorts as real numbers
    (biggest first on the first click); TYPE runs counter, gauge,
    histogram, summary, untyped. Click again to flip.
  * FILTER — pick a type and/or type words. It matches names, labels
    and help text, and it is all done from what's already on screen:
    filtering never asks the endpoint anything extra. "showing N of
    M" and Clear are right there.
  * YOUR PLACE IS YOURS — your selected row and your scroll position,
    on the board AND in the detail pane, survive refreshes, re-sorts
    and filters. If your selected row gets filtered out, its detail
    stays on screen with an honest note that your filter is hiding it.

THE DETAIL PANE
Click a row for its whole story: the full series name with labels,
what the type means in plain words, the value now with the time it
was fetched (and the endpoint's own timestamp when it provides one),
the help text, and its recent-history sparkline.
  * For a server, history comes from the server (last hour).
  * For an exporter page, history is remembered only for the series
    you have selected, only while PROMESCOPE is open — the pane says
    so. Nothing is saved to disk.
Buttons: Copy series name · Query this series (server only) ·
Graph this series.

QUERY (server only)
Type a PromQL query and run it right now. The four ways it can go are
four different sentences, in plain words: it ran (with the run time),
the server couldn't parse it (with the server's own words), it took
too long, or it ran fine and matched nothing. Warnings from the
server are shown, never hidden.

GRAPH
Plot up to five series over 15 minutes / 1 hour / 6 hours / 24 hours.
Server graphs come from the server itself. Exporter graphs are drawn
from this session's memory for series you have selected — the window
says which source it used.

TARGETS (server only)
Every scrape target with its health in words and symbols — UP,
DOWN, NOT KNOWN — worst first, the server's last error word for word,
and dropped targets listed separately, dimmed. UNKNOWN is shown as
itself; it is never painted as up or down.

HONESTY RULES (built in, not options)
  * Every value carries the time it was fetched.
  * If the endpoint stops answering, after two missed refreshes a
    banner says so, over the last true data, stamped with when that
    data was true. Old data is never shown as if it were live.
  * If the endpoint rejects the login, refreshing STOPS — PROMESCOPE
    will never hammer a login and risk locking an account.
  * A load that hits the size cap, or metadata that had to come from
    a fallback, is labeled as exactly that.

CONNECTIONS (PROFILES)
Saved connections live in ONE file next to the program,
promescope_profiles.json, locked to permissions 0600 — only your
user can read it. Passwords and tokens live only in that file: never
in this package, never in a log, never sent anywhere but the endpoint
itself. In the form, a saved secret shows as "saved - type to
replace" — type over it only when you mean to change it.
If an endpoint uses a self-signed certificate, tick the box on its
connection — the form says plainly that this weakens certificate
checking for that connection only.

RUNNING IT
  ./PROMESCOPE            (Linux, no install, nothing else needed)
  ./PROMESCOPE --version

WHAT'S IN THIS PACKAGE
  PROMESCOPE                    the program (one file)
  README.txt                    this file
  promescope.py                 the full source it was built from
No profiles, settings or credentials are in this package — yours are
created on your own machine, beside the program, the first time you
save a connection.

Lead Assistant Architect: Charles Burnett — 777 Software
