Chart-Annotations markieren wichtige Ereignisse - Deploys, Releases, Marketing-Kampagnen, Vorfälle, eigene Meilensteine - auf jedem Zeitreihen-Chart in Zenovay. Wenn sich Traffic oder Umsatz verschiebt, sehen Sie unmittelbar, was sich um denselben Zeitpunkt geändert hat, ohne das Dashboard zu verlassen.
Warum Annotations wichtig sind
Die meisten Analytics-Fragen lassen sich auf "was hat sich geändert?" reduzieren. Ein unerwarteter Einbruch am Dienstagnachmittag ist viel einfacher zu triagen, wenn Sie um 14:32 die Markierung "deploy: release v2.5" sehen. Annotations machen aus dem Dashboard einen einzigen Zeitstrahl, auf dem Geschäftsmetriken und Betriebsereignisse nebeneinander leben.
Die fünf Annotation-Typen
| Typ | Farbe | Typische Nutzung |
|---|---|---|
deploy | Blau | Code-Deploys, Infrastrukturänderungen, Konfigurations-Rollouts |
release | Smaragd | Öffentliche Release-Ankündigungen, Versionsschnitte |
campaign | Bernstein | Marketing-Kampagnen, Werbestarts, E-Mail-Versand |
incident | Rot | Kundenwirksame Vorfälle, Ausfälle |
custom | Violett | Alles andere - Vorstandstermine, Partner-Integrationen, Audits |
Jeder Typ hat ein eigenes Icon und eine eigene Farbe, damit Sie die Chip-Leiste unter dem Chart auf einen Blick einordnen können.
Drei Wege, Annotations zu erstellen
Option 1 - Im Dashboard
Öffnen Sie das Dashboard Ihrer Website und wählen Sie den Tab Analytics, dann klicken Sie auf das Notiz-Icon an einem beliebigen Punkt des Visitor-Charts. Ein Dialog mit Details für den Tag öffnet sich mit drei Tabs: Notes, Annotations und Commits. Im Tab Annotations wählen Sie einen Typ (deploy, release, campaign, incident oder custom), geben eine Nachricht ein und speichern ab. Der Marker erscheint sofort auf dem Chart.
Das ist die schnellste Variante für einzelne Ad-hoc-Ereignisse. Wenn Sie regelmäßig Deploys absenden, ist die CLI unten die bessere Wahl.
Option 2 - Zenovay-CLI (empfohlen für CI)
Die CLI ist der kanonische Weg, Deploys aus einer CI-Pipeline heraus zu markieren. Sie übernimmt die Authentifizierung über Ihren Account-Login und funktioniert auf macOS, Linux und Windows.
zenovay annotation create --type=deploy --message="release v2.5"
Hängen Sie sie als letzten Schritt Ihrer Deploy-Pipeline an, damit
sich jeder Release automatisch markiert. Der Befehl beendet sich mit
einem eindeutigen Code bei Plan-Limits (4) oder Duplikat (5) Fehler,
damit Ihre Pipeline jeden Fall behandeln kann. Vollständige Flags und ein
GitHub-Actions-Beispiel finden Sie im
CLI-Integrations-Guide.
Option 3 - REST-API
Es gibt auch einen /api/annotations-Endpunkt, den das Dashboard selbst
nutzt. Er authentifiziert sich über Ihre Dashboard-Session (dieselbe
Anmeldung wie im Browser), daher ist es nur praktisch für einen Server,
der bereits eine gültige Session hält. Externe zv_* API-Keys werden
auf diesem Endpunkt derzeit nicht akzeptiert. Daher ist die CLI oben
das richtige Werkzeug für CI und andere automatisierte Umgebungen - sie
kümmert sich um die Authentifizierung. Siehe die
Chart-Annotations-API-Referenz
für die vollständige Request- und Response-Form.
Plan-Limits und Verhalten
- Free: 10 Annotations pro Team und Monat.
- Pro und höher: unbegrenzt.
Eine gleichartige Annotation innerhalb von 5 Minuten zu einer bestehenden wird abgelehnt, damit eine fehlkonfigurierte CI-Pipeline den Zeitstrahl nicht mit Duplikaten überflutet. Zwei Annotations desselben Typs mit unterschiedlichen Nachrichten (beispielsweise "checkout kaputt" und später "checkout repariert") sind beide erlaubt.
Wo Annotations erscheinen
- Unter jedem kundennahen Analytics-Chart als farbige Chip-Leiste. Hover zeigt die vollständige Nachricht und die genaue Zeit.
- Im Conversion-Incident-Triage-Panel als "verdächtige Änderung", wenn die Annotation innerhalb von ±2 Stunden um den Vorfallsbeginn liegt - hilft der KI-Triage zu beantworten "was hat sich nahe diesem Einbruch geändert?".
- Auf der bestehenden Notes-Icon-Position im Domain-Visitor-Chart, falls Sie das ältere Notes-Feature schon nutzen. Beide Surfaces bleiben automatisch synchron.
Die Chip-Leiste lesen
Jeder Chip unter einem Chart ist farbcodiert nach Typ, mit dem Typ-Icon links. Die fünf Farben bleiben über alle Charts und Seiten konsistent, sodass Sie die Leiste nach kurzer Eingewöhnung auf einen Blick scannen können: ein Cluster Blau bedeutet Deploys, Bernstein bedeutet Kampagnen, Rot bedeutet Vorfälle. Der Chip zeigt Ihre Nachricht und die Erstellungs- zeit; per Hover sehen Sie den vollen Zeitstempel.
Datenschutz: öffentliche Dashboards zeigen NIE Annotations
Wenn Sie einen öffentlichen Dashboard-Link mit jemandem außerhalb Ihres Teams teilen, sind Annotations dort ausgeblendet. Deploy- und Release-Nachrichten sind für das betreibende Team gedacht, nicht für Besucher. Es gibt keine Möglichkeit, Annotation-Nachrichten öffentlich zu zeigen.
Häufige Muster
Jeden Production-Deploy automatisch markieren - CLI-Befehl als Post-Deploy-Schritt anhängen. Nach dem Verdrahten kein manueller Aufwand mehr.
Kampagnenstart markieren -
zenovay annotation create --type=campaign --message="Frühjahrsaktion"
genau dann ausführen, wenn die Kampagne startet. Beim späteren
Vergleich des Traffic-Lifts ist der Marker bereits auf dem Chart.
Bekannten Vorfall markieren - Wenn Sie wissen, dass ein Ausfall auftrat, posten Sie eine Incident-Annotation, damit der Chart den Einbruch sichtbar erklärt. Passt natürlich zum Conversion-Incident- Triage, das unerklärte Einbrüche automatisch erkennt.
Fehlerbehebung
- "Annotation limit reached": Free-Plan-Monatslimit erreicht. Upgrade auf Pro für unbegrenzt.
- HTTP 409 Dedup-Fehler: Sie versuchen, eine Annotation mit demselben Typ und derselben Nachricht innerhalb von 5 Minuten zu einer bestehenden zu posten. Warten Sie, ändern Sie die Nachricht, oder akzeptieren Sie, dass der erste Marker bereits das Ereignis darstellt. (Die CLI gibt Exit-Code 5 für diesen Fall zurück.)
- Die Chip-Leiste erscheint nicht: Bestätigen Sie, dass für die Website mindestens eine Annotation existiert. Die Leiste bleibt ausgeblendet, wenn nichts anzuzeigen ist.
- Der Chip ist in der falschen Sprache oder im falschen Theme: Theme folgt dem Theme des Dashboards; Sprache folgt der Browser-Lokalität. Beides wechselt automatisch.