Start/Doks/Eigene Metriken

Vertrag für eigene Metriken

Vertragsversion 2.1.0 · Payload schema_version 2.0

Mit eigenen Metriken liefert der Dienst Ihrer Erweiterung die Zahlen, auf die es ihm ankommt (Conversions, Umsatz, Backend-Zustand, Trichter), in dasselbe Panel, das bereits Installationen und den Zustand im Chrome Web Store verfolgt. Der Vertrag ist metadatengesteuert und bedient zwei Oberflächen: Jede Metrik deklariert, wo und wie sie im Dashboard und im Telegram-Status erscheint, sodass das Panel ein generischer Renderer ohne produktspezifischen Code bleibt.

1. Funktionsweise (zwei Oberflächen)

Ihr Dienst stellt einen Metrik-Endpunkt bereit. Ext Ops Panel ist der Client: Es ruft diesen Endpunkt ab (nie umgekehrt) und stellt die Antwort dar. Die Antwort steuert zwei Oberflächen gleichzeitig:

• Dashboard-Tabs in der Detailansicht der Erweiterung: Tabs, Abschnitte und Darstellungsarten pro Metrik.
• Telegram-Status: logische Zeilen aus denselben Metriken, pro Metrik gefiltert und formatiert.

Das Panel führt Ihre Metriken mit den panel-eigenen Basismetriken zusammen (Installationen / Deinstallationen / Neuinstallationen / Feedback / Chrome Web Store / Zustand), die im reservierten Tab base und in der gleichnamigen Telegram-Zeile liegen.

2. Der Endpunkt und die Authentifizierung

Das Panel ruft Ihren Endpunkt per GET auf und erwartet die v2-Payload als Antwort mit Status 200. Zwei Abrufmodi haben dieselbe Form:

• Auf Abruf: wird ausgelöst, wenn ein Nutzer die Detailansicht öffnet. Begrenzt auf höchstens 1 Anfrage pro Minute und Quelle, in allen Tarifen einschließlich Free.
• Monitoring: planmäßig in Tarifen mit Monitoring; stellt den Telegram-Status und die Flankenalarme zusammen.

Als Authentifizierung dient eines von none, bearer oder api_key_header. Geheimnisse werden im Panel-Backend verschlüsselt gespeichert und nie an die Dashboard-Erweiterung weitergegeben. Schlägt ein Abruf fehl, degradiert das Panel kontrolliert (letzter Snapshot oder ausgeblendet), ohne die Basismetriken zu beeinträchtigen.

3. Payload-Struktur

Die Payload der obersten Ebene enthält das Layout (Tabs, Abschnitte, Telegram-Zeilen) und das Metrik-Array.

4. Tabs und Tab-Symbole

Ein Tab ist { id, title, order, icon? }. Der reservierte Tab base gehört dem Panel selbst (icon="layout-dashboard"); Ihr Dienst ergänzt die übrigen. Sind viele Tabs geöffnet, zeigt der aktive Tab Symbol + Titel, die anderen schrumpfen auf das Symbol (der Titel bleibt im Tooltip und im aria-label).

Zwei Tab-IDs sind für das Panel reserviert: base (der Basic-Tab) und monitoring (der eingebaute Monitoring-Tab, den Heartbeat-Berichte füllen, siehe den Monitoring-Vertrag). Deklarieren Sie sie nicht in tabs: eine Deklaration wird ignoriert, Titel, Icon und Reihenfolge legt das Panel fest. Metriken adressieren sie weiterhin über dashboard.tab.

Der Wert icon ist eines von zwei Dingen:

• Ein Lucide-Symbolname in kebab-case-ASCII (entspricht ^[a-z][a-z0-9-]*$), z. B. trending-up. Ein wohlgeformter, aber nicht unterstützter Name fällt auf das Standardsymbol (square) zurück, sodass die Leiste nie bricht.
• Ein einzelnes Emoji, z. B. 💰 oder 🚀, als Text dargestellt.

Das Panel liefert einen kuratierten Katalog von 60 Lucide-Namen (schlank für das MV3-Bundle). Derselbe Katalog dient für Tab-Symbole und Ziel-Symbole (Abschnitt 5.3):

• layout-dashboard
• activity
• gauge
• layers
• plug
• dollar-sign
• banknote
• wallet
• credit-card
• receipt
• bar-chart-3
• line-chart
• pie-chart
• trending-up
• trending-down
• users
• user
• alert-triangle
• bell
• clock
• git-branch
• package
• box
• database
• server
• cpu
• zap
• globe
• pencil
• puzzle
• funnel
• filter
• square
• circle
• hash
• percent
• tag
• flag
• user-plus
• log-in
• plus-square
• shopping-cart
• check-circle
• send
• mail
• download
• upload
• star
• heart
• eye
• mouse-pointer-click
• share-2
• message-square
• target
• rocket
• file-text
• bookmark
• calendar
• key
• play

5. Metrik: Wert + zwei Platzierungsblöcke

Eine Metrik trägt einen typisierten Wert plus zwei unabhängige Blöcke: dashboard (wo und wie in der Erweiterung) und telegram (wo und wie in der Nachricht). Jeder kann weggelassen oder über show:false ausgeblendet werden, sodass eine Metrik auch nur auf einer Oberfläche erscheinen kann.

5.1. Arten (Datentyp + Payload)

Arten sind eine offene Menge: Eine unbekannte Art ignoriert der Renderer (vorwärtskompatibel).

Eine Metrik table:

{ "id": "queues", "kind": "table", "label": "Mail queues",
  "items": [ { "queue": "outbound", "size": 3, "oldest": "2m" },
             { "queue": "deferred", "size": 0, "oldest": "-" } ],
  "dashboard": { "show": true, "tab": "backend", "section": "engines", "order": 5, "render": "table",
                 "options": { "columns": ["queue", "size", "oldest"] } } }

5.2. Darstellung (Anzeige im Dashboard)

dashboard.render wählt die Darstellung (entspricht meist kind, kann aber abweichen, z. B. ein percent als badge zeigen). Ebenfalls eine offene Menge.

intraday vs. chart. Die Achse von chart ist täglich (points[].date = YYYY-MM-DD), und seine Monatsansicht zeigt nur die letzten 30 Punkte, daher passen die 96 Zeitfenster von heute nicht hinein. intraday ist das panel-eigene Heute-Diagramm, als Vertragsart bereitgestellt: dieselbe Konvention, bei der minute die Minuten ab Beginn des UTC-Tages zählt (0, 15, …, 1425), aber Reihen und Daten deklariert die Quelle. Senden Sie nur nicht leere Zeitfenster, den Rest füllt das Panel auf.

Ein leeres Zeitfenster ist null, nicht 0. Bei einem Durchschnitt (z. B. mittlere Conversion-Zeit) wäre eine Null gelogen, deshalb bricht die Linie ab, statt auf null zu fallen. Ein fehlendes Zeitfenster und value: null sind gleichwertig: Die Linie bricht ab, es wird kein Balken gezeichnet, und die Hover-Anzeige zeigt einen Strich.

Gestapelt: Gesamtwert und Teile in einem Diagramm und einer Liste. Wenn sich eine Metrik aus Teilen zusammensetzt (etwa die Seitenaufrufe zweier Websites), senden Sie Gesamtwert und Teile als EINE Metrik: Das Panel zeichnet die Teile übereinander, und die Legende schaltet jeden Teil ein und aus, ohne zusätzliche Tabs und ohne Dropdown-Filter. Beide Erweiterungen sind additiv: Ein Renderer, der sie nicht kennt, zeichnet dieselbe Metrik wie bisher.

Diagramm: kind: "series" mit dashboard.options.stack: true. Die Reihen werden in Array-Reihenfolge gestapelt, die erste ist die unterste Schicht. Das Panel zeichnet eine Säule pro Tag (in der Gesamtzeit pro 7-Tage-Fenster) mit einem Segment pro sichtbarer Reihe, sodass die Oberkante einer Säule genau die Summe der sichtbaren Reihen ist; ein Tag, an dem alle null sind, hat keine Säule. Ein Klick auf einen Legendeneintrag blendet eine Schicht aus (die letzte sichtbare bleibt an); der Rest wird ab null neu gezeichnet, und die Werteachse folgt der sichtbaren Summe. Beim Hovern über eine Säule oder beim Wechsel mit den Pfeiltasten zeigt die Anzeige jede sichtbare Schicht und eine Zeile Total. Die Gesamtzeit stapelt den gleitenden 7-Tage-Durchschnitt jeder Reihe, markiert mit ~. Jeder andere Wert von stack behält die überlagerten Linien bei.

Liste: kind: "breakdown" mit dashboard.options.stack als geordneter Liste von Teilen [{key, label}] und parts: {"key": number} an jedem Element, in items und in jedem ranges-Fenster. value muss der Summe aller Teile entsprechen. Das Panel zeigt pro Teil einen Chip, der ihn für die ganze Karte über alle Fenster hinweg umschaltet. Eine Zeile zeigt die Summe ihrer sichtbaren Teile, Zeilen mit null werden ausgeblendet, die Liste wird nach dieser Summe neu sortiert, und der Balken wird in ein Segment pro sichtbarem Teil geteilt. Mit map: "countries" folgen die Kreise den sichtbaren Summen. Ein Element ohne parts zählt vollständig, egal was ausgeschaltet ist.

{ "id": "site_sources", "kind": "breakdown", "label": "Sources",
  "items": [ { "label": "Search engines", "value": 812, "parts": { "makcards": 790, "journalingapp": 22 } } ],
  "ranges": { "today": [ { "label": "Search engines", "value": 30, "parts": { "makcards": 29, "journalingapp": 1 } } ],
              "month": [ { "label": "Search engines", "value": 812, "parts": { "makcards": 790, "journalingapp": 22 } } ] },
  "dashboard": { "show": true, "tab": "site", "section": "site_sources", "render": "breakdown",
                 "options": { "defaultRange": "month",
                              "stack": [ { "key": "makcards", "label": "makcards.online" },
                                         { "key": "journalingapp", "label": "journalingapp.app" } ] } } }

Kachel: eine kpi-Kachel vom Typ number oder delta nimmt dieselbe dashboard.options.stack-Liste und parts: {"key": number} an der Metrik selbst. Der große Wert bleibt value und muss der Summe aller Teile entsprechen. Darunter zeigt das Panel die Teile in einer Reihe in der Reihenfolge des Stapels (auf einer schmalen Kachel bricht die Reihe um), in der Farbe, die derselbe Name auf einem gestapelten Diagramm des Tabs hat; ein Teil mit null wird abgeschwächt dargestellt. Die Kachel hat keine Schalter. Die Kopfzeilen der Projektliste und Telegram lesen weiterhin value.

{ "id": "site_views_today", "kind": "number", "label": "Page views", "value": 42,
  "parts": { "portal": 30, "cabinet": 4, "backoffice": 8 },
  "dashboard": { "show": true, "tab": "site", "section": "site_today", "render": "kpi",
                 "options": { "stack": [ { "key": "portal", "label": "zakazindia.ru" },
                                         { "key": "cabinet", "label": "Client cabinet" },
                                         { "key": "backoffice", "label": "Backoffice" } ] } } }

5.3. Die Projektliste: Nutzer und Ziele aus dem Basis-Tab

Die Projektliste zeigt einige Zahlen eines Webdienstes, ohne ihn zu öffnen. Das Panel liest sie nur aus dem base Tab, und nur wenn die Metrik einen numerischen value hat. Der erste Treffer gewinnt.

Ein Ziel ist eine Zielaktion Ihrer Nutzer: Registrierungen, Käufe, gesendete Formulare. Sie wählen das Zeitfenster der Zahl, und das Panel zeigt sie unverändert. Wir empfehlen, heute zu zählen und das Zeitfenster im Label zu nennen (zum Beispiel Registrierungen heute). Das Label ist der Tooltip, bis zu 80 Zeichen. Das Feld icon nimmt einen Namen aus dem Katalog in Abschnitt 4; Emoji werden für Ziele nicht akzeptiert. Ohne Symbol oder mit einem unbekannten Namen zeichnet das Panel target. Eine Null wird als gedämpfter Strich angezeigt.

{ "id": "goal_1", "kind": "number", "label": "Sign-ups today", "value": 12, "icon": "user-plus",
  "dashboard": { "show": true, "tab": "base", "section": "goals", "render": "kpi" } }

Das Panel speichert nur die letzten Werte, wie bei DAU. Jeder erfolgreiche Abruf ersetzt sie, und ein Ziel, das nicht mehr in der Antwort ist, verschwindet aus der Liste.

Mehrere Oberflächen

Eine Custom-Metrics-Quelle gehört zu einer Oberfläche Ihres Dienstes, und das Panel speichert die Zahlen pro Oberfläche. Die Projektliste zeigt ihre Summe; die Projektseite zeigt jede Oberfläche einzeln.

• Mehrere Quellen einer Oberfläche zählen als die zuletzt abgefragte. Quellen ohne Oberfläche bilden eine weitere Gruppe.
• Es zählen nur Produktionsoberflächen. Eine Oberfläche in einer Staging-, Test- oder Entwicklungsumgebung bleibt außen vor.
• Eine Oberfläche, deren letzte Zahlen mehr als 48 Stunden hinter den frischesten liegen, bleibt außen vor.
• Jedes Zeitfenster wird über die Oberflächen addiert, die es senden, und Ziele werden nach id addiert, daher muss ein Ziel auf jeder Oberfläche dasselbe bedeuten.
• Die Summe ist eine Obergrenze: Wer zwei Oberflächen nutzt, wird doppelt gezählt.

Chrome-Erweiterungen

Eine Erweiterung nutzt dieselbe Konvention. Sendet ihr Feed dau und Ziele auf dem Tab base, zeigt die Projektliste sie in einer weiteren Zeile unter den Zählern für Installationen, Deinstallationen, Feedback und Neuinstallationen, im selben Format wie die Heute-Zeile eines Webdienstes.

• WAU und MAU einer Erweiterung werden in der Liste nicht angezeigt; ihre Spalte „Nutzer“ ist die Nutzerzahl aus dem Chrome Web Store.
• Zählen Sie DAU und Ziele für den aktuellen UTC-Tag: Die Zähler in derselben Zeile verwenden UTC-Tage.
• Mehrere Quellen einer Erweiterung werden nach den obigen Regeln summiert. Eine Veränderung gegenüber gestern gibt es nicht.
• Nur der Autor sieht die Zeile. Die Aktualisieren-Schaltfläche der Zeile ruft auch die benutzerdefinierten Metriken ab.

5.4. Schwellenwerte (warn und crit)

Eine numerische Metrik kann thresholds enthalten. Dann berechnet das Panel die Severity der Metrik selbst, bei jedem Abruf und bei jeder Heartbeat-Annahme, und zeigt die Grenzen neben dem Wert: 41 (threshold 20/100), gelb zwischen warn und crit, rot ab crit. Die Severity, die Ihr Dienst für eine solche Metrik sendet, wird durch die berechnete ersetzt.

{
  "id": "queue",
  "kind": "number",
  "label": "Mail queue",
  "value": 41,
  "thresholds": { "direction": "above", "warn": 20, "crit": 100, "recover": 15 },
  "dashboard": { "show": true, "tab": "backend", "section": "mail", "order": 1, "render": "kpi" },
  "telegram": { "show": true, "line": "mail", "pos": 10, "format": "queue {value}", "when": "severity>=warn" }
}

• Die Schwellenwerte vergleichen value; bei duration vergleichen sie seconds (sonst minutes), bei bytes vergleichen sie bytes (sonst kb). Nicht numerische Kinds wie status, list oder table können keine Schwellenwerte haben.
• Keine Zahl in diesem Durchlauf bedeutet idle: grau, und es zählt für kein Licht.
• Ein fehlerhafter Block wird in einem Heartbeat-Bericht abgelehnt (422 invalid_report). In einer abgerufenen Antwort wird er verworfen, die Metrik wird wie gesendet gezeichnet und der Grund erscheint als letzter Fehler der Quelle.
• In einem Heartbeat-Bericht ist das Licht des Heartbeats nie unter einem überschrittenen Schwellenwert (siehe den Monitoring-Vertrag).

Geplante Abfrage. Bei einem Webdienst können Sie in den Einstellungen einer Quelle die geplante Abfrage einschalten. Das Panel ruft den Endpunkt dann in einem Intervall ab, das von der Untergrenze Ihres Tarifs (5 Minuten bei Trial und Indie, 1 Minute bei Studio und Fleet) bis 24 Stunden reicht, mit derselben Anfrage wie jeder Abruf: ein ehrlicher User-Agent und höchstens eine Anfrage pro Minute. Sie belegt eine Monitoring-Unit und ist daher bei Free nicht verfügbar. Ein überschrittener Schwellenwert öffnet einen Vorfall für diese Metrik und benachrichtigt Sie; eine wiederholte Überschreitung benachrichtigt nicht erneut. Der Vorfall schließt nach einem Abruf ohne Überschreitung, wenn das Intervall 1 Stunde oder länger ist, und nach zwei Abrufen in Folge ohne Überschreitung, wenn es kürzer ist. Ein fehlgeschlagener Abruf ändert nichts und zeigt seinen Grund als letzten Fehler. Bis zu 20 Metriken mit Schwellenwerten pro Quelle erzeugen Vorfälle.

6. Die Palette gehört dem Panel

Diagramm- und Reihenfarben vergibt das Panel aus Marken-Tokens, nicht die Quelle. options.series[] trägt nur die Identität ({key,label,order}); ein Feld color in der Payload ist nur ein Hinweis und wird ignoriert. Semantische Schlüssel werden festen Tokens zugeordnet (paid der Akzentfarbe, free einem gedämpften Neutralton, failed/error der Gefahrenfarbe, ready/success der Erfolgsfarbe); andere Schlüssel erhalten die kategoriale Markenpalette der Reihe nach. Flächen und Linien der Reihen haben in beiden Themes mindestens 3:1 Kontrast (WCAG 1.4.11), Text und Beschriftungen mindestens 4,5:1. Das schützt die Marke vor beliebigen externen Hex-Farben.

7. Telegram-Vorlagen

telegram.header ist die Kopfzeile der Nachricht; telegram.lines[] sind logische Zeilen ({ id, order, prefix, when }). Der Composer sammelt jede Metrik mit einem bestimmten telegram.line, filtert nach when, sortiert nach pos, rendert jede über ihre Vorlage format und verbindet sie mit dem sep der jeweiligen Metrik. Das prefix der Zeile wird zuerst ausgegeben. Alles ist reiner Text.

8. Sichtbarkeitsbedingungen (when)

when steuert, ob ein Metrikfeld (oder eine ganze Telegram-Zeile) angezeigt wird. Werte:

Unbekannte when-Werte verhalten sich wie always (vorwärtskompatibel).

9. Beispiel-Payload

{
  "schema_version": "2.0",
  "generated_at": "2026-07-02T23:17:30Z",
  "tabs": [
    { "id": "conv", "title": "Conversions", "order": 1, "icon": "trending-up" }
  ],
  "sections": [
    { "tab": "conv", "id": "by_hour", "title": "By hour", "order": 0 }
  ],
  "telegram": {
    "header": "{name} • {cws.users} • {cws.rating}★ ({cws.rating_count})",
    "lines": [
      { "id": "base", "order": 0 },
      { "id": "conv", "order": 1, "prefix": "{sev} Conv " }
    ]
  },
  "metrics": [
    {
      "id": "conv_today",
      "kind": "number",
      "label": "Conversions today",
      "value": 254,
      "severity": "ok",
      "shareable": true,
      "dashboard": {
        "show": true,
        "tab": "conv", "section": "by_hour", "order": 10,
        "name": "Today", "render": "kpi", "options": {}
      },
      "telegram": {
        "show": true,
        "line": "conv", "pos": 20,
        "format": "today {value}", "sep": " • ", "when": "always"
      }
    }
  ]
}

10. Der maschinenlesbare Vertrag

Die formale, importierbare Beschreibung dieses Endpunkts ist die OpenAPI-3.1-Datei. Sie trägt dieselbe Vertragsversion (2.1.0) und ist das einzige kanonische maschinenlesbare Artefakt, gemeinsam für alle Sprachen.