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 l'OpenTelemetry Protocol. Questa API ti consente di raccogliere dati di telemetria indipendenti dal fornitore da SDK e raccoglitori OpenTelemetry senza utilizzare esportatori Google Cloud personalizzati.

Quando invii la telemetria al tuo progetto utilizzando l'API Telemetry, Google Cloud Observability elabora ogni segnale nel seguente modo:

  • 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:memorizza le tracce distribuite in un formato generalmente coerente con OTLP.

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

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 gRPC OTLP 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 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 della lingua alla tua applicazione.

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

  • Configurare un progetto di quota. Per saperne di più, consulta la sezione Impostare 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 quota.
    • Ruolo Cloud Telemetry Writer (roles/telemetry.writer) sul 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 traccia vengono convertiti da OTLP in strutture di dati di Google Cloud Observability.

Importazione dati di log

Quando utilizzi l'API Telemetry per importare log in formato OTLP, i dati di log vengono convertiti in voci di log di Cloud Logging. Una richiesta di log in formato 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 ulteriori informazioni 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 in formato OTLP, la struttura di Cloud Logging LogEntry 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à 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 rimandano a schemi di risorse esterni, tutti i metadati di risorse, ambito ed entità OTLP vengono copiati in ogni voce di log.

Importazione dati delle metriche

OTLP per le metriche 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 devono non avere un dominio o 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, tranne 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 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 si trovano nel 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, consigliamo di utilizzare l'API Telemetry perché fornisce quote di importazione più elevate rispetto all&#39Cloud Trace APIe.

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 memorizzato:

  • 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 in campi con nomi simili nello schema di traccia.

Per saperne di più, consulta i seguenti documenti:

Fatturazione

La fatturazione dei dati di log, metriche e traccia 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 nei 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ù importanti all'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 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 quanto segue:

  • 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 che i metadati aggiuntivi vengano conservati nel campo otel, utilizza l'opzione di mappatura precedente, gcp.use_legacy_mapping, che impedisce il popolamento del campo otel.

Fatturazione dei dati delle metriche

La fatturazione delle metriche OTLP viene contabilizzata in base allo SKU "Campioni Prometheus importati", lo stesso utilizzato per le metriche di Google Cloud Managed Service per Prometheus.

Fatturazione dei dati di Trace

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

Esecuzione di query sui dati di log, metriche e tracce

Puoi utilizzare le pagine di esplorazione, 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 traccia utilizzando SQL.

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

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

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

  • Se mantieni l'etichetta le quando esegui query sugli istogrammi esponenziali, potresti ottenere risultati imprevisti. È previsto che funzionino le query più tipiche histogram_quantile(.99, sum by (le) (metric)).

  • Le metriche delta potrebbero non essere eseguite correttamente in determinate circostanze, ad esempio 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 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 inserite 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 sono previsti limiti o quote aggiuntivi.

Passaggi successivi