Manuelle Instrumentierung

Manuelle Instrumentierung

0:00 Am Ende von Modul fünf stand eine Liste dessen, was der Agent nicht liefert. Genau daran arbeiten wir jetzt. Der Agent kennt Ihre Aufrufe — Ihre Fachlichkeit kennt nur Ihr Code. Das klingt nach viel Arbeit, ist aber überschaubarer, als viele erwarten: Es geht nicht darum, alles zu instrumentieren, sondern die wenigen Stellen, an denen fachlich etwas passiert, das man später wissen möchte.

0:22 Wir schauen uns Spans und Metriken an — und vor allem, wie sich beides sauber mit dem Agent verträgt, ohne dass Zahlen doppelt gezählt werden.

Manuelle Instrumentierung

0:31 Drei Kapitel. Zuerst eigene Spans: wie ein fachlicher Vorgang zu einer Arbeitseinheit im Trace wird, samt Attributen und Fehlerbehandlung. Dann eigene Metriken — Counter, Histogram und beobachtete Werte. Und im dritten Kapitel das Zusammenspiel mit der automatischen Instrumentierung, wo der teuerste Anfängerfehler lauert.

0:50 Am Ende machen Sie die Materialprüfung von Pfandwerk sichtbar — als Span, als Zählwert und als Verteilung.

Eigene Spans und Attribute

0:57 Beginnen wir mit dem Span. Ein Span ist, wie wir in Modul vier gelernt haben, die einzelne Arbeitseinheit innerhalb eines Trace. Bisher hat der Agent sie erzeugt. Jetzt erzeugen Sie selbst welche — für die Vorgänge, die Ihr Geschäft ausmachen und die kein Werkzeug von allein kennen kann. Der Ablauf ist immer derselbe: Sie holen sich einen Tracer, bauen daraus einen Span, starten ihn, setzen ihn als aktuellen Kontext und beenden ihn am Ende.

1:24 Dazwischen nimmt er Attribute auf, kann eine Ausnahme aufzeichnen und trägt einen Status — Unset, Ok oder Error. Denken Sie an eine Stechuhr: Sie stempeln beim Betreten, notieren während der Arbeit, was Sie getan haben, und stempeln beim Verlassen. Der wichtigste Teil ist das Stempeln beim Verlassen. Wer das vergisst, taucht in keiner Auswertung auf.

1:46 Auf dieses Muster kommt es an, nicht auf die einzelnen Zeilen. Drei Dinge sind wichtig. Erstens: Der Span wird gebaut und gestartet, bevor die Arbeit beginnt. Zweitens: Das try-with-resources setzt ihn als aktuellen Kontext — dadurch hängen alle Spans, die währenddessen entstehen, automatisch als Kinder darunter. Drittens und am wichtigsten: das finally. Der Span muss beendet werden, egal was passiert.

2:11 Das ist kein Stilmittel, sondern eine Notwendigkeit — ein nicht beendeter Span erscheint in keinem Backend, und Sie suchen ihn vergeblich. Der catch-Zweig zeigt nebenbei, wie eine Ausnahme sauber am Span landet statt nur im Log. Der erste Punkt ist der entscheidende: Ein Span ohne Attribute lässt sich finden, aber nicht gruppieren.

2:32 Und Gruppieren ist genau das, was Sie im Störfall tun wollen — sind alle Materialarten betroffen oder nur Glas? Der zweite Punkt erinnert daran, warum wir das überhaupt tun: Fachliche Attribute beantworten Fragen, die keine HTTP-Angabe beantwortet. Der dritte ist eine Feinheit mit großer Wirkung: Der Fehlerstatus trennt fachliche Ablehnung von technischem Fehlschlag.

2:54 Und der vierte spart Zeit — eine aufgezeichnete Ausnahme erspart den Sprung ins Log. Die ersten beiden Punkte sind die technischen Klassiker: Span nicht beendet, Kontext nicht gesetzt. Beim zweiten ist das Symptom besonders verwirrend — die Spans existieren, hängen aber an der falschen Stelle im Baum, und der Trace erzählt eine Geschichte, die so nie passiert ist.

3:16 Der dritte Punkt ist ein Datenschutzthema: Attribute mit Klartextdaten von Personen wandern ins Backend und bleiben dort. Und der vierte ist derselbe Fehler wie in Modul vier, nur eine Ebene höher: eine Kennung im Span-Namen statt im Attribut. Namen sollen wenige sein, Attribute dürfen viele Werte haben.

Eigene Metriken

3:34 Vom Einzelfall zur Aggregation. Spans beantworten „warum in diesem Fall", Metriken beantworten „wie oft" und „wie stark" — die Unterscheidung aus Modul zwei. Für fachliche Metriken gilt dasselbe wie für fachliche Spans: Kein Werkzeug liefert sie, weil keines Ihr Geschäft kennt. Der Unterschied zu den Spans ist die Perspektive: Ein Span beschreibt einen Vorgang, eine Metrik beschreibt viele.

3:57 Beide entstehen aus demselben Code an derselben Stelle, beantworten aber völlig verschiedene Fragen — und kosten sehr unterschiedlich viel. Drei Instrumententypen, und die Wahl zwischen ihnen ist folgenreicher, als sie aussieht. Ein Counter zählt monoton aufwärts — er kann nie fallen. Ein Histogram erfasst eine Verteilung von Messwerten. Und ein beobachtetes Instrument liest bei Bedarf einen aktuellen Wert aus, statt bei jedem Ereignis aktiv zu werden.

4:25 Jedes Instrument trägt Name, Beschreibung und Einheit. Die Einheit klingt nach einer Formalität — in Modul zwölf werden Sie sehen, dass Prometheus daraus Namenskonventionen ableitet und dass eine falsche Einheit jede Rechnung kaputt macht. Zwei Dinge sind an diesem Beispiel bemerkenswert. Das Erste ist der Aufbau: Name, Beschreibung, Einheit, bauen — und das passiert einmal beim Start, nicht bei jedem Vorgang.

4:50 Das Zweite ist die Einheit in geschweiften Klammern. Diese Schreibweise ist die Konvention für Dinge, die kein physikalisches Maß haben: Behälter, Anfragen, Nachrichten. Zeiten dagegen schreibt man als s oder ms. Und beachten Sie die letzten beiden Zeilen: Beim Zählen werden Attribute mitgegeben. Genau diese Attribute entscheiden später darüber, ob Sie nach Materialart gruppieren können — und wie viele Zeitreihen dabei entstehen.

5:17 Die Logik dahinter ist die Frage: Kann der Wert auch fallen? Angenommene Behälter können nur mehr werden — also Counter. Die Dauer einer Prüfung ist eine Verteilung vieler Einzelmessungen — also Histogram. Der Füllstand eines Automaten steigt und fällt — also ein beobachteter Wert, den man bei Bedarf abfragt. Die Fußzeile enthält die eigentliche Warnung: Ein Wert, der fallen kann, gehört nie in einen Counter.

5:42 Denn auf Counter wendet man die Funktion rate an, und die interpretiert jeden Rückgang als Neustart. Das Ergebnis sind Zahlen, die plausibel aussehen und falsch sind. Der erste Punkt ist genau dieser Fehler — Counter für einen Füllstand. Der zweite ist die fehlende Einheit; spätestens wenn jemand anders die Metrik auswertet, wird aus Millisekunden versehentlich eine Sekunde, und der Fehler ist um den Faktor tausend daneben.

6:07 Der dritte ist ein Performance-Thema: Instrumente gehören einmal beim Start gebaut, nicht in der Schleife. Und der vierte ist der Vorgriff auf Modul zwölf — Attribute entstehen frei und sprengen später die Kardinalität. Deshalb lohnt der Blick in den Attributvertrag aus Modul vier, bevor Sie das erste Instrument bauen.

Zusammenspiel mit dem Agent

6:26 Jetzt zum Kapitel, in dem die meisten Fehler passieren — und zwar leise. Eigene Instrumentierung und Agent arbeiten gegen dieselbe API, sie sollen sich also ergänzen. Tun sie das nicht sauber, bekommen Sie nicht etwa eine Fehlermeldung, sondern doppelte Zahlen. Der Grund ist einfach: Beide erzeugen Telemetrie über dieselbe Programmierschnittstelle, und keiner von beiden weiß, was der andere schon erfasst hat.

6:50 Diese Verantwortung liegt bei Ihnen, und sie ist der Kern dieses Kapitels. Die Grundlage ist einfach: Manuelle Instrumentierung arbeitet gegen dieselbe API, die auch der Agent bedient. Ihre Spans hängen sich in den vom Agent erzeugten Kontext ein, Ihre Metriken stehen neben dessen Metriken. Die Voraussetzung ist, dass beides denselben Kontext teilt.

7:12 Ist das nicht der Fall, entstehen zwei getrennte Wahrheiten — und zwar beide plausibel. Das ist die unangenehmste Sorte Fehler: Es sieht alles richtig aus, nur die Zahlen stimmen nicht, und niemand weiß, welcher man glauben soll. Diese Schichtung ist die Arbeitsteilung in einem Bild. Der Agent übernimmt die Ränder: eingehende Anfrage, Datenbankzugriff, ausgehender Aufruf.

7:35 Ihr Code übernimmt, was fachlich dazwischen passiert. Und die dritte Ebene ist die, die gern vergessen wird: die Log-Anbindung, damit Log Records dieselbe Trace- und Span-ID tragen. Diese dritte Ebene kostet fast nichts — meist eine Konfigurationszeile — und liefert den größten Teil des Nutzens, den wir in Modul fünfzehn beim Korrelieren einlösen.

7:56 Vier Punkte, aber es ist eigentlich einer. Ein selbst gebauter HTTP-Span neben dem Agent-Span verdoppelt jede Latenzaussage. Doppelte Counter melden zweimal denselben Vorgang und verfälschen jede Quote. Und — das ist die Pointe — der Fehler fällt nicht auf, weil beide Zahlen plausibel aussehen. Es gibt keinen Alarm für „diese Zahl ist doppelt so hoch wie die Wirklichkeit".

8:19 Die Regel, die Sie davor bewahrt, ist erfreulich einfach: Technische Grenzen überlassen Sie dem Agent. Sie instrumentieren nur, was er nicht kennen kann. Sie erweitern jetzt die automatische Instrumentierung gezielt um fachliche Aussagen. Drei Kriterien: Der fachliche Span erscheint als Kind des Agent-Spans, er trägt Materialart und Prüfergebnis, und keine Kennzahl wird doppelt gezählt.

8:42 Der Hinweis verrät die Prüftechnik: Sehen Sie sich einen einzelnen Vorgang an und zählen Sie die Spans. Summen zu vergleichen hilft nicht — eine Verdopplung sieht in der Summe aus wie doppelter Verkehr, und den kann man nicht ausschließen. Der erste Punkt ist das Symptom eines fehlenden Kontexts: Ihr Span erscheint als eigener Trace statt als Kind.

9:03 Der zweite ist der Reflex, den wir in Modul fünf schon besprochen haben — den Agent abschalten, sobald man selbst instrumentiert. Der dritte ist ein Volumenproblem: Log-Ausgaben werden zusätzlich als Span Events erfasst, und das verdoppelt die Datenmenge ohne neuen Erkenntniswert. Und der vierte ist eine Haltungsfrage, die sich durch das ganze Seminar zieht: Es wird alles instrumentiert, was geht, statt was eine Frage beantwortet.

Übung

9:28 In der Übung machen wir die Materialprüfung sichtbar — den Vorgang, der für Pfandwerk fachlich zentral ist und in der bisherigen Telemetrie schlicht nicht vorkommt. Und wir prüfen das Ergebnis gegen eine Handzählung, was sich altmodisch anhört und der zuverlässigste Test ist, den es gibt. Vier Ergebnisse: ein Span je Prüfung mit Materialart und Ergebnis, ein Counter für angenommene Behälter, ein Histogram für die Prüfdauer — und die Zahlen stimmen mit einer Handzählung überein.

9:55 Der Hinweis enthält die interessante Entscheidung: Abgelehnte Behälter sind kein technischer Fehler. Ein Automat, der eine Plastikflasche korrekt ablehnt, hat fehlerfrei gearbeitet. Wenn Sie das als Error markieren, treiben Sie Ihre Fehlerquote nach oben und alarmieren später auf den Normalbetrieb. Begründen Sie Ihre Wahl schriftlich — diese Unterscheidung kommt in Modul achtzehn wieder.

10:18 Der rote Faden: erst der Span, dann die Unterscheidung von Ablehnung und Fehler, dann die Instrumente — einmalig beim Start, wie besprochen. Danach lösen Sie zehn Rücknahmen aus und prüfen Spans wie Zahlen. Und im fünften Schritt rechnen Sie gegen eine Handzählung gegen. Die Fußzeile sagt Ihnen schon, was Sie finden werden, falls die Zahlen abweichen: Es liegt fast immer an einem doppelt erfassten oder an einem nie beendeten Span.

10:43 Beides haben wir in diesem Modul behandelt. Der erste Punkt ist die Statusfrage, über die wir gerade gesprochen haben — und er ist der folgenreichste, weil er sich bis in die Alarmierung durchzieht. Der zweite ist der Mittelwert statt der Verteilung; das ist so verbreitet, dass Modul vierzehn ein eigenes Kapitel dafür hat.

11:01 Der dritte ist Bequemlichkeit: Die Handzählung entfällt, und der Fehler fällt erst im Dashboard auf, wenn ihn niemand mehr einem Commit zuordnen kann. Und der vierte ist ein echter Programmierfehler — Attribute nach dem Beenden des Spans setzen. Das erzeugt keine Fehlermeldung, die Attribute verschwinden einfach.