Panoramica dell'importazione OTLP

Questo documento introduce l'utilizzo dell' API Telemetry (OTLP), telemetry.googleapis.com, che implementa il protocollo OpenTelemetry. L'API Telemetry consente di importare dati di log, metriche e tracce in formato OTLP in Google Cloud Observability:

  • I record di log OTLP vengono convertiti in voci di log quindi vengono instradati e archiviati. Per informazioni sulla procedura di conversione, consulta la sezione Importazione dei log OTLP di questo documento.
  • I dati delle metriche vengono importati in Cloud Monitoring. Per informazioni sui nomi delle metriche e delle etichette e sulle limitazioni di importazione, consulta la sezione Importazione delle metriche OTLP di questo documento.
  • I dati di Trace vengono archiviati in un formato generalmente coerente con OTLP. Per saperne di più, consulta Importazione delle tracce OTLP.

Puoi inviare dati di telemetria all'API Telemetry dalle applicazioni che utilizzano gli SDK o esportandoli da un raccoglitore OpenTelemetry.

Se utilizzi Google Kubernetes Engine, puoi utilizzare OpenTelemetry gestito per GKE anziché eseguire il deployment e la configurazione manuale di un agente di raccolta OpenTelemetry che utilizza l' API Telemetry.

Supporto del protocollo

L'endpoint OTLP supporta tutti i protocolli di trasporto e serializzazione OTLP, inclusi http/protobuf, http/json e grpc. Quando esporti direttamente dalle applicazioni utilizzando gli SDK, ti consigliamo di utilizzare l'esportatore OTLP gRPC anziché gli esportatori HTTP, perché la maggior parte degli esportatori SDK non supporta l'aggiornamento dinamico dei token.

Autenticazione

Devi configurare gli esportatori con le credenziali necessarie per inviare i dati al tuo Google Cloud progetto. Ad esempio, quando utilizzi i raccoglitori, 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 tue Google Cloud credenziali predefinite dell'applicazione (ADC) e aggiungere una libreria di autenticazione Google specifica per la lingua alla tua applicazione.

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

  • Configurare un progetto di quota. Per saperne di più, consulta Impostare il progetto di quota.

  • Concedere i seguenti ruoli Identity and Access Management (IAM) all'utente o all'account di servizio utilizzato dall'applicazione:

    • Ruolo Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) nel progetto di quota.
    • Ruolo Cloud Telemetry Writer (roles/telemetry.writer) nel progetto. Questo ruolo consente all'applicazione di scrivere dati di log, metriche e tracce.

Importazione OTLP

Questa sezione descrive come i dati di log, metriche e tracce vengono convertiti da OTLP in strutture di dati di Google Cloud Observability.

Importazione dati di log

Quando utilizzi l'API Telemetry per importare i log in formato OTLP, i tuoi dati di log vengono convertiti in voci di log di Cloud Logging . Una richiesta di log in formato OTLP in entrata in JSON ha la seguente struttura generale:

"resourceLogs": [
    {
      "resource": {
        "attributes": [...]
      },
      "scopeLogs": [
        {
          "scope": { ...}
          "logRecords": [...]
        }
      ]
    }
]

Ogni elemento di ogni array logRecords diventa una singola voce di log di Cloud Logging. Gli attributi resource determinano la risorsa monitorata nel LogEntry risultante. Per saperne di più sugli attributi necessari per l'importazione dei log in formato OTLP, consulta Mappatura degli attributi OTLP ai tipi di risorse.

Per supportare l'importazione dei log in formato OTLP, la struttura LogEntry di Cloud Logging contiene un campo aggiuntivo, otel. Poiché i modelli di dati OTLP e Cloud Logging differiscono nella struttura, il campo otel conserva una copia dei metadati di risorsa, ambito ed entità dalla richiesta OTLP in entrata.

Ad esempio, se invii un payload OTLP resourceLogs come il seguente all'API Telemetry, ogni voce di log risultante contiene un campo resource (per la risorsa monitorata) e un campo otel, come mostrato nelle altre schede:

resourceLogs 

{
  "resourceLogs": [
    {
      "resource": {
        "attributes": [
          {
            "key": "gcp.project_id",
            "value": { "stringValue": "PROJECT_ID" }
          },
          {
            "key": "gcp.resource_type",
            "value": { "stringValue": "global" }
          }
        ]
      },
      "scopeLogs": [
        {
          "scope": {
            "name": "my.library",
            "version": "1.0.0",
            "attributes": [
              {
                "key": "my.scope.attribute",
                "value": { "stringValue": "some scope attribute" }
              }
            ]
          },
          "logRecords": [ ... ]
         }
       ]
     }
   ]
}

resource 

  {
    ...
    "resource": {
      "labels": {
        "project_id": "PROJECT_ID"
      },
      "type": "global"
    },
    ...
}

otel 

  {
    ...
    "otel": {
      "resource": {
        "attributes": {
          "gcp.project_id": "PROJECT_ID",
          "gcp.resource_type": "global"
        }
      },
      "scope": {
        "attributes": {
          "my.scope.attribute": "some scope attribute"
        },
        "name": "my.library",
        "version": "1.0.0"
      }
    },
   ...
  }

Poiché le voci di log di Cloud Logging sono autonome e non rimandano a schemi di risorse esterni, tutti i metadati di risorsa, ambito ed entità OTLP vengono copiati in ogni voce di log.

Importazione dati delle metriche

OTLP per le metriche di Prometheus funziona solo quando utilizzi OpenTelemetry Collector versione 0.140.0 o successive.

Quando le metriche vengono acquisite in Cloud Monitoring utilizzando un agente di raccolta OpenTelemetry e l'esportatore otlphttp o inviate direttamente utilizzando un SDK OpenTelemetry, le metriche OTLP vengono mappate alle strutture delle metriche di Cloud Monitoring. Per informazioni su queste mappature, consulta:

Google Cloud Observability converte le metriche nel formato delle serie temporali di Prometheus. I nomi delle metriche non devono avere un dominio o devono avere il dominio prometheus.googleapis.com. Dopo la conversione, il nome della metrica include il prefisso prometheus.googleapis.com e un suffisso aggiuntivo, in base al tipo di punto OTLP. La metrica di Cloud Monitoring risultante ha la seguente struttura:

prometheus.googleapis.com/{metric_name}/{suffix}

Inoltre, per ogni risorsa OpenTelemetry univoca, la conversione aggiunge una target_info metrica che contiene tutti gli attributi delle risorse, ad eccezione di service.name, service.instance.id, e service.namespace.

Poiché i nomi delle metriche e le chiavi delle etichette in Cloud Monitoring non supportano UTF-8 completo, i dati delle metriche possono essere rifiutati:

  • I nomi delle metriche che non sono conformi all'espressione regolare [a-zA-Z][a-zA-Z0-9_:./-]* vengono rifiutati. Gli unici caratteri speciali consentiti nei nomi delle metriche sono quelli del set _:./-.
  • I punti dati contenenti attributi (ovvero chiavi di etichette) che non sono conformi all'espressione regolare [a-zA-Z_][a-zA-Z0-9_.]* vengono rifiutati. Gli unici caratteri speciali consentiti nelle chiavi delle etichette sono quelli del set _.. Tutti i caratteri speciali sono consentiti nei valori delle etichette.

Per evitare il rifiuto delle metriche per questi motivi, utilizza la replace_pattern funzione per trasformare i nomi e gli attributi delle metriche.

Trace dei importazione dati di traccia

Indipendentemente dal fatto che utilizzi l'API Telemetry o l'Cloud Trace API, i dati di traccia in entrata vengono archiviati in un formato coerente con OTLP. Tuttavia, ti consigliamo di utilizzare l'API Telemetry perché fornisce quote di importazione più elevate rispetto all'Cloud Trace API.

Di seguito è riportato un esempio di dati di traccia che potrebbero essere inviati da un'applicazione al tuo Google Cloud progetto:

{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [...]
      },
      "scopeSpans": [
        {
          "scope": { ...},
          "spans": [...]
        }
      ]
    }
  ]
}

Ogni elemento di ogni array scopeSpans.spans diventa un singolo intervallo archiviato:

  • Il campo resource di ogni intervallo contiene una copia dei dati resourceSpans.resource.attributes.
  • Il campo instrumentation_scope di ogni intervallo contiene una copia dei dati scopeSpans.scope.
  • Ogni intervallo corrisponde a una voce nell'array scopeSpans.spans. I campi come traceId, spanId e kind vengono mappati in campi con nomi simili nello schema di traccia.

Per ulteriori informazioni, consulta i seguenti documenti:

Fatturazione

La fatturazione dei dati di log, metriche e tracce importati utilizzando l'API Telemetry dipende dal segnale di telemetria. Per informazioni complete, consulta la pagina Fatturazione.

Fatturazione dei dati di log

Potresti notare una modifica nei valori di archiviazione e fatturazione di Cloud Logging quando utilizzi l'API Telemetry per importare i log a causa di una modifica del volume dei log.

Le modifiche più significative all'archiviazione e alla fatturazione del tuo Google Cloud progetto si verificano quando sono soddisfatte entrambe le seguenti condizioni:

  • Il campo resource contiene attributi di cardinalità elevata o un numero elevato di attributi. Questi attributi delle risorse determinano la risorsa monitorata nel LogEntry risultante.
  • Il campo scopeLogs contiene un numero elevato di elementi negli array logRecords. I campi scopeLogs.scope vengono copiati nel campo otel per ogni singola voce di log.

Poiché questi metadati di risorsa e ambito vengono copiati in ogni singola voce di log, il volume dei log archiviati può aumentare.

Per ridurre al minimo il volume di archiviazione, ti consigliamo di:

  • Utilizzare un processore OpenTelemetry Collector, ad esempio un processore transform, per eliminare gli attributi di risorsa o ambito non necessari prima di esportare i dati.
  • Se non hai bisogno dei metadati aggiuntivi conservati nel campo otel, utilizza l'opzione di mappatura precedente, gcp.use_legacy_mapping, che impedisce la compilazione del campo otel.

Fatturazione dei dati delle metriche

La fatturazione delle metriche OTLP viene contabilizzata nello SKU "Esempio di Prometheus importati", lo stesso utilizzato per le metriche di Google Cloud Managed Service per Prometheus.

Fatturazione dei dati di traccia

L'API che utilizzi per inviare i dati di traccia al tuo progetto non influisce sul modo in cui vengono calcolati gli addebiti per questi dati.

Esecuzione di query sui dati di log, metriche e tracce

Puoi utilizzare le pagine dell'explorer, ovvero Esplora log, Metrics Explorer ed Esplora tracce, per eseguire query sui dati di log, metriche e tracce. Puoi anche utilizzare la pagina Observability Analytics per analizzare i dati di log e di traccia utilizzando SQL.

I seguenti suggerimenti potrebbero essere utili quando esegui query sui dati delle metriche utilizzando Metrics Explorer:

  • Importante: per eseguire query sui nomi delle metriche e sulle chiavi delle etichette con caratteri speciali diversi dai due punti (:) e dal trattino basso (_), devi racchiuderli tra parentesi graffe ({}) e virgolette ("), in base alla specifica UTF-8 di PromQL. Ad esempio, le seguenti sono query valide:

    • {"my.metric.name"}
    • {"my.metric.name", "label.key.KEY"="value"}

  • La conservazione dell'etichetta le durante l'esecuzione di query sugli istogrammi esponenziali potrebbe restituire risultati imprevisti. È previsto che le query histogram_quantile(.99, sum by (le) (metric)) più tipiche funzionino.

  • Le metriche delta potrebbero non essere sottoposte a query correttamente in determinate circostanze, ad esempio delta molto sparse.

Limiti e quote

I limiti dell'API Telemetry si applicano a tutti i tipi di segnali.

Si applicano anche le seguenti quote e i seguenti limiti:

  • Dati di log: si applicano le quote e i limiti dell'API Cloud Logging.

  • Dati delle metriche: si applicano le quote e i limiti dell'API Cloud Monitoring. Ad esempio, le metriche non possono avere più di 200 etichette.

    La quota predefinita per le metriche importate dall'API Telemetry è di 60.000 richieste al minuto. Con una dimensione massima del batch di 200 punti per richiesta, questa quota è una quota predefinita effettiva di 200.000 campioni al secondo. Puoi richiedere un aumento della quota.

  • Dati di Trace: non si applicano quote o limiti aggiuntivi.

Passaggi successivi