Schema di archiviazione per i dati di traccia

Questo documento descrive il formato in cui vengono archiviati gli intervalli di traccia. Il formato dei dati è generalmente coerente con i file proto definiti dal protocollo OpenTelemetry OTLP. Tuttavia, i campi potrebbero essere convertiti da un tipo di dati specifico di OpenTelemetry a un tipo di dati JSON prima dell'archiviazione.

L'API Telemetry utilizza il protocollo OpenTelemetry OTLP. Questo protocollo si basa sui file trace_service.proto e trace.proto. Per informazioni sui limiti dei campi, consulta Limiti dell'API Telemetry.

L'API Cloud Trace non utilizza il protocollo OTLP di OpenTelemetry e definisce un formato di dati proprietario. I dati di Trace inviati al tuo progetto Google Cloud tramite questa API vengono convertiti nel formato descritto in questo documento. Tuttavia, si applicano i limiti per l'Cloud Trace API.

Formato di archiviazione degli span

Campo	Descrizione
trace_id	string Identificatore univoco globale per la traccia. Questo identificatore è un valore numerico a 128 bit formattato come stringa esadecimale a 16 byte. Ad esempio, 382d4f4c6b7bb2f4a972559d9085001d. Per saperne di più su questo identificatore, consulta trace-id W3C. Un valore numerico pari a zero non è valido. trace_id viene utilizzato dagli strumenti di visualizzazione e analisi per identificare gli intervalli associati a una traccia. Per questo motivo, ogni operazione end-to-end deve avere un identificatore univoco. Non riutilizzare un identificatore di traccia.
span_id	string Obbligatorio. Identificatore per lo span. Deve essere univoco all'interno di una traccia. Questo identificatore è un valore numerico a 64 bit formattato come stringa esadecimale a 8 byte. Ad esempio, 9046a5b9f7c12500. Un valore numerico pari a zero non è valido.
trace_state	string Questo campo corrisponde all'intestazione tracestate, come definito da W3C Trace Context. Questa intestazione contiene informazioni di configurazione incluse nelle richieste quando le applicazioni vengono strumentate per raccogliere dati di traccia. Ad esempio, un'applicazione può specificare le impostazioni di campionamento probabilistico oppure può includere contenuti specifici del fornitore. Le librerie OpenTelemetry registrano automaticamente il valore dell'intestazione tracestate quando generano gli span.
parent_span_id	string Facoltativo. Identifica l'operazione che ha richiamato questo span. L'intervallo "root" ha l'ID intervallo padre impostato su null. La relazione padre-figlio tra gli intervalli viene utilizzata dagli strumenti di visualizzazione per costruire la struttura ad albero.
name	string Obbligatorio. Il nome dell'operazione eseguita. Il nome può essere il nome di un metodo o un altro nome del sito per chiamata. Per lo stesso eseguibile e lo stesso endpoint, l'utilizzo di un nome coerente facilita la correlazione degli span cross-trace. Per le best practice, vedi Come assegnare un nome agli intervalli. Il nome dello span viene sanificato e visualizzato nella Google Cloud console.
kind	integer Specifica in quale parte del sistema è stata eseguita l'operazione. Il valore corrisponde all'enumerazione OpenTelemetry: Span Kind: Valore Enumerazione OpenTelemetry 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 Obbligatorio. Ora di inizio dell'intervallo, al nanosecondo più vicino.
start_time_unix_nano	integer L'ora di inizio in nanosecondi, secondo l'epoca UNIX.
end_time	Timestamp Obbligatorio. Ora di fine dell'intervallo, al nanosecondo più vicino.
end_time_unix_nano	integer L'ora di fine in nanosecondi, secondo l'epoca di UNIX.
receive_time	Timestamp Obbligatorio. Ricevi l'ora dello span, al nanosecondo più vicino.
receive_time_unix_nano	integer L'ora di fine in nanosecondi, secondo l'epoca di UNIX.
duration_unix_nano	integer La durata in nanosecondi.
attributes	JSON type Ogni attributo è una coppia chiave-valore. Gli attributi disponibili dipendono dai dati di traccia. La struttura degli attributi segue lo standard OpenTelemetry. Per saperne di più, consulta OpenTelemetry: Attributes. OpenTelemetry specifica le convenzioni semantiche per gli attributi. Per scoprire di più su queste convenzioni, consulta Convenzioni semantiche di traccia. Di seguito sono riportati alcuni esempi di attributi: "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 Il numero di attributi eliminati. Gli attributi possono essere eliminati perché le relative chiavi sono troppo lunghe o perché sono presenti troppi attributi. Quando questo valore è zero, non sono stati eliminati attributi. Questo valore potrebbe essere impostato dalla strumentazione lato client o da un'applicazione. Il valore può essere incrementato dal server.
events	record con campi ripetuti Un evento in un momento specifico. Ogni evento contiene i seguenti campi. Campo Descrizione time Timestamp time_unix_nano integer name string Obbligatorio. Il nome dell'evento. attributes JSON type Ogni attributo è una coppia chiave-valore. Gli attributi disponibili dipendono dai dati di traccia. La struttura degli attributi segue lo standard OpenTelemetry. Per saperne di più, consulta OpenTelemetry: Attributes. dropped_attributes_count integer Il numero di attributi eliminati. Gli attributi possono essere eliminati perché le relative chiavi sono troppo lunghe o perché sono presenti troppi attributi. Quando questo valore è zero, non sono stati eliminati attributi. Questo valore potrebbe essere impostato dalla strumentazione lato client o da un'applicazione. Il valore può essere incrementato dal server.
dropped_events_count	integer Il numero di eventi eliminati. Gli eventi possono essere eliminati perché sono troppi. Quando questo valore è zero, non sono stati eliminati eventi.
links	record con campi ripetuti I link associati all'intervallo. I link sono riferimenti di questo span a un altro span nella stessa traccia o in una traccia diversa. I link forniscono un meccanismo per correlare gli span di una traccia con gli span di un'altra traccia. Ad esempio, supponiamo che un'operazione provochi un'operazione asincrona. In questo scenario, ci sono due tracce, una per l'operazione originale e una per l'operazione asincrona. Puoi utilizzare i link per correlare gli intervalli in queste tracce. Ogni link contiene i seguenti campi. Campo Descrizione trace_id string Obbligatorio. span_id string Obbligatorio. trace_state string attributes JSON type Ogni attributo è una coppia chiave-valore. Gli attributi disponibili dipendono dai dati di traccia. La struttura degli attributi segue lo standard OpenTelemetry. Per saperne di più, consulta OpenTelemetry: Attributes. dropped_attributes_count integer Il numero di attributi eliminati. Gli attributi possono essere eliminati perché le relative chiavi sono troppo lunghe o perché sono presenti troppi attributi. Quando questo valore è zero, non sono stati eliminati attributi. Questo valore potrebbe essere impostato dalla strumentazione lato client o da un'applicazione. Il valore può essere incrementato dal server.
dropped_links_count	integer Il numero di link eliminati. I link possono essere eliminati perché sono troppi. Quando questo valore è zero, non sono stati eliminati link.
status	record senza campi ripetuti Questo campo registra lo stato di completamento di un intervallo. Il valore del sottocampo code corrisponde all'enumerazione OpenTelemetry: Span Status: Valore Enumerazione OpenTelemetry Descrizione 0 UNSET Operazione completata correttamente. 1 OK L'operazione è stata contrassegnata come priva di errori da un operatore. 2 ERROR L'operazione è stata completata con un errore. Ad esempio, se lo stato è 400 (BAD REQUEST) in uno span client, questo campo è impostato su ERROR. Il sottocampo message, formattato come stringa, contiene informazioni sull'errore.
resource	record senza campi ripetuti Questo campo identifica l'infrastruttura o il sistema di hosting da cui sono stati raccolti i dati di telemetria o a cui si riferiscono. Ad esempio, considera un'applicazione in esecuzione su Google Kubernetes Engine. Gli attributi per questa risorsa potrebbero includere il nome e lo spazio dei nomi del processo. Questo campo contiene i seguenti campi secondari: Campo Descrizione attributes JSON type Ogni attributo è una coppia chiave-valore. Gli attributi disponibili dipendono dai dati di traccia. La struttura degli attributi segue lo standard OpenTelemetry. Per saperne di più, consulta OpenTelemetry: Attributes. Di seguito sono riportati alcuni esempi di attributi delle risorse: 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 Il numero di attributi eliminati. Gli attributi possono essere eliminati perché le relative chiavi sono troppo lunghe o perché sono presenti troppi attributi. Quando questo valore è zero, non sono stati eliminati attributi. Questo valore potrebbe essere impostato dalla strumentazione lato client o da un'applicazione. Il valore può essere incrementato dal server. Per scoprire di più, consulta OpenTelemetry: risorse.
instrumentation_scope	record senza campi ripetuti Questo campo identifica la libreria o il componente dell'applicazione per il resource specificato che raccoglie dati di telemetria. Lo span rappresenta un'operazione specifica che passa attraverso questo ambito, ovvero attraverso la libreria o il componente, all'interno della risorsa. Ad esempio, supponiamo che l'applicazione "checkout-service" sia sottoposta a deployment su Cloud Run, il che significa che resource è un'istanza Cloud Run specifica. Inoltre, supponi che la risorsa abbia diversi ambiti di strumentazione, come "request-authorization-library" e "payment-processor-library". Uno span client, come "WritePaymentInfoToStripe", potrebbe essere uno span segnalato dalla "payment-processor-library", che si trova all'interno del servizio Cloud Run denominato "checkout-service". Questo campo contiene i seguenti campi secondari: Campo Descrizione name string version string attributes JSON type Ogni attributo è una coppia chiave-valore. Gli attributi disponibili dipendono dai dati di traccia. La struttura degli attributi segue lo standard OpenTelemetry. Per saperne di più, consulta OpenTelemetry: Attributes. dropped_attributes_count integer Il numero di attributi eliminati. Gli attributi possono essere eliminati perché le relative chiavi sono troppo lunghe o perché sono presenti troppi attributi. Quando questo valore è zero, non sono stati eliminati attributi. Questo valore potrebbe essere impostato dalla strumentazione lato client o da un'applicazione. Il valore può essere incrementato dal server. Per saperne di più, consulta OpenTelemetry: ambito dell'instrumentazione.
resource_schema_link	string Questi campi devono essere un URL formattato come stringa. Questi campi contengono un URL che restituisce un file di schema per una risorsa. Il formato del file di schema e dei dati è definito da OpenTelemetry. Per ulteriori informazioni, consulta OpenTelemetry: Schemi. Questi campi possono essere impostati solo quando utilizzi l'API Telemetry. Questa API non verifica che i dati siano conformi allo schema dichiarato.
scope_schema_link	string Questi campi devono essere un URL formattato come stringa. Questi campi contengono un URL che restituisce un file di schema per un ambito. Il formato del file di schema e dei dati è definito da OpenTelemetry. Per ulteriori informazioni, consulta OpenTelemetry: Schemi. Questi campi possono essere impostati solo quando utilizzi l'API Telemetry. Questa API non verifica che i dati siano conformi allo schema dichiarato.
apphub	record senza campi ripetuti Le etichette specifiche dell'applicazione sono disponibili quando gli intervalli di traccia vengono generati dalle applicazioni App Hub, quando queste applicazioni vengono eseguite su infrastrutture supportate o sono state strumentate. Per scoprire di più sul monitoraggio delle applicazioni e quando queste etichette sono disponibili, consulta la panoramica del monitoraggio delle applicazioni. Questo campo contiene i campi secondari application, service e workload. Sottocampo dell'applicazione Descrizione container string location string id string Campo secondario Servizio/workload Descrizione id string environment_type string criticality_type string