Supporto di OTLP in Google Cloud Observability

Puoi importare dati di log, metriche e tracce in formato OTLP in Google Cloud Observability utilizzando l'API Telemetry (OTLP), che implementa il protocollo OpenTelemetry. Questa API ti consente di raccogliere dati di telemetria indipendenti dal fornitore dagli SDK e dai collector OpenTelemetry senza utilizzare esportatori Google Cloud personalizzati.

Quando invii la telemetria al tuo progetto utilizzando l'API Telemetry, Google Cloud Observability elabora ogni indicatore come segue:

  • Dati di log: converte i record di log OTLP in voci di log e li indirizza per l'archiviazione.
  • Dati delle metriche: mappa i dati delle metriche alle serie temporali di Prometheus in Cloud Monitoring.
  • Dati di traccia: archivia le tracce distribuite in un formato generalmente coerente con OTLP.

Se esegui workload su Google Kubernetes Engine, puoi utilizzare OpenTelemetry gestito per GKE anziché eseguire il deployment e la gestione manuale di un Collector OpenTelemetry.

Supporto dei protocolli

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 progetto Google Cloud . 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 Configura 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 il linguaggio alla tua applicazione.

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

  • Configura un progetto di quota. Per scoprire di più, consulta Imposta il progetto di quota.

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

    • Ruolo Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) nel progetto di quota.
    • Ruolo Cloud Telemetry Writer (roles/telemetry.writer) sul progetto. Questo ruolo consente alla tua 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 dati di log vengono convertiti in voci di log di Cloud Logging. Una richiesta di log in entrata formattata in OTLP 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 richiesti per l'importazione dei log in formato OTLP, consulta Mappatura degli attributi OTLP al tipo di risorsa.

Per supportare l'importazione di log formattati in 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 della risorsa, dell'ambito e dell'entità della 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 si collegano a schemi di risorse esterni, tutti i metadati delle risorse, degli ambiti e delle entità OTLP vengono copiati in ogni voce di log.

Importazione dati delle metriche

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

Quando le metriche vengono importate in Cloud Monitoring utilizzando un OpenTelemetry Collector 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 quanto segue:

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 Cloud Monitoring risultante ha la seguente struttura:

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

Inoltre, per ogni risorsa OpenTelemetry univoca, la conversione aggiunge una metrica target_info che contiene tutti gli attributi della risorsa, 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 l'intero set di caratteri UTF-8, 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 etichetta) 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 funzione replace_pattern 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 progetto Google Cloud :

{
  "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. Campi come traceId, spanId e kind vengono mappati a campi con nomi simili nello schema di traccia.

Per saperne di più, consulta i seguenti documenti:

Fatturazione

La fatturazione per i 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 variazione dei valori di archiviazione e fatturazione di Cloud Logging quando utilizzi l'API Telemetry per importare i log a causa di una variazione del volume dei log.

Le modifiche più significative allo spazio di archiviazione e alla fatturazione per il tuo progetto Google Cloud si verificano quando sono soddisfatte entrambe le seguenti condizioni:

  • Il campo resource contiene attributi con cardinalità elevata o un numero elevato di attributi. Questi attributi della risorsa 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é i metadati di questa risorsa e di questo 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:

  • Utilizza 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 di conservare i metadati aggiuntivi 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 per le metriche OTLP viene contabilizzata nello SKU "Prometheus Samples Ingested", 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 di esplorazione (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 tracce utilizzando SQL.

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

  • Importante: per eseguire query su nomi di metriche e chiavi di 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"}

  • Se mantieni l'etichetta le quando esegui query su istogrammi esponenziali, potresti ottenere risultati imprevisti. Le query histogram_quantile(.99, sum by (le) (metric)) più tipiche dovrebbero funzionare.

  • In determinate circostanze, le metriche delta potrebbero non essere interrogate correttamente, ad esempio nel caso di delta molto sparsi.

Limiti e quote

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

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 quote e 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