Referenz
Die Tabellen dieser Seite folgen der technischen Referenz im Quelltext (core/README.md, englisch). Feldnamen und Werte sind englisch, weil Programme sie so schicken.
Meldungsarten
Abschnitt betitelt „Meldungsarten“POST /v1/ingest, Bearer-Schlüssel mit der Rolle ingest, im Rumpf ein JSON-Array oder NDJSON. Höchstens 1 MiB und 1000 Meldungen; ein Stapel gilt ganz oder gar nicht. Unbekannte Felder werden abgelehnt.
Jede Meldung hat type, thing (eine Id, die du vergibst: Buchstaben, Ziffern und . _ : @ -) und auf Wunsch ts.
| Art | Felder | Bedeutung |
|---|---|---|
thing | kind, name, labels, url, price{amount, currency, per, side, until}, expect_s, gone | Beschreibt ein Ding. Nur die Felder, die du schickst, ändern sich. price.per ist hour, day, month oder year. price.side ist cost (Aufwand, der Standard) oder revenue (Ertrag). price.until ist, wo der Betrag von selbst endet: eine Abschreibung, ein Vertrag mit Laufzeit. expect_s: „Ich melde mich dazu mindestens so oft“ — Schweigen darüber hinaus ist kritisch. gone: Es gibt das Ding nicht mehr; es kostet nichts mehr, und seine Vorfälle erledigen sich. |
state | check, status (ok/warn/crit), summary, due, vars, ttl_s, amount + currency, side | Der Zustand einer benannten Prüfung, wie diese Quelle ihn sieht. Nach dem Datum in due gemeldet und nicht in Ordnung, braucht sie jemanden seit diesem Datum, nicht seit jetzt. Mit amount ist sie zugleich etwas Offenes: Es steht dir zu (side revenue), oder du schuldest es (cost, der Standard), bis diese Quelle den Zustand ohne Betrag meldet. ttl_s: wie lange die Meldung zählt, wenn mehrere Quellen dieselbe Prüfung melden. |
event | event, outcome (ok/fail/fehlt), summary, vars, amount + currency, oder quantity, side | Etwas ist passiert. Mit einem Ergebnis ist es ein Lauf: Ein Fehlschlag macht die Prüfung gleichen Namens kritisch, bis ein Lauf gelingt. Ein Ereignis kann tragen, was es gekostet hat (amount), oder eine quantity, die ein Preis je Ereignis aus der Konfiguration zu Kosten macht. |
metric | metric, value | Eine Zahl. Es bleiben der letzte Wert und ein Tag Verlauf; sie wird mit Schwellen verglichen. |
cost | amount, currency, from, to | Was das Ding in einem Zeitraum gekostet hat. Derselbe Zeitraum noch einmal ersetzt den Wert. |
revenue | amount, currency, from, to | Was das Ding in einem Zeitraum gebracht hat; sonst wie cost. |
edge | rel (part_of/runs_on/depends_on), target, gone | Eine Verbindung. Kosten rollen entlang part_of auf. Ein Vorfall an einem Ding, dessen Ziel von runs_on/depends_on kritisch ist, wird unter seiner Ursache gezeigt und benachrichtigt niemanden. |
Der erste Preis eines Dings zählt ab dem ts der Meldung (ab jetzt, wenn sie keines hat). Eine spätere Preisänderung zählt ab dem Moment, in dem sie gemeldet wird.
Melden mehrere Quellen dieselbe Prüfung, ist ihr Zustand die zweitschlechteste Meldung, und mindestens warn, solange irgendeine Quelle unzufrieden ist.
Ansichten
Abschnitt betitelt „Ansichten“Bearer-Schlüssel mit der Rolle read oder operate.
| Endpunkt | Liefert |
|---|---|
GET /v1/attention?thing= | offene Vorfälle (kritische zuerst, Folgen zuletzt) und Prüfungen, die in 30 Tagen fällig werden — für alles oder für einen Ausschnitt |
GET /v1/ledger?thing= | die Ledger Line als Daten: der Satz, der Vorfall, der zuerst zu nennen ist, dreißig vergangene Tage, was in den nächsten dreißig fällig wird, und Aufwand und Ertrag des Monats bisher und insgesamt |
GET /v1/things?kind= | Dinge mit ihrem schlechtesten Zustand |
GET /v1/things/{id} | ein Ding: Zustände, Vorfälle, Ereignisse, Verbindungen, Messwerte mit Verlauf |
GET /v1/scopes | jedes Ding, zu dem etwas gehört, mit der Zahl der Dinge darin und dem schlimmsten offenen Vorfall |
GET /v1/costs?from=&to= | eigener und aufgerollter Aufwand je Ding und Summen je Währung; Standard ist der ganze laufende Monat |
GET /v1/money?from=&to=&thing= | Aufwand und Ertrag je Ding, eigen und aufgerollt, und was jetzt offen ist, früheste Fälligkeit zuerst |
GET /v1/top?from=&to= | drei kurze Listen für einen Zeitraum: was am meisten Aufmerksamkeit brauchte, am meisten kostete, am meisten brachte |
GET /v1/review?from=&to=&thing= | der Rückblick auf einen Zeitraum: was wiederkam, ob Behebungen gehalten haben, Lärm, was zu spät fertig wurde, und alles als ein Brief (brief) |
GET /v1/episodes?from=&to=&thing= | die Vorfälle, die in einem Zeitraum offen waren (Standard: die letzten 30 Tage), und je Tag der schlimmste |
GET /v1/episodes/{id} | ein Vorfall |
GET /v1/episodes/{id}/actions | die passenden Brief-Vorlagen, für diesen Vorfall ausgefüllt |
POST /v1/episodes/{id}/actions/{action} | einen Webhook-Brief einreihen (Rolle operate) |
POST /mcp | der MCP-Server, der nur liest; siehe der Brief |
Platzhalter im Brief
Abschnitt betitelt „Platzhalter im Brief“| Platzhalter | Wird zu |
|---|---|
{{thing.id}}, {{thing.name}}, {{thing.kind}}, {{thing.url}} | das Ding |
{{check}}, {{status}}, {{summary}}, {{started}}, {{episode}} | der Vorfall |
{{due}} | die Fälligkeit |
{{amount}}, {{side}} | was an der Prüfung offen ist („2400.00 USD“), und auf welcher Seite |
{{vars.KEY}}, {{labels.KEY}} | was die Quelle mitgeschickt hat, und die Labels des Dings |
{{history}} | ob es schon einmal vorkam, wann, wie lange |
{{follows}} | was nur deswegen offen ist |
{{last_fix}} | was beim letzten Mal geholfen hat |
{{events}} | die letzten fünf Ereignisse des Dings |
{{context}} | alle vier davor zusammen |
Sonst wird nichts ersetzt.
Konfiguration
Abschnitt betitelt „Konfiguration“Jede *.json-Datei in NOTA_CONF darf diese Schlüsselwörter enthalten; die Dateien werden zusammengeführt.
| Schlüsselwort | Was darin steht |
|---|---|
rules | threshold (ein Messwert jenseits von warn/crit für for_s Sekunden) oder expect (ein gelungenes Ereignis mindestens alle every_s Sekunden), begrenzt auf kind oder thing |
actions | Brief-Vorlagen: prompt (ein Text zum Kopieren) oder webhook (derselbe Text, an url gesendet) |
notify | Ziele, webhook oder ntfy, mit min_status |
digest | der Satz am Morgen: {"at": "07:30", "tz": "Europe/Berlin"} |
things | Dinge, von Hand deklariert, vor allem was sie kosten: id, kind, name, labels, url, part_of, price, since |
event_prices | was ein Ereignis kostet, wenn es selbst keinen Betrag trägt: amount je per Einheiten der quantity des Ereignisses, zugeordnet über event und auf Wunsch kind oder thing |
Ein deklarierter Preis zählt ab dem Moment, in dem er zuerst deklariert wird, oder ab since (2026-01-01) für etwas, das es immer schon gab. Ein Ding, das aus der Konfiguration genommen wird, kostet ab dann nichts mehr; entfernt wird es nicht.
Die mitgelieferten Regeln:
{ "rules": [ {"id": "disk-full", "type": "threshold", "kind": "server", "metric": "disk_used_ratio", "warn": 0.8, "crit": 0.92, "for_s": 600, "check": "disk"}, {"id": "memory-low", "type": "threshold", "kind": "server", "metric": "memory_available_ratio", "op": "<", "warn": 0.1, "crit": 0.04, "for_s": 600, "check": "memory"}, {"id": "load-high", "type": "threshold", "kind": "server", "metric": "load5_per_cpu", "warn": 1.5, "crit": 3, "for_s": 900, "check": "load"}, {"id": "backup-daily", "type": "expect", "kind": "backup", "event": "run", "every_s": 93600}, {"id": "job-hourly", "type": "expect", "kind": "hourly-job", "event": "run", "every_s": 4500} ]}Spalten einer Liste
Abschnitt betitelt „Spalten einer Liste“| Spalte | Englischer Name | Bedeutung |
|---|---|---|
ding | thing | Id des Dings, um das es in der Zeile geht; eine Zeile ohne setzt die Zeile darüber fort |
name, art, teil_von | name, kind, part_of | beschreiben das Ding; nach teil_von rollt sein Geld auf |
aufgabe | check | was fällig ist — damit ist die Zeile eine Frist |
fällig | due | wann |
alle | every | monat, quartal, jahr: Die Frist kehrt wieder |
erledigt | done | das Datum, an dem es getan war |
warn_tage | warn_days | so viele Tage vor der Fälligkeit warnen (Standard: am Tag selbst) |
krit_tage | crit_days | so viele Tage nach der Fälligkeit kritisch (Standard: nie) |
betrag, währung, seite | amount, currency, side | mit aufgabe: was offen ist — du schuldest es (aufwand, der Standard), oder es steht dir zu (ertrag); ohne aufgabe und mit je: was das Ding kostet oder bringt |
je | per | stunde, tag, monat, jahr: ein wiederkehrender Betrag |
seit, bis | since, until | ab wann der wiederkehrende Betrag zählt, und wo er endet |
text | summary | ein Satz, der bei der Frist steht — bei einem Plan-Schritt, was fertig heißt |
nach, abstand | after, offset | ein Plan: Dieser Schritt ist abstand (2 Wochen, 14 Tage, 1 Monat) nach dem Schritt in nach fällig |
Wie Zeilen gelesen werden: Listen.
Umgebungsvariablen
Abschnitt betitelt „Umgebungsvariablen“Sie stehen unter Nota betreiben.