Eseguire la migrazione all'esportatore OTLP

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini di servizio specifici. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni delle fasi di lancio.

Questo documento descrive come modificare una configurazione di OpenTelemetry Collector che utilizza un esportatore esistente, in questo caso l'esportatore googlemanagedprometheus, per utilizzare l'esportatore otlphttp e l'API Telemetry (OTLP), telemetry.googleapis.com.

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

Abilita l'API Telemetry

L'esportatore otlphttp scrive all'API Telemetry, quindi questa API deve essere abilitata nel tuo progetto. Abilita l'API Telemetry eseguendo il comando seguente:

gcloud services enable telemetry.googleapis.com

Autorizza il account di servizio Kubernetes

Il account di servizio Kubernetes deve disporre dell'autorizzazione per utilizzare l'API Telemetry. I seguenti comandi concedono il ruolo Identity and Access Management (IAM) necessario alaccount di serviziot Kubernetes. Questi comandi presuppongono che tu stia utilizzando Workload Identity Federation for GKE:

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

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

Sostituisci la variabile PROJECT_ID con l'ID del tuo progetto Google Cloud .

Se il tuo account di servizio ha un formato diverso, puoi utilizzare il comando nella documentazione di Google Cloud Managed Service per Prometheus per autorizzare il service account, con le seguenti modifiche:

• Sostituisci il nome del service account gmp-test-sa con il tuo account di servizio.
• Esegui il comando per concedere il ruolo roles/telemetry.metricsWriter.

Imposta la variabile di ambiente PROJECT_ID

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

env:
- name: PROJECT_ID
  value: PROJECT_ID

Individua l'esportatore da sostituire.

Nel file di configurazione, individua l'esportatore e il servizio che lo utilizza:

exporters:
  googlemanagedprometheus:
service:
  pipelines:
    metrics:
      exporters: [googlemanagedprometheus]

Aggiungi la configurazione per l'esportatore otlphttp

In questo passaggio, aggiungi l'esportatore otlphttp e il processore metricstarttime alla configurazione. Questo esportatore aggiuntivo fa sì che il collettore scriva due volte le metriche.

• Se utilizzi metriche native OTLP, la doppia scrittura non causa problemi perché la struttura dei descrittori delle metriche creati con i due metodi è diversa. Si tratta di metriche separate.
• Se utilizzi le metriche Prometheus, vedrai collisioni finché non rimuovi l'esportatore googlemanagedpromethus.

La configurazione aggiornata è simile alla seguente:

exporters:
  googlemanagedprometheus:
  otlphttp:
    encoding: json
    endpoint: https://telemetry.googleapis.com
    auth:
      authenticator: googleclientauth
processors:
  # This processor ensures the start time is set for Prometheus metrics. This must be set in the pipeline before the k8sattributes processor, if used.
  metricstarttime:
    strategy: subtract_initial_point
  resource/gcp_project_id:
    attributes:
    - action: insert
      # Make sure you set the PROJECT_ID environment variable.
      value: ${PROJECT_ID}
      key: gcp.project_id
extensions:
  googleclientauth:
service:
  extensions: [googleclientauth]
  pipelines:
    metrics:
      processors: [resource/gcp_project_id, metricstarttime]
      exporters: [googlemanagedprometheus, otlphttp]

Dopo aver scritto due volte le metriche, aggiorna le dashboard e le policy di avviso per utilizzare i nuovi nomi delle metriche generati dall'esportatore otlphttp. L'esportatore otlphttp non rinomina le metriche in modo che siano in "stile Prometheus", utilizzando sostituzioni con il carattere di sottolineatura.

Nota: poiché l'API Telemetry imposta il tipo di valore di tutte le metriche su DOUBLE, prevediamo che possano verificarsi conflitti di tipo di valore, in particolare se in precedenza hai inviato metriche INT64 target_info. Se si verificano collisioni, la soluzione migliore a lungo termine è eliminare il descrittore della metrica per le metriche INT64 target_info. Per eliminare questo descrittore dall'ambito della metrica, utilizza questo script Golang.

Rimuovi la configurazione per l'esportatore precedente

Dopo aver aggiornato le dashboard e gli avvisi in modo che facciano riferimento alle metriche esportate otlphttp, rimuovi il vecchio esportatore, googlemanagedprometheus in questo caso, dalla configurazione. La configurazione rivista è simile alla seguente:

exporters:
  otlphttp:
    encoding: json
    endpoint: https://telemetry.googleapis.com
    auth:
      authenticator: googleclientauth
processors:
  # This processor ensures the start time is set for Prometheus metrics. This must be set in the pipeline before the k8sattributes processor, if used.
  metricstarttime:
    strategy: subtract_initial_point
  resource/gcp_project_id:
    attributes:
    - action: insert
      # Make sure you set the PROJECT_ID environment variable.
      value: ${PROJECT_ID}
      key: gcp.project_id
extensions:
  googleclientauth:
service:
  extensions: [googleclientauth]
  pipelines:
    metrics:
      processors: [resource/gcp_project_id, metricstarttime]
      exporters: [otlphttp]

Migra le dashboard e le norme di avviso, se necessario

Se hai utilizzato l'esportatore googlemanagedprometheus solo per i dati delle metriche Prometheus, quando passi all'esportatore OTLP, i dashboard e i criteri di avviso esistenti continueranno a funzionare.

Tuttavia, se hai utilizzato l'esportatore googlemanagedprometheus per raccogliere e inviare dati originariamente emessi utilizzando OTLP o se hai eseguito lo scraping delle metriche Prometheus con caratteri UTF-8, devi aggiornare i dashboard e gli avvisi in modo che utilizzino il nome della metrica UTF-8.

Ciò è dovuto alle seguenti differenze tra le metriche esportate utilizzando OTLP e le metriche esportate utilizzando l'esportatore googlemanagedprometheus:

• L'API Telemetry consente l'utilizzo dei caratteri punto (.) e barra (/) nei 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 fa sì che i descrittori delle metriche risultanti differiscano 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 vale anche per i suffissi _total e _ratio.

Per saperne di più sulle differenze tra le metriche, consulta Differenze tra l'esportatore googlemanagedprometheus e l'API Telemetry.

Poiché le regole di trasformazione non si applicano alle metriche con caratteri UTF-8, devi riscrivere le dashboard e le norme di avviso per utilizzare i nuovi nomi delle metriche o per unire i nomi delle metriche vecchi e nuovi.

Non è consigliabile scrivere regole del processore per ricreare queste trasformazioni per continuare a scrivere metriche UTF-8 come se fossero raccolte dall'esportatore googlemanagedprometheus. In questo modo si mantiene la compatibilità con le versioni precedenti, ma si sacrifica la compatibilità futura e non potrai utilizzare facilmente gli asset open source che fanno riferimento ai nomi delle metriche UTF-8.