Eseguire la migrazione all'esportatore OTLP

Questo documento descrive come modificare una configurazione delle metriche 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 di Prometheus funziona solo quando si utilizza OpenTelemetry Collector versione 0.140.0 o successive.

Abilitare l'API Telemetry

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

gcloud services enable telemetry.googleapis.com

Autorizzare 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 al account di servizio 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 Google Cloud progetto.

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.

Impostare la variabile di ambiente PROJECT_ID

Imposta la variabile di ambiente PROJECT_ID nel deployment dell'agente di raccolta. Il risultato è simile al seguente:

env:
- name: PROJECT_ID
  value: PROJECT_ID

Individuare l'esportatore da sostituire

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

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

Aggiungere 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 l'agente di raccolta scriva le metriche due volte.

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

La configurazione aggiornata è simile alla seguente. Assicurati di impostare il processore metricstarttime durante la migrazione:

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 le metriche due volte, aggiorna le dashboard e le policy di avviso in modo che utilizzino 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 trattini bassi.

Rimuovere la configurazione per l'esportatore precedente

Dopo aver aggiornato le dashboard e gli avvisi in modo che facciano riferimento alle metriche esportate da otlphttp, rimuovi il vecchio esportatore, in questo caso googlemanagedprometheus, 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]

Eseguire la migrazione delle dashboard e delle policy di avviso, se necessario

Se hai utilizzato l'esportatore googlemanagedprometheus solo per i dati delle metriche di Prometheus, quando passi all'esportatore OTLP, le dashboard e le policy 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 di Prometheus con caratteri UTF-8, devi aggiornare le dashboard e gli avvisi in modo che utilizzino il nome della metrica UTF-8.

Questo è 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 (/) ne i nomi delle metriche. L'esportatore googlemanagedprometheus converte tutte le istanze di questi caratteri nel carattere trattino basso (_). 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 di 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, hai 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, 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 policy di avviso in modo che utilizzino i nuovi nomi delle metriche o uniscano 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 state raccolte dall'esportatore googlemanagedprometheus. In questo modo si mantiene la retrocompatibilità, ma si sacrifica la compatibilità con le versioni successive e non sarà possibile utilizzare facilmente le risorse open source che fanno riferimento ai nomi delle metriche UTF-8.