Eseguire la migrazione dell'agente di raccolta per utilizzare gli esportatori OTLP

L'API Telemetry (OTLP) è un'implementazione del protocollo OpenTelemetry. Il supporto per OTLP ti consente di aggiungere esportatori otlphttp e otlp_grpc/otlp_logs generici alla configurazione del raccoglitore, evitando esportatori specifici del fornitore. Le applicazioni possono inviare dati di log, metriche e tracce all'API Telemetry.

Questa guida si applica se la configurazione del raccoglitore utilizza l' googlecloud esportatore o l' googlemanagedprometheus esportatore:

Per eseguire la migrazione agli esportatori OTLP, segui questi passaggi:

  1. Abilita l'API Telemetry
  2. Autorizza l'account di servizio del raccoglitore
  3. Imposta la variabile di ambiente GOOGLE_CLOUD_PROJECT
  4. Aggiungi l'estensione googleclientauth
  5. Aggiungi gli esportatori otlphttp e otlp_grpc/otlp_logs
  6. Aggiungi i processori
  7. Aggiorna le pipeline di servizio
  8. Convalida la configurazione
  9. Esegui la migrazione di dashboard e policy di avviso
  10. Rimuovi gli esportatori specifici del fornitore

Abilita l'API Telemetry

Gli esportatori OTLP scrivono nell'API Telemetry, quindi questa API deve essere abilitata nel tuo progetto. Per abilitare l'API Telemetry, esegui il seguente comando:

gcloud services enable telemetry.googleapis.com

Autorizza l'account di servizio del raccoglitore

L'agente di raccolta esegue l'autenticazione rispetto alle Google Cloud API utilizzando l'identità dell' ambiente in cui viene eseguito. L'account di servizio che esegue il raccoglitore deve avere l'autorizzazione per utilizzare l'API Telemetry per scrivere dati di log, metriche e tracce. Inoltre, poiché l'API Telemetry è un'API consumer, devi specificare in modo esplicito il Google Cloud progetto la cui quota viene consumata dalle chiamate API e concedere all'account di servizio le autorizzazioni necessarie per consumare la quota di quel progetto.

Ruoli obbligatori

Per assicurarti che l'account di servizio che esegue il raccoglitore disponga delle autorizzazioni necessarie per inviare dati di log, metriche e tracce, chiedi all'amministratore di concedere i seguenti ruoli IAM all'account di servizio che esegue il raccoglitore nel tuo progetto:

Questi ruoli predefiniti contengono le autorizzazioni necessarie per inviare dati di log, metriche e tracce. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per inviare dati di log, metriche e tracce sono necessarie le seguenti autorizzazioni:

  • logging.logEntries.create
  • monitoring.timeSeries.create
  • telemetry.traces.write
  • serviceusage.services.use

Account di servizio Kubernetes

Se esegui il deployment del raccoglitore su Google Kubernetes Engine (GKE) utilizzando Workload Identity Federation for GKE, concedi i ruoli richiesti al tuo account di servizio Kubernetes.

Puoi utilizzare i seguenti comandi per concedere i ruoli richiesti se la quota API viene prelevata dallo stesso Google Cloud progetto di destinazione delle chiamate API Telemetry. Prima di eseguire i comandi, sostituisci PROJECT_ID con l' ID del tuo progetto. Tuttavia, se utilizzi un progetto di quota separato, sostituisci PROJECT_ID nel secondo comando con l'ID del progetto di quota:

export PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")

gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/telemetry.writer \
  --member=principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector \
  --condition=None

gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/serviceusage.serviceUsageConsumer \
  --member=principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector \
  --condition=None

Service account per Workload Identity Federation for GKE

Se hai configurato un account di servizio per Workload Identity Federation for GKE, puoi utilizzare il comando nella documentazione di Google Cloud Managed Service per Prometheus per autorizzare il service account, con le seguenti modifiche:

  • Sostituisci gmp-test-sa con il nome del tuo account di servizio.
  • Esegui il comando per concedere i ruoli richiesti per scrivere dati di log, metriche e tracce.

Altro account di servizio

Se esegui il raccoglitore su una VM Compute Engine o al di fuori di GKE, concedi i ruoli richiesti al Google Cloud service account utilizzato dal deployment.

Imposta la variabile di ambiente GOOGLE_CLOUD_PROJECT

Imposta la variabile di ambiente GOOGLE_CLOUD_PROJECT nel deployment del raccoglitore. Il risultato è simile al seguente:

env:
- name: GOOGLE_CLOUD_PROJECT
  value: PROJECT_ID

Aggiungi l'estensione googleclientauth

Aggiungi l'estensione googleclientauth alla configurazione dell'agente di raccolta. L'API Telemetry è un'API consumer e richiede di specificare sia il Google Cloud progetto che il progetto di quota. Il risultato è simile al seguente:

extensions:
  googleclientauth:
    project: ${GOOGLE_CLOUD_PROJECT}
    quota_project: ${GOOGLE_CLOUD_PROJECT}

Aggiungi gli esportatori otlphttp e otlp_grpc/otlp_logs

Utilizza l'esportatore otlphttp per inviare dati di metriche e tracce in formato OTLP al tuo progetto e l'esportatore otlp_grpc/otlp_logs per inviare dati di log. Assicurati di configurare entrambi gli esportatori con l'estensione googleclientauth.

Il risultato è simile al seguente:

exporters:
  # ... existing content ...
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com
    auth:
      authenticator: googleclientauth
  otlp_grpc/otlp_logs:
    auth:
      authenticator: googleclientauth
    balancer_name: pick_first
    endpoint: telemetry.googleapis.com:443

Per l'esportatore otlp_grpc/otlp_logs, il campo endpoint deve essere specificato utilizzando il formato host:port.

Aggiungi i processori

In questa sezione sono elencati i processori che devi aggiungere all'agente di raccolta. Potresti voler utilizzare anche altri processori. Ad esempio, le configurazioni del raccoglitore Google-Built OpenTelemetry Collector in genere includono il processore memory_limiter e uno che trasforma i dati delle metriche. Per un esempio, vedi Google-Built OpenTelemetry Collector su GKE.

Aggiungi il processore resource/gcp_project_id

Aggiungi un processore resource che acquisisce informazioni sul tuo Google Cloud progetto.

  resource/gcp_project_id:
    attributes:
      - action: insert
        value: ${GOOGLE_CLOUD_PROJECT}
        key: gcp.project_id

Aggiungi il processore resourcedetection

Se esegui l'esecuzione su Google Cloud, valuta la possibilità di aggiungere il resourcedetection processore. Questo processore può scoprire automaticamente informazioni sulla tua architettura.

La seguente configurazione cerca le variabili di ambiente OpenTelemetry standard e poi esegue una query sul Google Cloud server dei metadati per raccogliere informazioni sulla tua infrastruttura:

  resourcedetection:
    detectors: ["env", "gcp"]

Aggiungi il processore batch

Per inviare la telemetria al tuo Google Cloud progetto in modo più efficiente, ti consigliamo di utilizzare il batch processore.

Ad esempio, il raccoglitore Google-Built OpenTelemetry Collector utilizza la seguente configurazione per il processore batch:

batch:
  send_batch_max_size: 200
  send_batch_size: 200
  timeout: 5s

Aggiungi il processore metricstarttime

Aggiungi il processore metricstarttime alla configurazione. Questo processore assicura che le metriche cumulative includano sia un'ora di inizio sia un'ora di osservazione. Per impostazione predefinita, le metriche Prometheus includono solo l'ora corrente. Pertanto, se ometti questo processore e la tua applicazione genera metriche Prometheus, i dati delle metriche potrebbero essere rifiutati o potresti notare picchi di dati.

Devi aggiungere questo processore se il raccoglitore riceve metriche Prometheus.

processors:
  # This processor ensures the start time is set for Prometheus metrics.
  # Set in the pipeline before the k8sattributes processor, if used.
  # No-op for OTLP metrics.
  metricstarttime:
    strategy: subtract_initial_point

Aggiungi il processore di trasformazione

Per conservare l'origine e la versione della strumentazione nei dati di log, aggiungi il seguente processore transform:

  transform/otlp_grpc/preserve_instrumentation_source_version:
    error_mode: ignore
    log_statements:
      - context: log
        statements:
          - set(attributes["instrumentation_source"], instrumentation_scope.name) where instrumentation_scope.name != ""
          - set(attributes["instrumentation_version"], instrumentation_scope.version) where instrumentation_scope.version != ""
          - set(attributes["service.name"], resource.attributes["service.name"]) where resource.attributes["service.name"] != nil
          - set(attributes["service.namespace"], resource.attributes["service.namespace"]) where resource.attributes["service.namespace"] != nil
          - set(attributes["service.instance.id"], resource.attributes["service.instance.id"]) where resource.attributes["service.instance.id"] != nil

Aggiorna le pipeline di servizio

Poi, aggiorna le pipeline del raccoglitore in modo che utilizzino gli esportatori otlp_grpc/otlp_logs e otlphttp. Per i dati di log e tracce, queste istruzioni sostituiscono l'esportatore corrente con l'esportatore OTLP appropriato. Per i dati delle metriche, queste istruzioni comportano scritture doppie. Questo approccio ti consente di verificare che l'esportatore OTLP stia inviando i dati delle metriche al tuo Google Cloud progetto. Ti consente inoltre di aggiornare grafici e policy di avviso prima di disattivare gli stream di dati dall'esportatore originale.

Apporta le seguenti modifiche alle configurazioni delle pipeline del raccoglitore:

  1. Aggiungi l'estensione googleclientauth alla voce service.

  2. Per la pipeline di log, sostituisci googlecloud/logging con otlp_grpc/otlp_logs e poi aggiungi i seguenti processori all'elenco dei processori della pipeline:

    • resource/gcp_project_id
    • transform/otlp_grpc/preserve_instrumentation_source_version
    • resourcedetection (se hai aggiunto questo processore)
    • batch

    Questa configurazione esegue una singola scrittura dei dati di log. Se vuoi scrivere i dati di log due volte, aggiungi l'esportatore otlp_grpc/otlp_logs all'elenco degli esportatori.

  3. Per la pipeline delle metriche, aggiungi l'esportatore otlphttp all'elenco degli esportatori della pipeline insieme all'esportatore googlemanagedprometheus, quindi aggiungi i seguenti processori:

    • resource/gcp_project_id
    • metricstarttime
    • resourcedetection (se hai aggiunto questo processore)
    • batch

    Questa configurazione esegue una doppia scrittura dei dati delle metriche. Dopo aver convalidato lo stream di dati delle metriche e aggiornato grafici e policy di avviso, rimuovi l'esportatore Prometheus.

  4. Per la pipeline delle tracce, sostituisci l'esportatore corrente con l'esportatore otlphttp, quindi aggiungi i seguenti processori:

    • resource/gcp_project_id
    • resourcedetection (se hai aggiunto questo processore)
    • batch

    Questa configurazione esegue una singola scrittura dei dati delle tracce.

Il risultato di queste modifiche è simile al seguente:

service:
  extensions: ["googleclientauth"]
  pipelines:
    logs:
      receivers: ["otlp"]
      processors:
        - resourcedetection
        - resource/gcp_project_id
        - transform/otlp_grpc/preserve_instrumentation_source_version
        - batch
      exporters: ["otlp_grpc/otlp_logs"]
    metrics:
      receivers: ["otlp"]
      processors:
        - resourcedetection
        - resource/gcp_project_id
        - metricstarttime
        - batch
      exporters: ["googlemanagedprometheus", "otlphttp"]
    traces:
      receivers: ["otlp"]
      processors:
        - resourcedetection
        - resource/gcp_project_id
        - batch
      exporters: ["otlphttp"]

Lo snippet precedente utilizza il ricevitore OTLP per i dati di log, metriche e tracce. La configurazione dell'agente di raccolta potrebbe essere diversa. Ad esempio, se hai un'applicazione che scrive dati di log strutturati, il ricevitore filelog è appropriato.

Convalida la configurazione

Riavvia il deployment e verifica che gli esportatori otlphttp e otlp_grpc/otlp_logs inviino dati al tuo Google Cloud progetto. Per verificare la configurazione:

  • Esegui una query sulle voci di log per verificare la presenza di errori relativi alla scrittura dei dati di telemetria.
  • Visualizza le percentuali di errore per l'API Cloud Logging, l'API Cloud Monitoring e l'API Telemetry.
  • Visualizza le serie temporali utilizzando Metrics Explorer.

Esegui la migrazione di dashboard e policy di avviso

Aggiorna i grafici e le dashboard nel seguente modo:

  1. Se monitori l'utilizzo dell'API Cloud Logging o dell'API Cloud Monitoring con grafici o policy di avviso, crea grafici o policy di avviso aggiuntivi per monitorare l'utilizzo dell'API Telemetry.

  2. Se i ricevitori di metriche includono un ricevitore otlp o se il raccoglitore esegue lo scraping delle metriche Prometheus con caratteri UTF-8, aggiorna i grafici e le dashboard. L'esportatore otlphttp genera metriche diverse dall'esportatore googlemanagedprometheus. Per ulteriori informazioni, vedi Differenze nel formato delle metriche esportate.

    Non devi aggiornare i grafici e le dashboard se il raccoglitore riceve solo dati delle metriche Prometheus.

  3. Se le pipeline delle metriche includono un prometheus ricevitore, si verificheranno conflitti di stream di dati tra le metriche generate dagli otlphttp e googlemanagedprometheus esportatori. Per risolvere questi conflitti, rimuovi l'esportatore googlemanagedprometheus.

Differenze nel formato delle metriche esportate

Gli aggiornamenti ai grafici e alle policy di avviso basati su metriche sono necessari a causa delle seguenti differenze tra le metriche esportate dagli esportatori OTLP e googlemanagedprometheus:

  • L'API Telemetry consente l'utilizzo dei caratteri punto (.) e barra (/) ne i nomi delle metriche. L'esportatore googlemanagedprometheus converte tutte le istanze di questi caratteri nel carattere di sottolineatura (_). Ad esempio, una metrica OTLP denominata prometheus.googleapis.com/foo.bar/gauge viene esportata letteralmente dall'esportatore OTLP, ma viene esportata come prometheus.googleapis.com/foo_bar/gauge dall'esportatore googlemanagedprometheus.

    Quando le metriche vengono importate, Cloud Monitoring crea descrittori di metriche in base ai nomi. La differenza nel modo in cui i caratteri punto (.) e barra (/) vengono gestiti dai percorsi di importazione significa che i descrittori di metriche risultanti differiscono tra le metriche importate utilizzando l'esportatore googlemanagedprometheus e quelle importate utilizzando l'esportatore otlphttp. Se utilizzi entrambi i percorsi di importazione, avrai due set di metriche; per ottenere risultati completi durante l'esecuzione di query, devi unire manualmente i risultati delle versioni Prometheus e OTLP delle metriche.

  • L'API Telemetry non aggiunge un'unità a un nome di metrica quando è presente un'unità e non aggiunge un suffisso _total ai contatori. Pertanto, una metrica esportata come prometheus.googleapis.com/foo/counter quando si utilizza l'API Telemetry viene esportata come prometheus.googleapis.com/foo_seconds_total/counter dall'esportatore googlemanagedprometheus. Questa differenza si applica anche ai suffissi _total e _ratio.

Per ulteriori informazioni sulle differenze tra le metriche, vedi Differenze tra l'esportatore googlemanagedprometheus e l'API Telemetry.

Le regole di trasformazione non si applicano alle metriche con caratteri UTF-8. Pertanto, devi riscrivere le dashboard e le policy di avviso in modo da utilizzare i nuovi nomi delle metriche o le query che combinano i nomi delle metriche precedenti e quelli nuovi. Non consigliamo di scrivere regole del processore per ricreare queste trasformazioni per continuare a scrivere metriche UTF-8 come se fossero state raccolte dall'esportatore googlemanagedprometheus. In questo modo si mantiene la retrocompatibilità, ma si sacrifica la compatibilità con le versioni successive e non potrai utilizzare asset open source che fanno riferimento ai nomi delle metriche UTF-8.

Rimuovi gli esportatori specifici del fornitore

Dopo aver convalidato i nuovi stream di dati e aggiornato le dashboard e le policy di avviso, rimuovi gli esportatori googlecloud/logging e googlemanagedprometheus dalla configurazione dell'agente di raccolta. Potresti anche dover rimuovere i processori utilizzati solo dagli esportatori rimossi dalla configurazione.

Devi aggiornare sia l'elenco degli esportatori sia le pipeline di servizio.

exporters:
  otlphttp: [...]
  otlp_grpc/otlp_logs: [...]

...
service:
  extensions: ["googleclientauth"]
  pipelines:
    logs:
      receivers: ["otlp"]
      processors: [...]
      exporters: ["otlp_grpc/otlp_logs"]
    metrics:
      receivers: ["otlp"]
      processors: [...]
      exporters: ["otlphttp"]
    traces:
      receivers: ["otlp"]
      processors: [...]
      exporters: ["otlphttp"]

Risoluzione dei problemi

Questa sezione descrive come risolvere gli errori che potrebbero verificarsi durante la migrazione della configurazione del raccoglitore.

Dati delle metriche mancanti o picchi nei dati delle metriche

Se i dati delle metriche sono mancanti o contengono picchi, verifica di aver aggiunto il processore metricstarttime alla configurazione del raccoglitore. Per ulteriori informazioni, vedi Aggiungere il processore metricstarttime.

Puoi anche esaminare i log del raccoglitore, i log di sistema e i log di controllo dell'accesso ai dati per Monitoring. Ad esempio, se una scrittura in una serie temporale non va a buon fine, viene generato un log di controllo dell'accesso ai dati che include il motivo dell'errore.

Messaggi di errore relativi alla scrittura di serie temporali

Il sistema genera messaggi di errore quando un tentativo di scrittura di dati in una serie temporale non va a buon fine. Puoi utilizzare questi messaggi per capire perché la scrittura non è riuscita e come risolvere il problema.

  • Messaggio di errore che indica una mancata corrispondenza dei valori:

    "One or more TimeSeries could not be written: Value type DOUBLE does not match metric descriptor value type INT64."

    Questo errore si verifica se in precedenza hai inviato metriche target_info INT64, perché l'API Telemetry imposta il tipo di valore di tutte le metriche su DOUBLE. La soluzione migliore a lungo termine è eliminare il descrittore della metrica per le metriche target_info INT64. Per eliminare questo descrittore dall'ambito delle metriche, utilizza questo script Golang.

  • Messaggio di errore che indica più origini che scrivono dati di serie temporali:

    "One or more TimeSeries could not be written: Points must be written in order. One or more of the points specified had an older end time than the most recent point."

    Per risolvere il problema, rimuovi l'esportatore googlemanagedprometheus dalla configurazione del raccoglitore. Per ulteriori informazioni, vedi Rimuovere gli esportatori specifici del fornitore.

Passaggi successivi