Inizia a utilizzare OpenTelemetry Collector

Questo documento descrive come configurare OpenTelemetry Collector per eseguire lo scraping dei dati delle metriche Prometheus standard e segnalarle a Google Cloud Managed Service per Prometheus. OpenTelemetry Collector è un agente di cui puoi eseguire il deployment e che puoi configurare per l'esportazione in Managed Service per Prometheus. La configurazione è simile all'esecuzione di Managed Service per Prometheus con una raccolta con deployment autonomo.

Potresti scegliere OpenTelemetry Collector anziché la raccolta con deployment autonomo per i seguenti motivi:

  • OpenTelemetry Collector ti consente di instradare i dati di telemetria a più backend configurando diversi esportatori nella tua pipeline.
  • Il raccoglitore supporta anche indicatori da metriche, log e tracce, quindi usandolo puoi gestire tutti e tre i tipi di indicatori in un unico agente.
  • Il formato dei dati indipendente dal fornitore di OpenTelemetry (OpenTelemetry Protocol o OTLP) supporta un solido ecosistema di librerie e componenti di Collector collegabili. Ciò consente di avere una gamma di opzioni di personalizzazione per la ricezione, l'elaborazione e l'esportazione dei dati.

Il compromesso per questi vantaggi è che l'esecuzione di un raccoglitore OpenTelemetry richiede un approccio di deployment e manutenzione autogestito. L'approccio che scegli dipende dalle tue esigenze specifiche, ma in questo documento offriamo linee guida consigliate per configurare OpenTelemetry Collector utilizzando Managed Service per Prometheus come backend.

Prima di iniziare

Questa sezione descrive la configurazione necessaria per le attività descritte in questo documento.

Configura progetti e strumenti

Per utilizzare Google Cloud Managed Service per Prometheus, sono necessarie le seguenti risorse:

  • Un progetto Google Cloud con l'API Cloud Monitoring abilitata.

    • Se non hai un progetto Google Cloud:

      1. Nella console Google Cloud, vai a Nuovo progetto:

        Crea un nuovo progetto

      2. Nel campo Nome progetto, inserisci un nome per il progetto e fai clic su Crea.

      3. Vai a Fatturazione:

        Vai a Fatturazione

      4. Seleziona il progetto appena creato, se non è già selezionato in alto.

      5. Ti viene chiesto di scegliere un profilo pagamenti esistente o di crearne uno nuovo.

      L'API Monitoring è abilitata per impostazione predefinita per i nuovi progetti.

    • Se hai già un progetto Google Cloud, assicurati che l'API Monitoring sia abilitata:

      1. Vai ad API e servizi:

        Vai ad API e servizi

      2. Seleziona il progetto.

      3. Fai clic su Abilita API e servizi.

      4. Cerca "Monitoring".

      5. Nei risultati di ricerca, fai clic su "API Cloud Monitoring".

      6. Se non viene visualizzato "API abilitata", fai clic sul pulsante Abilita.

  • Un cluster Kubernetes. Se non disponi di un cluster Kubernetes, segui le istruzioni riportate nella Guida rapida per GKE.

Sono necessari anche i seguenti strumenti a riga di comando:

  • gcloud
  • kubectl

Gli strumenti gcloud e kubectl fanno parte di Google Cloud CLI. Per informazioni su come installarli, consulta Gestione dei componenti di Google Cloud CLI. Per visualizzare i componenti gcloud CLI che hai installato, esegui questo comando:

gcloud components list

Configura il tuo ambiente

Per evitare di inserire ripetutamente l'ID progetto o il nome del cluster, esegui la seguente configurazione:

  • Configura gli strumenti a riga di comando come segue:

    • Configura gcloud CLI per fare riferimento all'ID del tuo progetto Google Cloud:

      gcloud config set project PROJECT_ID

    • Configura l'interfaccia a riga di comando kubectl per utilizzare il cluster:

      kubectl config set-cluster CLUSTER_NAME

    Per ulteriori informazioni su questi strumenti, consulta le seguenti risorse:

Configura uno spazio dei nomi

Crea lo spazio dei nomi Kubernetes NAMESPACE_NAME per le risorse che crei nell'ambito dell'applicazione di esempio:

kubectl create ns NAMESPACE_NAME

Verifica le credenziali dell'account di servizio

Puoi saltare questa sezione se per il tuo cluster Kubernetes è abilitata Workload Identity.

Durante l'esecuzione su GKE, Managed Service per Prometheus recupera automaticamente le credenziali dall'ambiente in base all'account di servizio predefinito di Compute Engine. L'account di servizio predefinito ha le autorizzazioni necessarie, monitoring.metricWriter e monitoring.viewer, per impostazione predefinita. Se non utilizzi Workload Identity e in precedenza hai rimosso uno di questi ruoli dall'account di servizio del nodo predefinito, dovrai riaggiungere le autorizzazioni mancanti prima di continuare.

Se non stai eseguendo su GKE, consulta Fornire le credenziali in modo esplicito.

Configura un account di servizio per Workload Identity

Puoi saltare questa sezione se per il tuo cluster Kubernetes non è abilitata Workload Identity.

Managed Service per Prometheus acquisisce i dati delle metriche utilizzando l'API Cloud Monitoring. Se il cluster utilizza Workload Identity, devi concedere al tuo account di servizio Kubernetes l'autorizzazione all'API Monitoring. Questa sezione descrive quanto segue:

Crea e associa l'account di servizio

Questo passaggio viene visualizzato in diverse sezioni della documentazione di Managed Service per Prometheus. Se hai già eseguito questo passaggio come parte di un'attività precedente, non è necessario ripeterlo. Vai avanti per autorizzare l'account di servizio.

La seguente sequenza di comandi crea l'account di servizio gmp-test-sa e lo associa all'account di servizio Kubernetes predefinito nello spazio dei nomi NAMESPACE_NAME:

gcloud config set project PROJECT_ID \
&&
gcloud iam service-accounts create gmp-test-sa \
&&
gcloud iam service-accounts add-iam-policy-binding \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE_NAME/default]" \
  gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
&&
kubectl annotate serviceaccount \
  --namespace NAMESPACE_NAME \
  default \
  iam.gke.io/gcp-service-account=gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com

Se utilizzi uno spazio dei nomi GKE o un account di servizio diverso, modifica i comandi di conseguenza.

Autorizza l'account di servizio

I gruppi di autorizzazioni correlate vengono raccolti in ruoli e concedi i ruoli a un'entità, in questo esempio l'account di servizio Google Cloud. Per ulteriori informazioni sui ruoli di Monitoring, consulta Controllo dell'accesso.

Il comando seguente concede all'account di servizio Google Cloud gmp-test-sa i ruoli dell'API Monitoring necessari per scrivere i dati delle metriche.

Se hai già concesso all'account di servizio Google Cloud un ruolo specifico nell'ambito dell'attività precedente, non è necessario ripeterlo.

gcloud projects add-iam-policy-binding PROJECT_ID\
  --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/monitoring.metricWriter

Esegui il debug della configurazione di Workload Identity

Se hai difficoltà a utilizzare Workload Identity, consulta la documentazione per la verifica della configurazione di Workload Identity e la guida alla risoluzione dei problemi di Workload Identity.

Poiché gli errori di battitura e gli errori di copia-incolla parziali sono le fonti di errore più comuni durante la configurazione di Workload Identity, ti consigliamo vivamente di utilizzare le variabili modificabili e le icone di copia e incolla cliccabili incorporate negli esempi di codice di queste istruzioni.

Workload Identity negli ambienti di produzione

L'esempio descritto in questo documento associa l'account di servizio Google Cloud all'account di servizio Kubernetes predefinito e concede all'account di servizio Google Cloud tutte le autorizzazioni necessarie per utilizzare l'API Monitoring.

In un ambiente di produzione, è consigliabile utilizzare un approccio più granulare, con un account di servizio per ogni componente, ciascuno con autorizzazioni minime. Per maggiori informazioni sulla configurazione degli account di servizio per la gestione delle identità dei carichi di lavoro, consulta Utilizzo di Workload Identity.

Configurare OpenTelemetry Collector

Questa sezione illustra la configurazione e l'utilizzo di OpenTelemetry Collector per eseguire lo scraping dei dati delle metriche da un'applicazione di esempio e inviare i dati a Google Cloud Managed Service per Prometheus. Per informazioni più dettagliate sulla configurazione, consulta le seguenti sezioni:

OpenTelemetry Collector è simile al programma binario dell'agente Managed Service per Prometheus. La community OpenTelemetry pubblica regolarmente release, inclusi codice sorgente, file binari e immagini container.

Puoi eseguire il deployment di questi artefatti su VM o cluster Kubernetes utilizzando le best practice predefinite oppure puoi utilizzare il generatore di collector per creare il tuo raccoglitore composto solo dai componenti necessari. Per creare un raccoglitore da utilizzare con Managed Service per Prometheus, sono necessari i seguenti componenti:

  • L'esportatore di Managed Service per Prometheus, che scrive le metriche in Managed Service per Prometheus.
  • Un ricevitore per eseguire lo scraping dei tuoi dati. Questo documento presuppone che tu stia utilizzando il ricevitore Prometheus OpenTelemetry, ma l'esportatore Managed Service for Prometheus è compatibile con qualsiasi ricevitore di metriche OpenTelemetry.
  • Processori per batch e markup delle metriche in modo da includere identificatori di risorse importanti in base al tuo ambiente.

Questi componenti vengono abilitati utilizzando un file di configurazione che viene passato al raccoglitore con il flag --config.

Le sezioni seguenti spiegano in modo più dettagliato come configurare ciascuno di questi componenti. Questo documento descrive come eseguire il raccoglitore in GKE e in altro luogo.

Configura ed esegui il deployment del raccoglitore

Sia che la raccolta venga eseguita su Google Cloud o in un altro ambiente, puoi comunque configurare OpenTelemetry Collector per l'esportazione in Managed Service per Prometheus. La differenza principale sarà il modo di configurare il raccoglitore. In ambienti non Google Cloud, potrebbe essere necessaria una formattazione aggiuntiva dei dati delle metriche affinché siano compatibili con Managed Service per Prometheus. Su Google Cloud, tuttavia, gran parte di questa formattazione può essere rilevata automaticamente dal raccoglitore.

Esegui il raccoglitore OpenTelemetry su GKE

Puoi copiare la configurazione seguente in un file denominato config.yaml per configurare OpenTelemetry Collector su GKE:

receivers:
  prometheus:
    config:
      scrape_configs:
      - job_name: 'SCRAPE_JOB_NAME'
        kubernetes_sd_configs:
        - role: pod
        relabel_configs:
        - source_labels: [__meta_kubernetes_pod_label_app_kubernetes_io_name]
          action: keep
          regex: prom-example
        - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_path]
          action: replace
          target_label: __metrics_path__
          regex: (.+)
        - source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
          action: replace
          regex: (.+):(?:\d+);(\d+)
          replacement: $1:$2
          target_label: __address__
        - action: labelmap
          regex: __meta_kubernetes_pod_label_(.+)

processors:
  resourcedetection:
    detectors: [gcp]
    timeout: 10s

  transform:
    # "location", "cluster", "namespace", "job", "instance", and "project_id" are reserved, and
    # metrics containing these labels will be rejected.  Prefix them with exported_ to prevent this.
    metric_statements:
    - context: datapoint
      statements:
      - set(attributes["exported_location"], attributes["location"])
      - delete_key(attributes, "location")
      - set(attributes["exported_cluster"], attributes["cluster"])
      - delete_key(attributes, "cluster")
      - set(attributes["exported_namespace"], attributes["namespace"])
      - delete_key(attributes, "namespace")
      - set(attributes["exported_job"], attributes["job"])
      - delete_key(attributes, "job")
      - set(attributes["exported_instance"], attributes["instance"])
      - delete_key(attributes, "instance")
      - set(attributes["exported_project_id"], attributes["project_id"])
      - delete_key(attributes, "project_id")

  batch:
    # batch metrics before sending to reduce API usage
    send_batch_max_size: 200
    send_batch_size: 200
    timeout: 5s

  memory_limiter:
    # drop metrics if memory usage gets too high
    check_interval: 1s
    limit_percentage: 65
    spike_limit_percentage: 20

# Note that the googlemanagedprometheus exporter block is intentionally blank
exporters:
  googlemanagedprometheus:

service:
  pipelines:
    metrics:
      receivers: [prometheus]
      processors: [batch, memory_limiter, resourcedetection, transform]
      exporters: [googlemanagedprometheus]

La configurazione precedente utilizza il ricevitore Prometheus e l'esportatore di Managed Service per Prometheus per eseguire lo scraping degli endpoint delle metriche sui pod Kubernetes ed esportare le metriche in Managed Service per Prometheus. I processori della pipeline formattano e vengono archiviati in batch i dati.

Per ulteriori dettagli sulle operazioni eseguite in ogni parte di questa configurazione, insieme alle configurazioni per piattaforme diverse, consulta le sezioni dettagliate di seguito sull'estrazione delle metriche e sull'aggiunta di processori.

Durante l'esecuzione nei cluster con una configurazione Prometheus esistente, sostituisci i caratteri $ con $$ per evitare di attivare la sostituzione delle variabili di ambiente. Per ulteriori informazioni, consulta l'articolo Eseguire lo scraping delle metriche di Prometheus.

Puoi modificare questa configurazione in base all'ambiente, al provider e alle metriche di cui vuoi eseguire lo scraping, ma la configurazione di esempio è un punto di partenza consigliato per l'esecuzione su GKE.

Esegui OpenTelemetry Collector al di fuori di Google Cloud

L'esecuzione di OpenTelemetry Collector al di fuori di Google Cloud, ad esempio on-premise o su altri cloud provider, è simile all'esecuzione del raccoglitore su GKE. Tuttavia, è meno probabile che le metriche di cui esegui lo scraping includano automaticamente i dati che li formattano al meglio per Managed Service per Prometheus. Pertanto, devi prestare particolare attenzione a configurare il raccoglitore in modo che formatti le metriche in modo che siano compatibili con Managed Service per Prometheus.

Puoi la configurazione seguente in un file denominato config.yaml per configurare OpenTelemetry Collector per il deployment su un cluster Kubernetes non GKE:

receivers:
  prometheus:
    config:
      scrape_configs:
      - job_name: 'SCRAPE_JOB_NAME'
        kubernetes_sd_configs:
        - role: pod
        relabel_configs:
        - source_labels: [__meta_kubernetes_pod_label_app_kubernetes_io_name]
          action: keep
          regex: prom-example
        - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_path]
          action: replace
          target_label: __metrics_path__
          regex: (.+)
        - source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
          action: replace
          regex: (.+):(?:\d+);(\d+)
          replacement: $1:$2
          target_label: __address__
        - action: labelmap
          regex: __meta_kubernetes_pod_label_(.+)

processors:
  resource:
    attributes:
    - key: "cluster"
      value: "CLUSTER_NAME"
      action: upsert
    - key: "namespace"
      value: "NAMESPACE_NAME"
      action: upsert
    - key: "location"
      value: "REGION"
      action: upsert

  transform:
    # "location", "cluster", "namespace", "job", "instance", and "project_id" are reserved, and
    # metrics containing these labels will be rejected.  Prefix them with exported_ to prevent this.
    metric_statements:
    - context: datapoint
      statements:
      - set(attributes["exported_location"], attributes["location"])
      - delete_key(attributes, "location")
      - set(attributes["exported_cluster"], attributes["cluster"])
      - delete_key(attributes, "cluster")
      - set(attributes["exported_namespace"], attributes["namespace"])
      - delete_key(attributes, "namespace")
      - set(attributes["exported_job"], attributes["job"])
      - delete_key(attributes, "job")
      - set(attributes["exported_instance"], attributes["instance"])
      - delete_key(attributes, "instance")
      - set(attributes["exported_project_id"], attributes["project_id"])
      - delete_key(attributes, "project_id")

  batch:
    # batch metrics before sending to reduce API usage
    send_batch_max_size: 200
    send_batch_size: 200
    timeout: 5s

  memory_limiter:
    # drop metrics if memory usage gets too high
    check_interval: 1s
    limit_percentage: 65
    spike_limit_percentage: 20

exporters:
  googlemanagedprometheus:
    project: "PROJECT_ID"

service:
  pipelines:
    metrics:
      receivers: [prometheus]
      processors: [batch, memory_limiter, resource, transform]
      exporters: [googlemanagedprometheus]

Questa configurazione svolge le seguenti operazioni:

Durante l'esecuzione nei cluster con una configurazione Prometheus esistente, sostituisci i caratteri $ con $$ per evitare di attivare la sostituzione delle variabili di ambiente. Per ulteriori informazioni, consulta l'articolo Eseguire lo scraping delle metriche di Prometheus.

Per informazioni sulle best practice per la configurazione del raccoglitore su altri cloud, consulta Amazon EKS o Azure AKS.

Esegui il deployment dell'applicazione di esempio

L'applicazione di esempio emette la metrica del contatore example_requests_total e la metrica dell'istogramma example_random_numbers (tra le altre) sulla porta metrics. Il manifest per questo esempio definisce tre repliche.

Per eseguire il deployment dell'applicazione di esempio, esegui questo comando:

kubectl -n NAMESPACE_NAME apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.8.2/examples/example-app.yaml

Crea la configurazione del raccoglitore come ConfigMap

Dopo aver creato la configurazione e averla inserita in un file denominato config.yaml, utilizza questo file per creare un ConfigMap Kubernetes basato sul tuo file config.yaml. Una volta eseguito il deployment del raccoglitore, monta il ConfigMap e carica il file.

Per creare un ConfigMap denominato otel-config con la tua configurazione, utilizza il seguente comando:

kubectl -n NAMESPACE_NAME create configmap otel-config --from-file config.yaml

esegui il deployment del raccoglitore

Crea un file intitolato collector-deployment.yaml con i seguenti contenuti:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: NAMESPACE_NAME:prometheus-test
rules:
- apiGroups: [""]
  resources:
  - pods
  verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: NAMESPACE_NAME:prometheus-test
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: NAMESPACE_NAME:prometheus-test
subjects:
- kind: ServiceAccount
  namespace: NAMESPACE_NAME
  name: default
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: otel-collector
spec:
  replicas: 1
  selector:
    matchLabels:
      app: otel-collector
  template:
    metadata:
      labels:
        app: otel-collector
    spec:
      containers:
      - name: otel-collector
        image: otel/opentelemetry-collector-contrib:0.92.0
        args:
        - --config
        - /etc/otel/config.yaml
        volumeMounts:
        - mountPath: /etc/otel/
          name: otel-config
      volumes:
      - name: otel-config
        configMap:
          name: otel-config

Crea il deployment del raccoglitore nel tuo cluster Kubernetes eseguendo questo comando:

kubectl -n NAMESPACE_NAME create -f collector-deployment.yaml

Dopo l'avvio del pod, esegue lo scraping dei dati dell'applicazione di esempio e segnala le metriche a Managed Service per Prometheus.

Per informazioni su come eseguire query sui dati, consulta Eseguire query utilizzando Cloud Monitoring o Eseguire query con Grafana.

Fornisci le credenziali in modo esplicito

Durante l'esecuzione su GKE, OpenTelemetry Collector recupera automaticamente le credenziali dall'ambiente in base all'account di servizio del nodo. Nei cluster Kubernetes non GKE, le credenziali devono essere fornite esplicitamente a OpenTelemetry Collector utilizzando i flag o la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS.

  1. Imposta il contesto per il progetto di destinazione:

    gcloud config set project PROJECT_ID

  2. Crea un account di servizio:

    gcloud iam service-accounts create gmp-test-sa

    Questo passaggio crea l'account di servizio che potresti aver già creato nelle istruzioni di Workload Identity.

  3. Concedi le autorizzazioni richieste all'account di servizio:

    gcloud projects add-iam-policy-binding PROJECT_ID\
  --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/monitoring.metricWriter

  4. Crea e scarica una chiave per l'account di servizio:

    gcloud iam service-accounts keys create gmp-test-sa-key.json \
  --iam-account=gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com

  5. Aggiungi il file della chiave come secret al cluster non GKE:

    kubectl -n NAMESPACE_NAME create secret generic gmp-test-sa \
  --from-file=key.json=gmp-test-sa-key.json

  6. Apri la risorsa Deployment OpenTelemetry per la modifica:

    kubectl -n NAMESPACE_NAME edit deployment otel-collector

  1. Aggiungi il testo mostrato in grassetto alla risorsa:

    apiVersion: apps/v1
kind: Deployment
metadata:
  namespace: NAMESPACE_NAME
  name: otel-collector
spec:
  template
    spec:
      containers:
      - name: otel-collector
        env:
        - name: "GOOGLE_APPLICATION_CREDENTIALS"
          value: "/gmp/key.json"
...
        volumeMounts:
        - name: gmp-sa
          mountPath: /gmp
          readOnly: true
...
      volumes:
      - name: gmp-sa
        secret:
          secretName: gmp-test-sa
...

  2. Salva il file e chiudi l'editor. Dopo l'applicazione della modifica, i pod vengono ricreati e iniziano l'autenticazione nel backend della metrica con l'account di servizio specificato.

Esegui lo scraping delle metriche di Prometheus

Questa sezione e la sezione successiva forniscono ulteriori informazioni sulla personalizzazione per l'utilizzo di OpenTelemetry Collector. Queste informazioni potrebbero essere utili in determinate situazioni, ma non sono necessarie per eseguire l'esempio descritto in Configurare OpenTelemetry Collector.

Se le tue applicazioni espongono già gli endpoint Prometheus, OpenTelemetry Collector può eseguire il scraping di questi endpoint utilizzando lo stesso formato di configurazione di scraping che useresti con qualsiasi configurazione di Prometheus standard. Per farlo, abilita il ricevitore Prometheus nella configurazione del raccoglitore.

Una semplice configurazione di ricevitore Prometheus per i pod Kubernetes potrebbe avere il seguente aspetto:

receivers:
  prometheus:
    config:
      scrape_configs:
      - job_name: 'kubernetes-pods'
        kubernetes_sd_configs:
        - role: pod
        relabel_configs:
        - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape]
          action: keep
          regex: true
        - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_path]
          action: replace
          target_label: __metrics_path__
          regex: (.+)
        - source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
          action: replace
          regex: (.+):(?:\d+);(\d+)
          replacement: $1:$2
          target_label: __address__
        - action: labelmap
          regex: __meta_kubernetes_pod_label_(.+)

service:
  pipelines:
    metrics:
      receivers: [prometheus]

Questa è una semplice configurazione di scrape basata sul Service Discovery, che puoi modificare in base alle esigenze per eseguire lo scraping delle tue applicazioni.

Durante l'esecuzione nei cluster con una configurazione Prometheus esistente, sostituisci i caratteri $ con $$ per evitare di attivare la sostituzione delle variabili di ambiente. Questo è particolarmente importante per il valore replacement all'interno della sezione relabel_configs. Ad esempio, se è presente la seguente sezione relabel_config:

- source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
  action: replace
  regex: (.+):(?:\d+);(\d+)
  replacement: $1:$2
  target_label: __address__

Quindi riscrivilo in questo modo:

- source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
  action: replace
  regex: (.+):(?:\d+);(\d+)
  replacement: $$1:$$2
  target_label: __address__

Per ulteriori informazioni, consulta la documentazione di OpenTelemetry.

Ti consigliamo vivamente di utilizzare i processori per formattare le metriche. In molti casi, i processori devono essere utilizzati per formattare correttamente le metriche.

Aggiungi processori

I processori OpenTelemetry modificano i dati di telemetria prima che vengano esportati. Puoi utilizzare i processori riportati di seguito per assicurarti che le metriche siano scritte in un formato compatibile con Managed Service per Prometheus.

Rileva attributi delle risorse

L'esportatore Managed Service per Prometheus per OpenTelemetry utilizza la risorsa monitorata prometheus_target per identificare in modo univoco i punti dati delle serie temporali. L'esportatore analizza i campi "monitored-resource" obbligatori degli attributi delle risorse nei punti dati della metrica. I campi e gli attributi da cui i valori vengono estratti sono:

  • project_id: rilevato automaticamente da Credenziali predefinite dell'applicazione, gcp.project.id o project nella configurazione dell'esportatore (consulta la configurazione dell'esportatore)
  • località: location, cloud.availability_zone, cloud.region
  • cluster: cluster, k8s.cluster_name
  • spazio dei nomi: namespace, k8s.namespace_name
  • job: service.name + service.namespace
  • istanza: service.instance.id

Se queste etichette non vengono impostate su valori univoci, possono verificarsi errori di "serie temporali duplicate" durante l'esportazione in Managed Service per Prometheus.

Il ricevitore Prometheus imposta automaticamente l'attributo service.name in base al job_name nella configurazione dello scrape e l'attributo service.instance.id in base al valore instance della destinazione dello scrape. Il ricevitore imposta anche k8s.namespace.name quando viene utilizzato role: pod nella configurazione dello scrape.

Ti consigliamo di completare gli altri attributi automaticamente utilizzando il processore di rilevamento delle risorse. Tuttavia, a seconda dell'ambiente, alcuni attributi potrebbero non essere rilevabili automaticamente. In questo caso, puoi utilizzare altri processori per inserire manualmente questi valori o analizzarli dalle etichette delle metriche. Le seguenti sezioni illustrano le configurazioni per l'esecuzione di questa elaborazione su varie piattaforme.

GKE

Quando esegui OpenTelemetry su GKE, devi solo abilitare il processore di rilevamento delle risorse per compilare le etichette delle risorse. Assicurati che le metriche non contengano già alcuna delle etichette delle risorse riservate. Se questo è inevitabile, consulta la sezione Evitare conflitti tra attributi delle risorse rinominando gli attributi.

processors:
  resourcedetection:
    detectors: [gcp]
    timeout: 10s

Questa sezione può essere copiata direttamente nel file di configurazione, sostituendo la sezione processors, se esistente.

Amazon EKS

Il rilevatore di risorse EKS non compila automaticamente gli attributi cluster o namespace. Puoi fornire questi valori manualmente utilizzando il processore di risorse, come mostrato nell'esempio seguente:

processors:
  resourcedetection:
    detectors: [eks]
    timeout: 10s

  resource:
    attributes:
    - key: "cluster"
      value: "my-eks-cluster"
      action: upsert
    - key: "namespace"
      value: "my-app"
      action: upsert

Puoi anche convertire questi valori dalle etichette delle metriche utilizzando il processore groupbyattrs (consulta la sezione Spostare le etichette delle metriche nelle etichette delle risorse di seguito).

Azure AKS

Il rilevatore di risorse AKS non compila automaticamente gli attributi cluster o namespace. Puoi fornire questi valori manualmente utilizzando il processore di risorse, come mostrato nell'esempio seguente:

processors:
  resourcedetection:
    detectors: [aks]
    timeout: 10s

  resource:
    attributes:
    - key: "cluster"
      value: "my-eks-cluster"
      action: upsert
    - key: "namespace"
      value: "my-app"
      action: upsert

Puoi anche convertire questi valori dalle etichette delle metriche utilizzando il processore groupbyattrs. Consulta Spostare le etichette delle metriche nelle etichette delle risorse.

Ambienti on-premise e non cloud

Con gli ambienti on-premise o non cloud, probabilmente non riesci a rilevare automaticamente nessuno degli attributi delle risorse necessari. In questo caso, puoi emettere queste etichette nelle metriche e spostarle negli attributi delle risorse (consulta Spostare le etichette delle metriche nelle etichette delle risorse) oppure impostare manualmente tutti gli attributi delle risorse come mostrato nell'esempio seguente:

processors:
  resource:
    attributes:
    - key: "cluster"
      value: "my-on-prem-cluster"
      action: upsert
    - key: "namespace"
      value: "my-app"
      action: upsert
    - key: "location"
      value: "us-east-1"
      action: upsert

Crea la configurazione del raccoglitore come ConfigMap. Descrive come utilizzare la configurazione. Questa sezione presuppone che tu abbia inserito la configurazione in un file denominato config.yaml.

L'attributo della risorsa project_id può comunque essere impostato automaticamente quando si esegue il raccoglitore con le Credenziali predefinite dell'applicazione. Se il raccoglitore non ha accesso alle Credenziali predefinite dell'applicazione, consulta Impostazione project_id.

In alternativa, puoi impostare manualmente gli attributi delle risorse necessari in una variabile di ambiente, OTEL_RESOURCE_ATTRIBUTES, con un elenco separato da virgole di coppie chiave/valore, ad esempio:

export OTEL_RESOURCE_ATTRIBUTES="cluster=my-cluster,namespace=my-app,location=us-east-1"

Quindi utilizza il processore del rilevatore di risorse env per impostare gli attributi delle risorse:

processors:
  resourcedetection:
    detectors: [env]

Evitare conflitti tra gli attributi delle risorse rinominando gli attributi

Se le tue metriche contengono già etichette in conflitto con gli attributi delle risorse richiesti (come location, cluster o namespace), rinominale per evitare la sovrapposizione. La convenzione di Prometheus prevede l'aggiunta del prefisso exported_ al nome dell'etichetta. Per aggiungere questo prefisso, utilizza il processore transform.

La seguente configurazione processors rinomina qualsiasi potenziale conflitto e risolve eventuali chiavi in conflitto dalla metrica:

processors:
  transform:
    # "location", "cluster", "namespace", "job", "instance", and "project_id" are reserved, and
    # metrics containing these labels will be rejected.  Prefix them with exported_ to prevent this.
    metric_statements:
    - context: datapoint
      statements:
      - set(attributes["exported_location"], attributes["location"])
      - delete_key(attributes, "location")
      - set(attributes["exported_cluster"], attributes["cluster"])
      - delete_key(attributes, "cluster")
      - set(attributes["exported_namespace"], attributes["namespace"])
      - delete_key(attributes, "namespace")
      - set(attributes["exported_job"], attributes["job"])
      - delete_key(attributes, "job")
      - set(attributes["exported_instance"], attributes["instance"])
      - delete_key(attributes, "instance")
      - set(attributes["exported_project_id"], attributes["project_id"])
      - delete_key(attributes, "project_id")

Sposta le etichette delle metriche nelle etichette delle risorse

In alcuni casi, le metriche potrebbero segnalare intenzionalmente etichette come namespace perché l'esportatore sta monitorando più spazi dei nomi. Ad esempio, durante l'esecuzione dell'utilità di esportazione kube-state-metrics.

In questo scenario, queste etichette possono essere spostate negli attributi delle risorse utilizzando il processore groupbyattrs:

processors:
  groupbyattrs:
    keys:
    - namespace
    - cluster
    - location

Nell'esempio precedente, data una metrica con le etichette namespace, cluster e/o location, queste etichette verranno convertite negli attributi della risorsa corrispondenti.

Limita le richieste API e l'utilizzo della memoria

Altri due processori, il processore batch e il processore limitatore di memoria, consentono di limitare il consumo di risorse da parte del raccoglitore.

Elaborazione batch

Le richieste in batch consentono di definire il numero di punti dati da inviare in una singola richiesta. Tieni presente che Cloud Monitoring ha un limite di 200 serie temporali per richiesta. Abilita l'elaborazione batch utilizzando le seguenti impostazioni:

processors:
  batch:
    # batch metrics before sending to reduce API usage
    send_batch_max_size: 200
    send_batch_size: 200
    timeout: 5s

Limitazione di memoria

Consigliamo di abilitare il processore del limitatore di memoria per evitare l'arresto anomalo del raccoglitore in momenti di velocità effettiva elevata. Abilita l'elaborazione utilizzando le seguenti impostazioni:

processors:
  memory_limiter:
    # drop metrics if memory usage gets too high
    check_interval: 1s
    limit_percentage: 65
    spike_limit_percentage: 20

Configura l'esportatore googlemanagedprometheus

Per impostazione predefinita, l'utilizzo dell'utilità di esportazione googlemanagedprometheus su GKE non richiede alcuna configurazione aggiuntiva. Per molti casi d'uso, è sufficiente abilitarlo con un blocco vuoto nella sezione exporters:

exporters:
  googlemanagedprometheus:

Tuttavia, l'esportatore fornisce alcune impostazioni di configurazione facoltative. Le seguenti sezioni descrivono le altre impostazioni di configurazione.

Impostazione project_id

Per associare la serie temporale a un progetto Google Cloud, la risorsa monitorata prometheus_target deve avere impostato project_id.

Quando esegui OpenTelemetry su Google Cloud, per impostazione predefinita l'esportatore Managed Service per Prometheus imposta questo valore in base alle Credenziali predefinite dell'applicazione che trova. Se non sono disponibili credenziali o se vuoi eseguire l'override del progetto predefinito, hai due opzioni:

  • Imposta project nella configurazione dell'esportatore
  • Aggiungi un attributo risorsa gcp.project.id alle tue metriche.

Ti consigliamo vivamente di utilizzare il valore predefinito (non impostato) per project_id, anziché impostarlo esplicitamente, quando possibile.

Imposta project nella configurazione dell'esportatore

Il seguente estratto di configurazione invia le metriche a Managed Service per Prometheus nel progetto Google Cloud MY_PROJECT:

receivers:
  prometheus:
    config:
    ...

processors:
  resourcedetection:
    detectors: [gcp]
    timeout: 10s

exporters:
  googlemanagedprometheus:
    project: MY_PROJECT

service:
  pipelines:
    metrics:
      receivers: [prometheus]
      processors: [resourcedetection]
      exporters: [googlemanagedprometheus]

L'unica modifica rispetto agli esempi precedenti è la nuova riga project: MY_PROJECT. Questa impostazione è utile se sai che ogni metrica proveniente da questo raccoglitore deve essere inviata a MY_PROJECT.

Imposta attributo della risorsa gcp.project.id

Puoi impostare l'associazione del progetto in base alle metriche aggiungendo un attributo della risorsa gcp.project.id alle tue metriche. Imposta il valore dell'attributo sul nome del progetto a cui deve essere associata la metrica.

Ad esempio, se la metrica ha già un'etichetta project, questa etichetta può essere spostata in un attributo della risorsa e rinominata in gcp.project.id utilizzando i processori nella configurazione del raccoglitore, come mostrato nell'esempio seguente:

receivers:
  prometheus:
    config:
    ...

processors:
  resourcedetection:
    detectors: [gcp]
    timeout: 10s

  groupbyattrs:
    keys:
    - project

  resource:
    attributes:
    - key: "gcp.project.id"
      from_attribute: "project"
      action: upsert

exporters:
  googlemanagedprometheus:

service:
  pipelines:
    metrics:
      receivers: [prometheus]
      processors: [resourcedetection, groupbyattrs, resource]
      exporters: [googlemanagedprometheus]

Impostazione delle opzioni client

L'esportatore googlemanagedprometheus utilizza client gRPC per Managed Service per Prometheus. Di conseguenza, sono disponibili impostazioni facoltative per la configurazione del client gRPC:

  • compression: abilita la compressione gzip per le richieste gRPC, utile per ridurre le tariffe per il trasferimento di dati quando si inviano dati da altri cloud a Managed Service per Prometheus (valori validi: gzip).
  • user_agent: esegue l'override della stringa user agent inviata nelle richieste a Cloud Monitoring; si applica solo alle metriche. Il valore predefinito è la build e il numero di versione di OpenTelemetry Collector, ad esempio opentelemetry-collector-contrib 0.92.0.
  • endpoint: imposta l'endpoint a cui verranno inviati i dati delle metriche.
  • use_insecure: se il valore è true, viene utilizzato gRPC come trasporto della comunicazione. Ha un effetto solo quando il valore endpoint non è "".
  • grpc_pool_size: imposta le dimensioni del pool di connessioni nel client gRPC.
  • prefix: configura il prefisso delle metriche inviate a Managed Service per Prometheus. Il valore predefinito è prometheus.googleapis.com. Non modificare questo prefisso. In questo caso, non sarà possibile eseguire query sulle metriche con PromQL nell'interfaccia utente di Cloud Monitoring.

Nella maggior parte dei casi, non è necessario modificare questi valori rispetto ai valori predefiniti. Tuttavia, puoi cambiarle per adattarle a circostanze speciali.

Tutte queste impostazioni sono configurate in un blocco metric nella sezione dell'esportatore googlemanagedprometheus, come mostrato nell'esempio seguente:

receivers:
  prometheus:
    config:
    ...

processors:
  resourcedetection:
    detectors: [gcp]
    timeout: 10s

exporters:
  googlemanagedprometheus:
    metric:
      compression: gzip
      user_agent: opentelemetry-collector-contrib 0.92.0
      endpoint: ""
      use_insecure: false
      grpc_pool_size: 1
      prefix: prometheus.googleapis.com

service:
  pipelines:
    metrics:
      receivers: [prometheus]
      processors: [resourcedetection]
      exporters: [googlemanagedprometheus]

Passaggi successivi