Speicherschema für Tracedaten

In diesem Dokument wird das Format beschrieben, in dem Trace-Spans gespeichert werden. Das Format der Daten entspricht im Allgemeinen den Proto-Dateien, die vom OpenTelemetry OTLP-Protokoll definiert werden. Felder werden jedoch möglicherweise vor dem Speichern von einem OpenTelemetry-spezifischen Datentyp in einen JSON-Datentyp konvertiert.

Die Telemetry API verwendet das OpenTelemetry OTLP-Protokoll. Dieses Protokoll basiert auf den Dateien trace_service.proto und trace.proto. Informationen zu Feldlimits finden Sie unter Telemetry API-Limits.

Die Cloud Trace API verwendet nicht das OpenTelemetry OTLP-Protokoll und definiert ein proprietäres Datenformat. Trace-Daten, die über diese API an Ihr Google Cloud -Projekt gesendet werden, werden in das in diesem Dokument beschriebene Format konvertiert. Es gelten jedoch die Limits für die Cloud Trace API.

Speicherformat für Spans

Feld	Beschreibung
trace_id	string Global eindeutige Kennung für den Trace. Diese Kennung ist ein numerischer 128-Bit-Wert, der als 16-Byte-Hexadezimalstring formatiert ist. Beispiel: 382d4f4c6b7bb2f4a972559d9085001d. Weitere Informationen zu dieser Kennung finden Sie unter W3C trace-id. Ein numerischer Wert von null ist ungültig. Die trace_id wird von Visualisierungs- und Analysetools verwendet, um die Spannen zu identifizieren, die einem Trace zugeordnet sind. Aus diesem Grund muss jeder End-to-End-Vorgang eine eindeutige Kennung haben. Verwenden Sie keine Trace-ID wieder.
span_id	string Erforderlich. Kennung für den Span. Muss innerhalb eines Traces eindeutig sein. Diese Kennung ist ein 64-Bit-Zahlenwert, der als 8-Byte-Hexadezimalstring formatiert ist. Beispiel: 9046a5b9f7c12500. Ein numerischer Wert von null ist ungültig.
trace_state	string Dieses Feld entspricht dem tracestate-Header, wie im W3C Trace Context definiert. Dieser Header enthält Konfigurationsinformationen, die in Anfragen enthalten sind, wenn Anwendungen für die Erfassung von Trace-Daten instrumentiert werden. Eine Anwendung kann beispielsweise die Einstellungen für Wahrscheinlichkeitsstichproben festlegen oder anbieterspezifische Inhalte enthalten. OpenTelemetry-Bibliotheken zeichnen den Wert des tracestate-Headers automatisch auf, wenn sie Spans generieren.
parent_span_id	string Optional. Gibt den Vorgang an, der diesen Bereich aufgerufen hat. Für den Stamm-Span ist die ID des übergeordneten Spans auf „null“ gesetzt. Die über- und untergeordnete Beziehung zwischen Spannen wird von Visualisierungstools verwendet, um die Baumstruktur zu erstellen.
name	string Erforderlich. Der Name des Vorgangs, der ausgeführt wurde. Der Name kann ein Methodenname oder ein anderer Name für die Website pro Aufruf sein. Wenn Sie für dieselbe ausführbare Datei und denselben Endpunkt einen einheitlichen Namen verwenden, lassen sich Spans in verschiedenen Traces leichter in Beziehung setzen. Best Practices finden Sie unter Spans benennen. Der Spannenname wird bereinigt und in der Google Cloud Console angezeigt.
kind	integer Gibt an, wo im System der Vorgang stattgefunden hat. Der Wert entspricht der Aufzählung OpenTelemetry: Span Kind: Wert OpenTelemetry-Aufzählung 0 SPAN_KIND_UNSPECIFIED 1 SPAN_KIND_INTERNAL 2 SPAN_KIND_SERVER 3 SPAN_KIND_CLIENT 4 SPAN_KIND_PRODUCER 5 SPAN_KIND_CONSUMER
start_time	Timestamp Erforderlich. Startzeit des Zeitraums, auf die nächste Nanosekunde gerundet.
start_time_unix_nano	integer Die Startzeit in Nanosekunden gemäß der UNIX-Epoche.
end_time	Timestamp Erforderlich. Ende des Zeitraums, auf die nächste Nanosekunde gerundet.
end_time_unix_nano	integer Die Endzeit in Nanosekunden gemäß der UNIX-Epoche.
receive_time	Timestamp Erforderlich. Empfangszeit des Zeitraums, auf die nächste Nanosekunde genau.
receive_time_unix_nano	integer Die Endzeit in Nanosekunden gemäß der UNIX-Epoche.
duration_unix_nano	integer Die Dauer in Nanosekunden.
attributes	JSON type Jedes Attribut ist ein Schlüssel/Wert-Paar. Die verfügbaren Attribute hängen von Ihren Tracedaten ab. Die Struktur der Attribute entspricht dem OpenTelemetry-Standard. Weitere Informationen zu OpenTelemetry-Attributen OpenTelemetry gibt semantische Konventionen für Attribute an. Weitere Informationen zu diesen Konventionen finden Sie unter Semantische Konventionen für Traces. Hier einige Beispiele für Attribute: "yourcompany.your.own.key": "your own value" "network.protocol.name": "http" "network.protocol.version": "1.1" "http.response.status_code": "200" "network.peer.address": "REDACTED"
dropped_attributes_count	integer Die Anzahl der verworfenen Attribute. Attribute können verworfen werden, weil ihre Schlüssel zu lang sind oder weil es zu viele Attribute gibt. Wenn dieser Wert null ist, wurden keine Attribute verworfen. Dieser Wert kann durch die clientseitige Instrumentierung oder durch eine Anwendung festgelegt werden. Der Wert kann vom Server erhöht werden.
events	record mit wiederkehrenden Feldern Ein Ereignis, das zu einem bestimmten Zeitpunkt stattfindet. Jedes Ereignis enthält die folgenden Felder. Feld Beschreibung time Timestamp time_unix_nano integer name string Erforderlich. Name des Ereignisses. attributes JSON type Jedes Attribut ist ein Schlüssel/Wert-Paar. Die verfügbaren Attribute hängen von Ihren Tracedaten ab. Die Struktur der Attribute entspricht dem OpenTelemetry-Standard. Weitere Informationen zu OpenTelemetry-Attributen dropped_attributes_count integer Die Anzahl der verworfenen Attribute. Attribute können verworfen werden, weil ihre Schlüssel zu lang sind oder weil es zu viele Attribute gibt. Wenn dieser Wert null ist, wurden keine Attribute verworfen. Dieser Wert kann durch die clientseitige Instrumentierung oder durch eine Anwendung festgelegt werden. Der Wert kann vom Server erhöht werden.
dropped_events_count	integer Die Anzahl der verworfenen Ereignisse. Ereignisse können verworfen werden, weil es zu viele Ereignisse gibt. Wenn dieser Wert null ist, wurden keine Ereignisse verworfen.
links	record mit wiederkehrenden Feldern Mit dem Bereich verknüpfte Links. Links sind Verweise von diesem Span auf einen anderen Span im selben oder in einem anderen Trace. Mithilfe von Links können Spans aus einem Trace mit Spans in einem anderen Trace in Beziehung gesetzt werden. Angenommen, ein Vorgang führt zu einem asynchronen Vorgang. In diesem Szenario gibt es zwei Traces: einen für den ursprünglichen Vorgang und einen für den asynchronen Vorgang. Sie können Links verwenden, um die Spans in diesen Traces in Beziehung zu setzen. Jeder Link enthält die folgenden Felder. Feld Beschreibung trace_id string Erforderlich. span_id string Erforderlich. trace_state string attributes JSON type Jedes Attribut ist ein Schlüssel/Wert-Paar. Die verfügbaren Attribute hängen von Ihren Tracedaten ab. Die Struktur der Attribute entspricht dem OpenTelemetry-Standard. Weitere Informationen zu OpenTelemetry-Attributen dropped_attributes_count integer Die Anzahl der verworfenen Attribute. Attribute können verworfen werden, weil ihre Schlüssel zu lang sind oder weil es zu viele Attribute gibt. Wenn dieser Wert null ist, wurden keine Attribute verworfen. Dieser Wert kann durch die clientseitige Instrumentierung oder durch eine Anwendung festgelegt werden. Der Wert kann vom Server erhöht werden.
dropped_links_count	integer Die Anzahl der verworfenen Links. Links können verworfen werden, weil es zu viele Links gibt. Wenn dieser Wert null ist, wurden keine Links verworfen.
status	record ohne wiederkehrende Felder In diesem Feld wird der Abschlussstatus für einen Zeitraum aufgezeichnet. Der Wert des Unterfelds code entspricht der Aufzählung OpenTelemetry: Span Status: Wert OpenTelemetry Aufzählung Beschreibung 0 UNSET Vorgang wurde abgeschlossen. 1 OK Der Vorgang wurde von einem Menschen als fehlerfrei markiert. 2 ERROR Der Vorgang wurde mit einem Fehler abgeschlossen. Wenn der Status für einen Client-Span beispielsweise 400 (BAD REQUEST) ist, wird dieses Feld auf ERROR festgelegt. Das Unterfeld message, das als String formatiert ist, enthält Fehlerinformationen.
resource	record ohne wiederkehrende Felder In diesem Feld wird die Infrastruktur oder das Hostingsystem angegeben, aus dem die Telemetriedaten erfasst wurden oder auf die sich die Telemetriedaten beziehen. Betrachten Sie beispielsweise eine Anwendung, die in Google Kubernetes Engine ausgeführt wird. Attribute für diese Ressource können den Prozessnamen und den Namespace umfassen. Dieses Feld enthält die folgenden Unterfelder: Feld Beschreibung attributes JSON type Jedes Attribut ist ein Schlüssel/Wert-Paar. Die verfügbaren Attribute hängen von Ihren Tracedaten ab. Die Struktur der Attribute entspricht dem OpenTelemetry-Standard. Weitere Informationen zu OpenTelemetry-Attributen Hier einige Beispiele für Ressourcenattribute: cloud.account.id: "my-project" cloud.platform: "gcp_kubernetes_engine" cloud.provider: "gcp" cloud.region: "us-central1" gcp.project_id: "my-project" host.id: "REDACTED" host.name: "gke-otel-demo" k8s.cluster.name: "otel-demo" k8s.deployment.name: "otel-demo-frontendproxy" dropped_attributes_count integer Die Anzahl der verworfenen Attribute. Attribute können verworfen werden, weil ihre Schlüssel zu lang sind oder weil es zu viele Attribute gibt. Wenn dieser Wert null ist, wurden keine Attribute verworfen. Dieser Wert kann durch die clientseitige Instrumentierung oder durch eine Anwendung festgelegt werden. Der Wert kann vom Server erhöht werden. Weitere Informationen finden Sie unter OpenTelemetry: Resources.
instrumentation_scope	record ohne wiederkehrende Felder In diesem Feld wird die Bibliotheks- oder Anwendungskomponente für die angegebene resource angegeben, die Telemetriedaten erfasst. Der Bereich stellt einen bestimmten Vorgang dar, der diesen Bereich durchläuft, d. h. die Bibliothek oder Komponente innerhalb der Ressource. Angenommen, die Anwendung „checkout-service“ wird in Cloud Run bereitgestellt. Das bedeutet, dass die resource eine bestimmte Cloud Run-Instanz ist. Angenommen, die Ressource hat mehrere Instrumentierungsbereiche, z. B. „request-authorization-library“ und „payment-processor-library“. Ein Client-Span wie „WritePaymentInfoToStripe“ kann ein Span sein, der von der „payment-processor-library“ gemeldet wird, die sich im Cloud Run-Dienst „checkout-service“ befindet. Dieses Feld enthält die folgenden Unterfelder: Feld Beschreibung name string version string attributes JSON type Jedes Attribut ist ein Schlüssel/Wert-Paar. Die verfügbaren Attribute hängen von Ihren Tracedaten ab. Die Struktur der Attribute entspricht dem OpenTelemetry-Standard. Weitere Informationen zu OpenTelemetry-Attributen dropped_attributes_count integer Die Anzahl der verworfenen Attribute. Attribute können verworfen werden, weil ihre Schlüssel zu lang sind oder weil es zu viele Attribute gibt. Wenn dieser Wert null ist, wurden keine Attribute verworfen. Dieser Wert kann durch die clientseitige Instrumentierung oder durch eine Anwendung festgelegt werden. Der Wert kann vom Server erhöht werden. Weitere Informationen finden Sie unter OpenTelemetry: Instrumentation scope.
resource_schema_link	string Diese Felder müssen eine URL sein, die als String formatiert ist. Diese Felder enthalten eine URL, die eine Schemadatei für eine Ressource zurückgibt. Das Format der Schemadatei und der Daten wird von OpenTelemetry definiert. Weitere Informationen finden Sie unter OpenTelemetry: Schemas. Diese Felder können nur bei Verwendung der Telemetry API festgelegt werden. Bei dieser API wird nicht geprüft, ob die Daten dem deklarierten Schema entsprechen.
scope_schema_link	string Diese Felder müssen eine URL sein, die als String formatiert ist. Diese Felder enthalten eine URL, die eine Schemadatei für einen Bereich zurückgibt. Das Format der Schemadatei und der Daten wird von OpenTelemetry definiert. Weitere Informationen finden Sie unter OpenTelemetry: Schemas. Diese Felder können nur bei Verwendung der Telemetry API festgelegt werden. Bei dieser API wird nicht geprüft, ob die Daten dem deklarierten Schema entsprechen.
apphub	record ohne wiederkehrende Felder Anwendungsspezifische Labels sind verfügbar, wenn Trace-Spans von App Hub-Anwendungen generiert werden, wenn diese Anwendungen auf unterstützter Infrastruktur ausgeführt werden oder instrumentiert wurden. Weitere Informationen zum Anwendungsmonitoring und dazu, wann diese Labels verfügbar sind, finden Sie in der Übersicht zum Anwendungsmonitoring. Dieses Feld enthält die Unterfelder application, service und workload. Unterfeld der Anwendung Beschreibung container string location string id string Unterfeld „Dienst/Arbeitslast“ Beschreibung id string environment_type string criticality_type string