C_12265_Anlage

Telemetriedaten als neues Format zum Bereitstellen und Senden von Daten an die gematik.

Inhaltsverzeichnis

1 Änderungsbeschreibung

Vorabinformation zum Änderungseintrag: Folgende Änderungen sind Bestandteil des Änderungseintrages: C_12265 Perf Telemetriedatenlieferung Die Nummerierung der Kapitel entspricht nicht der Nummerierung aus den referenzierenden Dokumenten, da diese durch die Formatierung automatisch erzeugt wird. Dies wird bei der Einarbeitung der Änderungen entsprechend beachtet. Erläuterung: hier nur normativ notwendige Texte in Begleitdokument der dynamische Teil beide zusammen beschreiben den aktuellen Stand des Prozesses Hinweise zur Lesart: <<Text, der zur Erklärung der Änderung dient - wird nicht mit eingearbeitet/übernommen.>> Text, der neu ist. Text, der entfernt wird. Text, der entfernt wird.

2 Ergänzung eines Datenliefermodells

<< Änderungen in gemSpec_Perf zur Ergänzung eines neuen Datenliefermodells>>

2.1 Änderungen in gemSpec_Perf

2.2 in Kapitel 2.5 Datenliefermodelle

<< Aufnahme von Telemetriedaten als neues Datenliefermodell>>

Auswahl eines oder mehrerer Datenliefermodelle für das Produkt. Mögliche (ab heute zugewiesene) Datenliefermodelle:

• Betriebsdatenlieferung
• Version 1 - wollen wir nicht mehr spezifizieren
• Version 2 (BDEv2)
• Selbstauskunft
• Version 1 - wollen wir nicht mehr spezifizieren
• Version 2
• Bestandsdaten
• Konnektordaten - muss ordentlich überarbeitet werden, bevor es genutzt werden kann
• Ereignisdaten - für den dezentralen Bereich gedacht
• Telemetriedaten
• Ad-hoc-Reports - werden immer zugeordnet (da verbandelt mit gemRL_Betr_TI)

<..>

<< Zuordnung des neuen Datenliefermodells zu den TI2.0 Diensten>>

PDT-ID	Name des Produkttyps	Aktuelle Datenliefermodelle
...
PDT71	Proof of Patient Presence Service	BDEv2 Telemetriedaten, Selbstauskunft v2
...
PDT74	Digitale Patientenrechnung Fachdienst	BDEv2 Telemetriedaten, Selbstauskunft v2
...
PDT79	VSDM 2 Fachdienst	BDEv2 Telemetriedaten, Selbstauskunft v2
...
PDT82	ZETA - PIP und PAP Service	Telemetriedaten

Tabelle 1 Tab_gemSpec_Perf_Zuordnung_Datenliefermodelle

Entfernen der Zuordnung der AFO für TI 2.0 Dienste für die Datenaufbewahrung, da der Anbieter nun keine Datenlieferungen mehr direkt an die gematik sendet, sondern diese dem ZETA-Guard bereitstellt. Der Anbieter ist auch mit Wegfall dieser Anforderungen weiterhin verpflichtet, Daten an den ZETA-Guard zum Zwecke der vollständigen Lieferung (z.B. Nachlieferung) zwischenzuspeichern.

2.2.1 Unterkapitel 2.5.1 Betriebsdatenlieferung

Entfernen der Zuordnung von TI2.0 Dienst-Anbieter bzw. Produkttypen [Anb_]PoPP-Service, [Anb_]VSDM_2_FD, [Anb_]DiPag_FD, ZT_PIP_PAP aus den folgenden Anforderungen:

Afo-ID	Titel
A_22002	Performance - Betriebsdatenlieferung v2 - Übermittlung
A_22047	Performance - Betriebsdatenlieferung v2 - Änderung der Konfiguration der Lieferintervalle
A_22996	Performance - Betriebsdatenlieferung v2 - Zeitpunkte der Übermittlungen
A_22620	Performance - Betriebsdatenlieferung v2 - Umsetzungszeit für Änderung der Lieferintervalle
A_22500-01	Performance - Betriebsdatenlieferung v2 - Status-Block
A_22003-01	Performance - Betriebsdatenlieferung v2 - Nachlieferung auf Anforderung
A_22513-02	Performance - Betriebsdatenlieferung v2 - Message-Block im Fehlerfall
A_21982-01	Performance - Betriebsdatenlieferung v2 - Message-Block
A_21980-01	Performance - Betriebsdatenlieferung v2 - Leerlieferung
A_22004	Performance - Betriebsdatenlieferung v2 - Korrektheit
A_21976	Performance - Betriebsdatenlieferung v2 - Konfigurierbarkeit der Lieferintervalle
A_22005	Performance - Betriebsdatenlieferung v2 - Frist für Nachlieferung
A_21981-02	Performance - Betriebsdatenlieferung v2 - Format
A_21975-01	Performance - Betriebsdatenlieferung v2 - Default-Wert des Lieferintervalls
A_22001-02	Performance - Betriebsdatenlieferung v2 - Dateiname der Lieferung
A_21979	Performance - Betriebsdatenlieferung v2 - Bezug der Lieferverpflichtung
A_22057	Performance - Betriebsdatenlieferung - Verpflichtung des Anbieters
A_22482-01	Performance - Betriebsdatenlieferung - Erfassung von Betriebsdaten

Tabelle 2 : Zuordnungsentfernung der TI2.0 Dienste zu BDE

2.2.2 Unterkapitel 2.5.3 Selbstauskunft

Entfernen der Zuordnung von TI2.0 Dienst-Anbieter bzw. Produkttypen [Anb_]PoPP-Service, [Anb_]VSDM_2_FD, [Anb_]DiPag_FD, ZT_PIP_PAP aus den folgenden Anforderungen:

Afo-ID	Titel
A_26173	Performance - Selbstauskunft v1 - Format und Übermittlung
A_26179	Performance - Selbstauskunft v1 - Dateiname der Lieferung
A_22429	Performance - Selbstauskunft v1 - Inhalt
A_26181	Performance - Selbstauskunft v2 - Format und Übermittlung
A_26180	Performance - Selbstauskunft v2 - Grundgerüst
A_27271	Performance - Selbstauskunft v2 - Schemaversion 1

Tabelle 3 :: Zuordnungsentfernung der TI2.0 Dienste zur Selbstauskunft

2.2.3 Unterkapitel 2.5.x Telemetriedaten

<< neues Unterkapitel im Kapitel 2.5 Datenliefermodelle>>

Dienste der TI2.0 Architektur werden Betriebsdaten, Selbstauskunft und Bestandsdaten in einem neuen Datenliefermodell übermitteln.  Unter Verwendung des OpenTelemetry-Frameworks werden Telemetrie-Daten über verteilte Systeme eingesammelt und für die Weitergabe an die gematik aufbereitet. Aus den Telemetriedaten können Informationen zur Performance, Last und Fehlersituationen sowie Daten über den Status und Versionsständen von Nutzern und Clients abgeleitet werden.

Die gesammelten Telemetriedaten werden auf Basis des OpenTelemetry Protokolls (OTLP) über gRPC gesendet und von der gematik empfangen. Die gematik prüft den Sender auf ein gültiges Client-Zertifikat und erlaubt nur validierte Zugriffe über mTLS.

Generell werden folgende drei Typen von Telemetriedaten unterschieden:

• Traces
• Logs
• Metriken

Die Tabelle 4- Zuordnung der Telemetriedatentypen zu Datenlieferungen beschreibt die Zuordnung der Telemetriedatentypen zu den gematik bekannten Datenlieferungen.

Telemetriedatentyp	Zugeordnete Datenlieferung	Beschreibung
Trace	Betriebsdaten	Informationen über den Ablauf und die Dauer von verteilten Anfragen und Transaktionen über die einzelnen beteiligten Komponenten hinweg.
Logs	Selbstauskunft	Versions- und Statusinformationen werden zeitlich zugeordnet als Logs dokumentiert und können darüber ausgewertet werden
Metriken	Bestandsdaten	Numerische Werte, die den Zustand oder die Leistung über die Zeit messen, z.B. Anzahl erfolgreicher Anfragen pro Minute

Tabelle 4 : Zuordnung der Telemetriedatentypen zu Datenlieferungen

Eine zentrale Rolle in der TI2.0 Architektur nehmen die Komponenten von ZETA ein. Der ZETA Guards wird eine zwingende Komponente von TI2.0 Diensten und stellt einen Telemetrie-Daten Service zur Verfügung. Dieser Service übernimmt die Kommunikation mit der gematik und führt die Informationen des dahinterliegenden Ressource Servers mit den eigenen Aufrufen zusammen. Die dazugehörigen Spezifikationen sind in dem Dokument [gemSpec_ZETA] näher skizziert und Anforderungen zum Aufbau des Telemetrie-Daten-Service innerhalb des ZETA Guard sind ebenfalls in dem Dokument verortet.

der ZETA PIP / PAP Service ist ebenfalls Bestandteil der TI2.0 Architektur und wird Telemetriedaten entsprechend dem spezifizierten Aufbau liefern.

2.2.3.1 Traces

Ein gesendeter Trace enthält 1-n Spans, die grundlegende Einheit von einzelnen Operationen in einem verteilten System. Die Gesamtheit der Spans mit gleicher Trace ID ermöglicht eine Nachvollziehbarkeit der gesamten Kette eines Aufrufes. 

Hier ein Beispiel eines Traces, der aus zwei einzelnen Operationen zusammengesetzt wird.

{
  "trace_id": "abcd1234efgh5678ijkl9012mnop3456", 
  "spans": [
    {
      "span_id": "1111222233334444",
      "name": "HTTP GET /api/user",
      "start_time_unix_nano": "2025-04-22T12:00:00.000Z",
      "end_time_unix_nano": "2025-04-22T12:00:01.000Z",
      "attributes": [
        {"http_fqdn": "vsdm2.aok.net"},
        {"http_route": "/ressource/path/1"},
        {"http_status": 200}
      ],
      "parent_id": null  // Root-Span hat keinen Parent
    },
    {
      "span_id": "5555666677778888",
      "name": "rs-vsdm_2",
      "start_time_unix_nano": "2025-04-22T12:00:00.200Z",
      "end_time_unix_nano": "2025-04-22T12:00:00.700Z",
      "attributes": [
        {"rs_ci": "CI111243243"},
        {"rs_message_key1": "text"},
        {"rs_message_key2": 500}
      ],
      "parent_id": "1111222233334444" // Parent-Span-ID des Root-Spans
    }
  ]
}

Fehlt in der Kette der Operationen ein Span eines Ressource Servers kann daraus abgeleitet werden, dass der Ressource Server ausgefallen ist.  Ein weiterer Überwachungsmechanismus für den Ausfall eines Ressource Servers ist die Kontrolle einzelner Kubernetes Pods. Die Protokollierung von automatischen Neustarts kann hierzu ausgewertet werden.

Die folgende Tabelle gibt Aufschluss über die möglichen Trace-Parameter.

Attributname	zugehörige Operation	Beschreibung
trace_id	alle	Eindeutige ID eines Traces und Kennzeichnung zueinander gehörender Operationen. Das Feld darf nicht leer sein.
span_id	alle	Eindeutige ID einer einzelnen Operation innerhalb eines Traces. Das Feld darf nicht leer sein.
parent_id	alle	Eindeutige ID zur Identifizierung von Hierarchien innerhalb der Operationen eines Traces.
name	alle	Name der Operation bzw. Systemname. Das Feld darf nicht leer sein.
start_time_unix_nano	alle	Startzeitpunkt der Operation, Nutzung zur Berechnung der Duration aus der Differenz zum Endzeitpunkt. Das Feld darf nicht leer sein.
end_time_unix_nano	alle	Endzeitpunkt der Operation, Nutzung zur Berechnung der Duration aus der Differenz zum Startzeitpunkt. Das Feld darf nicht leer sein.
pod_name	alle	Name des Pods/der Instanz
attributes:http_fqdn	alle	Vollständiger FQDN der ausgeführten Operation
attributes:http_route	alle	HTTP Route der ausgeführten Operation
attributes:http_status	alle	3-stelliger HTTP Statuscode gemäß [RFC9110]
attributes:rs_ci	Ressource Server des TI 2.0 Dienst	Dies ist die logische Produktinstanz und entspricht der CI-ID aus dem ITSM. Das Feld darf beim Span des Ressource Servers nicht leer sein. Format: String mit 10 Zeichen
attributes:rs_instance	Ressource Server des TI 2.0 Dienst	Dies ist eine zusätzliche fachliche Instanz des Resource Servers. Wenn notwendig vom Ressource Server befüllt.
attributes:rs_status	Ressource Server des TI 2.0 Dienst	Ein max. 5-stelliger Statuscode des Ressource Servers gemäß [A_27722]. Das Feld darf nicht leer sein.
attributes:rs_message_key1	Ressource Server des TI 2.0 Dienst	JSON-formatierter String (UTF-8, ohne Steuerzeichen oder Binärdaten); evtl. Produktspezifische Zusatzinformationen
attributes:rs_message_key2	Ressource Server des TI 2.0 Dienst	JSON-formatierter String (UTF-8, ohne Steuerzeichen oder Binärdaten); evtl. Produktspezifische Zusatzinformationen

Tabelle 5 Tab_gemSpec_Perf_Trace_Parameter_Telemetriedatenlieferung

2.2.3.2 Logs

Zusätzlich zur Nachvollziehbarkeit von verteilten Transaktionen in einer Anwendung mittels Traces kann OpenTelemetry Logs erfassen. Die Telemetriedatenlieferung stellt einen Custom Collector für die Selbstauskunft zur Verfügung. Der ZETA Guard greift diesen Collector auf und lässt ihn durch den Ressource Server befüllen, ebenso liefert der ZETA PIP PAP Server die Informationen auf direktem Weg.

Das OpenTelemetry Log "product_info" wird in der folgenden Tabelle beschrieben.

Parameter	Beschreibung
product_name	Name des Produkts
product_version	Aktuelle Produktversion
producttype_version	Aktuelle Produkttypversion
configuration_version	Aktuelle Konfigurationsversion
pod_name	Name des Pods/der Instanz
timestamp	Zeitpunkt der letzten Änderung

Tabelle 6 : Tab_gemSpec_Perf_Telemetriedaten_product_info

2.2.3.3 Metriken

In der Zukunft können OpenTelemetry Metriken hinzukommen, um Bestandsdaten von TI2.0 Diensten aufzunehmen, sobald Anwendungsfälle hierfür definiert werden.

2.2.3.4 Neue Anforderungen Telemetriedatenlieferungen

Hinweis: Es sind vom Anbieter, anstatt der Status Code Klassen (first digit of status code), die konkreten 3-stelligen HTTP-Statuscodes gemäß [RFC9110] zu verwenden.

2.2.4 Anmerkung zu Kapitel 3. Produkttypspezifische Vorgaben

In dem Kapitel 3 "Produkttypspezifische Vorgaben" gibt es Unterkapitel zu den einzelnen Diensten und deren spezifische Vorgaben. Die bereits erwähnten TI2.0 Dienste müssen hier genauer betrachtet werden und die Anforderungen mit Bezug zu den Betriebsdaten, Selbstauskunft oder Bestandsdaten müssen angepasst werden. Die technischen Vorgaben sind mit den neuen, hier in der Anlage aufgeführten Anforderungen bereits adressiert, aber es gibt noch weiteren Anforderungsbedarf im Wortlaut für das Senden produktspezifischer Informationen.

Betroffen sind die Unterkapitel

• Betriebsdatenlieferung v2 - Spezifika VSDM 2
• 3.28.2 Betriebsdatenlieferung v2 - Spezifika Digitale Patientenrechnung
  
• 3.28.3 Bestandsdatenlieferung - Spezifika Digitale Patientenrechnung
  

3 Ergänzungen von Anforderungen in der ZETA Guard Spezifikation

<< Änderungen in gemSpec_ZETA zur Ergänzung von Anforderungen für den Telemetrie-Daten-Service >>

3.1 Änderungen in gemSpec_ZETA

3.2 in Kapitel 5.7 Telemetrie-Daten-Service

<< neue Anforderungen >> 

Hinweis: Es sind vom Anbieter, anstatt der Status Code Klassen (first digit of status code), die konkreten 3-stelligen HTTP-Statuscodes gemäß [RFC9110] zu verwenden.