v1.traces overview

Questo documento descrive perché ti consigliamo di inviare i dati di traccia al tuo Google Cloud progetto utilizzando l'API Telemetry (OTLP), che implementa il protocollo di linea OpenTelemetry. Fornisce inoltre indicazioni su come instrumentare le applicazioni e su dove visualizzare i dati di traccia. Puoi utilizzare l' API Telemetry quando instrumenti le applicazioni utilizzando uno degli SDK OpenTelemetry o quando utilizzi un agente di raccolta OpenTelemetry.

Ti consigliamo di utilizzare l'API Telemetry per i seguenti motivi:

  • L'API fornisce la compatibilità con l'ecosistema OpenTelemetry open source e i suoi limiti sono spesso più generosi di quelli dell' API Cloud Trace, che è un'API proprietaria Google Cloud .

  • I dati di traccia vengono archiviati in un formato generalmente coerente con i file proto definiti dal protocollo di linea OpenTelemetry. Alcuni campi potrebbero essere convertiti da un tipo di dati specifico di OpenTelemetry a un tipo di dati JSON prima dell'archiviazione. Per saperne di più sul formato di archiviazione, consulta Schema per i dati di traccia.

  • La strumentazione non si basa su un Google Cloudesportatore specifico.

  • Alcune funzionalità, come il monitoraggio delle applicazioni, si basano su informazioni disponibili solo quando invii i dati di traccia all'API Telemetry.

OpenTelemetry è un progetto open source supportato Google Cloudcon Google Cloud ingegneri che garantiscono il supporto per l'importazione e la visualizzazione della telemetria.

Google Cloud Observability verifica che l'Cloud Trace API sia abilitata nel tuo Google Cloud progetto prima di archiviare i dati di traccia. Ciò significa che se disabiliti l'Cloud Trace API, Google Cloud Observability ignora i dati di traccia che invii all'API Telemetry.

Best practice

Quando instrumenti le applicazioni per inviare i dati di traccia al tuo Google Cloud progetto, ti consigliamo di utilizzare un esportatore che scrive i dati in formato OTLP in un agente di raccolta, che poi invia i dati di traccia all'API Telemetry. Nell'agente di raccolta, specifica solo l'URL di base:

exporters:
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com

OpenTelemetry rileva il tipo di dati e aggiunge automaticamente /v1/traces, /v1/metrics o /v1/logs, a seconda dei casi. Per saperne di più, consulta Richiesta OTLP/HTTP.

Per esempi di esportazione di dati di traccia o metriche nell'API Telemetry, consulta i seguenti documenti:

Quando non puoi utilizzare un agente di raccolta, puoi utilizzare una libreria OpenTelemetry che contiene un esportatore OTLP in-process per inviare la telemetria all'API Telemetry. Per scoprire come esportare direttamente i dati di traccia, consulta Esportatore Cloud Trace all'endpoint OTLP.

Autenticazione

Devi configurare gli esportatori con le credenziali necessarie per inviare i dati al tuo Google Cloud progetto. Ad esempio, quando utilizzi i collettori, in genere utilizzi l'estensione googleclientauth per l'autenticazione con le credenziali Google.

Per un esempio di autenticazione quando utilizzi l'esportazione diretta dei dati di traccia, consulta Configurare l'autenticazione. Questo esempio illustra come configurare l'esportatore con le Google Cloud credenziali predefinite dell'applicazione (ADC) e aggiungere una libreria di autenticazione Google specifica per la lingua all'applicazione.

Per inviare i dati di telemetria al tuo Google Cloud progetto utilizzando l'API Telemetry, devi anche:

Cloud Trace e residenza dei dati

Se utilizzi Assured Workloads perché hai requisiti di residenza dei dati o livello di impatto 4 (IL4) requisiti, non utilizzare l'API Telemetry per inviare gli intervalli di traccia al tuo progetto.

Dove visualizzare i dati importati

Puoi visualizzare i dati di traccia utilizzando le pagine Esplora tracce e Analisi di osservabilità. Per informazioni, consulta: