Datenmodell und Semantic Conventions

Datenmodell und Semantic Conventions

0:00 Dieses Modul klingt nach dem trockensten des ganzen Seminars, und es ist das folgenreichste. Es geht um Namen. Genauer: darum, dass ein Attribut, das in drei Diensten anders heißt, kein Attribut ist, sondern drei. Alles, was wir an Tag zwei und drei an Abfragen, Dashboards und Alarmen bauen, steht und fällt damit, dass die Daten vergleichbar benannt sind.

0:22 Und das ist keine Aufgabe, die man nachträglich erledigt — nachträglich umbenennen heißt, die Historie zu verlieren. Deshalb steht dieses Modul vor der ersten Zeile Instrumentierung.

Datenmodell und Semantic Conventions

0:33 Wir schauen uns drei Ebenen an. Zuerst die Resource: Wer hat diese Telemetrie gesendet, aus welcher Umgebung, mit welcher Bibliothek? Dann das Datenmodell der Signale selbst — Spans, Metriken, Log Records und die gemeinsame Kennung, die sie verbindet. Und zum Schluss die Semantic Conventions, also die Benennungsvereinbarungen, die OpenTelemetry mitliefert. Am Ende schreiben Sie für Pfandwerk einen Attributvertrag auf.

1:00 Das ist genau so verbindlich gemeint, wie es klingt.

Resource, Scope und Schema

1:04 Fangen wir mit der Frage an, die jedes Telemetriesystem als Erstes beantworten muss: Woher kommen diese Daten? Das klingt trivial, ist es aber nicht — in einer Umgebung mit dreißig Diensten, mehreren Umgebungen und vielen Instanzen ist die Antwort überraschend oft unklar. Genau dafür gibt es die Resource. Zwei Begriffe. Die Resource beschreibt die Einheit, die Telemetrie erzeugt: Dienst, Instanz, Umgebung, Laufzeitumgebung.

1:29 Der Instrumentation Scope benennt die Bibliothek, die ein einzelnes Signal erzeugt hat — das hilft, wenn Sie wissen wollen, ob ein Span vom Agent oder aus Ihrem eigenen Code stammt. Beide hängen an jedem Datenpunkt. Stellen Sie sich einen Brief vor: Die Resource ist der Absender, der Scope ist der Vermerk, mit welcher Maschine er geschrieben wurde.

1:50 Ohne Absender ist ein Brief nicht zuzuordnen — und genau so verhält es sich mit Telemetrie ohne Resource. Diese fünf Attribute sind so etwas wie das Pflichtprogramm. Der Dienstname beantwortet, wer sendet; die Version, welcher Stand; die Instanz-Kennung, welche Kopie; die Umgebung, ob Produktion oder Test. Alle sind stabil, Sie können sich also darauf verlassen.

2:13 Besonders wichtig ist die Fußzeile: Das ältere deployment.environment ist abgekündigt, gültig ist deployment.environment.name. Solche Umbenennungen passieren selten, aber sie passieren — und sie sind ein guter Grund, Attributnamen an einer Stelle zu pflegen statt in dreißig Deployment-Dateien. Worauf es bei diesem Beispiel ankommt, ist nicht die Syntax, sondern die Erkenntnis: Das hier ist kein Code. Das sind Umgebungsvariablen.

2:40 Die Resource lässt sich vollständig von außen setzen, ohne die Anwendung anzufassen — und das ist genau richtig so, denn ob ein Dienst in Produktion oder Test läuft, weiß der Quelltext nicht. Eine Feinheit am Rande, die in der Praxis Verwirrung stiftet: Die eigene Variable für den Dienstnamen schlägt den Wert aus der allgemeinen Attributliste.

3:00 Wer beides setzt, gewinnt nicht doppelt, sondern wundert sich. Der erste Punkt ist der mit Abstand häufigste: Der Dienstname bleibt auf dem Vorgabewert, und in Ihrer Übersicht sehen alle Dienste gleich aus. Der zweite ist gefährlicher als er klingt — fehlt die Umgebung, mischen sich Testdaten in die Produktionssicht, und niemand merkt es, weil die Zahlen ja plausibel aussehen.

3:22 Der dritte verhindert jeden Vergleich zwischen Instanzen, und das ist genau die Analyse, die man bei Lastproblemen braucht. Der vierte ist Pflege: Das abgekündigte Attribut wird weitergeschrieben, weil es funktioniert — bis es das irgendwann nicht mehr tut.

Spans, Metriken und Log Records

3:36 Von der Frage nach dem Absender gehen wir jetzt zum Inhalt. Jedes der drei Signale hat ein eigenes Datenmodell — und einen gemeinsamen Nenner, der sie verbindet. Dieser gemeinsame Nenner ist das, was wir in Modul zwei als Verknüpfungspunkt gesucht haben. Ein Span, eine Metrik und ein Log Record sind technisch drei verschiedene Dinge mit drei verschiedenen Modellen.

3:57 Was sie zusammenhält, ist eine einzige Kennung — und wenn die fehlt, haben Sie drei unabhängige Datensammlungen statt einer Observability-Plattform. Ein Span trägt Name, Zeiten, Trace-ID, Span-ID und die Beziehung zu seinem übergeordneten Span. Dazu kommen vier Angaben, die gerne vergessen werden: Span Kind ordnet ihn ein, Status meldet den Ausgang, Events halten Zeitpunkte innerhalb des Spans fest, Links verbinden ihn mit Vorgängen, zu denen keine Eltern-Kind-Beziehung besteht.

4:26 Und der entscheidende Satz steht am Schluss: Ein Log Record trägt dieselbe Trace- und Span-ID. Damit ist ein Log nicht länger ein isolierter Text, sondern ein Detail zu einem konkreten Vorgang. Genau das macht die Korrelation später möglich. Span Kind sieht nach einer Formalität aus und ist keine. Das Kind sagt dem Backend, ob ein Span eine Dienstgrenze markiert — und daraus baut es Dienstübersichten, Abhängigkeitskarten und Service Graphs.

4:53 Die Logik ist einfach: Was hereinkommt, ist SERVER, was hinausgeht, ist CLIENT. Nachrichten haben zwei Seiten, PRODUCER und CONSUMER. Und alles, was innerhalb eines Dienstes passiert, ist INTERNAL. Wenn Sie alles als INTERNAL markieren, funktioniert Ihr Tracing technisch, aber das Backend kann keine einzige Dienstgrenze erkennen.

5:12 Das ist der Unterschied zwischen Daten haben und Fragen beantworten. Hier steht die Antwort auf die Frage aus Modul zwei, welcher Verknüpfungspunkt die Signale verbindet. Die Trace-ID gilt für den ganzen Vorgang über alle Dienste hinweg. Die Span-ID benennt die einzelne Arbeitseinheit darin. Und ein Log Record, der beide trägt, ist damit dem Vorgang zuordenbar. Das Schöne daran: Sie müssen dafür nichts erfinden.

5:38 Diese Kennungen entstehen ohnehin, sobald Sie instrumentieren. Sie müssen nur dafür sorgen, dass Ihr Logging sie mitschreibt — in Java ist das meist eine Konfigurationszeile im Log-Muster. Der erste Punkt ist ein echter Klassiker mit teuren Folgen: Die Bon-Nummer wandert in den Span-Namen, und plötzlich hat Ihr Backend Millionen verschiedener Operationsnamen statt einer Handvoll.

6:01 Kennungen gehören in Attribute, nicht in Namen. Der zweite ist der Span Kind, über den wir gerade gesprochen haben. Der dritte ist subtil und verbreitet — ein Fehler wird geloggt, aber der Span-Status bleibt auf Unset; dann findet jede Suche nach fehlerhaften Traces nichts. Und der vierte macht die ganze Korrelation zunichte: strukturierte Logs ohne Trace-ID.

Konventionen als Vertrag

6:22 Jetzt zum Teil, der über die eigene Anwendung hinausgeht. OpenTelemetry liefert Benennungsvereinbarungen mit — für HTTP, Datenbanken, Messaging und vieles mehr. Die Frage ist, wann Sie diese nehmen und wann Sie eigene Namen brauchen. Und die zweite Frage ist fast wichtiger: wie eigene Namen aussehen sollten, damit sie nicht in ein paar Jahren kollidieren.

6:45 Die Semantic Conventions legen gemeinsame Namen, Attribute, Einheiten und Bedeutungen fest — im September 2026 in Version 1.44.0. Die Regeln für die Schreibweise sind schnell erzählt: kleingeschrieben, mit Punkt in Namensräume gegliedert, und innerhalb eines Bestandteils Unterstriche. Das Beispiel http.response.status_code zeigt beides auf einmal: Punkte trennen die Ebenen, der Unterstrich hält zusammen, was inhaltlich ein Begriff ist.

7:14 Diese Regeln wirken pedantisch, bis man das erste Mal versucht, über zwanzig Dienste hinweg zu gruppieren — dann sind sie Gold wert. Vier gute Gründe, keine eigenen Namen zu erfinden, wo es schon welche gibt. Der erste ist unmittelbar praktisch: Fertige Dashboards und Abfragen greifen nur auf konventionsgerechte Attribute.

7:34 Der zweite ist noch wichtiger — die automatische Instrumentierung, die wir gleich in Modul fünf einsetzen, erzeugt genau diese Namen. Wer eigene erfindet, bricht die Reihe und muss alles doppelt pflegen. Der dritte betrifft den Backendwechsel, über den wir in Modul drei gesprochen haben. Und der vierte ist eine Zusage: Stabile Attribute ändern sich nicht mehr.

7:57 Für alles, was die Konventionen nicht kennen, gibt es zwei saubere Wege. Gilt ein Attribut firmenweit, nehmen Sie Ihre Domain rückwärts — das ist dasselbe Prinzip wie bei Java-Paketnamen und aus demselben Grund: Es kann nicht kollidieren. Betrifft es nur eine Anwendung, genügt der Anwendungsname als Präfix. Die dritte Zeile ist die eigentliche Warnung: Verwenden Sie niemals einen bestehenden OpenTelemetry-Namensraum als Präfix.

8:22 Heute ist http.filiale frei — morgen definiert die Spezifikation dort etwas, und dann haben Sie einen Konflikt, den niemand mehr sauber auflösen kann. Sie entwerfen jetzt ein Benennungsschema: Standardattribute übernehmen, eigene sauber abgrenzen. Das Ergebnis ist eine Tabelle mit den Resource-Attributen je Dienst und drei fachlichen Attributen — jeweils mit Namensraum, Typ und Wertebereich.

8:46 Der Hinweis ist ernst gemeint: Prüfen Sie für jedes eigene Attribut zuerst, ob die Konventionen es bereits kennen. Das ist der häufigste vermeidbare Fehler in diesem Feld, weil niemand gern in fremden Spezifikationen sucht. Die zehn Minuten sparen Ihnen später einen Umbau. Der erste Punkt beschreibt, wie es üblicherweise schiefgeht: Jedes Team erfindet eigene Attribute, und danach kann niemand mehr über Dienste hinweg gruppieren.

9:12 Der zweite ist der nachgebaute Standard. Der dritte ist der, den wir in Modul zwölf wieder treffen werden — ein offener Wertebereich sprengt später die Kardinalität; deshalb steht der Wertebereich schon jetzt in der Tabelle. Und der vierte betrifft den Reifegrad: Experimentelle Attribute können sich ändern. Wer sie wie stabile behandelt, hat beim nächsten Update kaputte Dashboards.

Übung

9:34 In der Übung schreiben Sie den Vertrag auf, bevor auch nur eine Zeile Code entsteht. Das ist bewusst so herum: Was hier festgelegt wird, setzen Sie in Modul fünf als Umgebungsvariable und prüfen es in Modul zwölf gegen die Kardinalität. Das ist ungewohnt, weil Benennung sich nicht wie Arbeit anfühlt. Aber jede Stunde, die Sie hier investieren, sparen Sie in Modul zwölf und sechzehn mehrfach wieder ein — dort zahlt sich ein sauberer Vertrag unmittelbar aus.

10:01 Das Ziel ist, Benennung als bindende Vereinbarung zu behandeln und nicht als Nebenprodukt. Konkret: Für alle drei Pfandwerk-Dienste stehen am Ende die Resource-Attribute fest, und drei fachliche Attribute sind gegen die Konventionen geprüft — mit Begründung, warum es dafür keinen Standard gibt. Diese Begründung ist wichtiger, als sie aussieht. Sie zwingt zur Suche, und bei der Suche findet man erfahrungsgemäß mindestens ein Attribut, das es doch schon gibt.

10:28 Die Reihenfolge führt vom Allgemeinen zum Speziellen und endet bei der Kostenfrage. Zuerst die Resource je Dienst, dann die fachlichen Attribute des Rücknahmevorgangs sammeln, dann jedes einzelne gegen die Konventionen prüfen. Für die verbleibenden wählen Sie einen eigenen Namensraum. Und im letzten Schritt notieren Sie den erwarteten Wertebereich — das ist der Schritt, den man gern überspringt und der später am meisten wert ist.

10:51 Denn dieser Wertebereich ist die Grundlage der Kardinalitätsabschätzung in Modul zwölf. Der erste Punkt ist die elegante Form des Weglassens: Wertebereich „beliebig". Das ist keine Angabe, sondern eine verschobene Entscheidung. Der zweite ist die Prüfung, die aus Zeitgründen entfällt — dabei dauert sie Minuten und spart Stunden.

11:11 Der dritte ist organisatorisch: Die Tabelle entsteht, wird aber nicht versioniert, und nach drei Wochen weiß niemand mehr, welche Fassung gilt. Legen Sie sie ins Repository. Und der vierte ist ein Datenschutzthema, das wir in Modul sieben vertiefen: Für die Filiale wird die Klartextadresse gewählt statt einer Kennung. Adressen sind Daten, die man nicht überall haben möchte.