Esegui il deployment del collector OpenTelemetry creato da Google su Google Kubernetes Engine

Questo documento descrive come eseguire OpenTelemetry Collector creato da Google su Google Kubernetes Engine per raccogliere log, metriche e tracce OTLP dalle applicazioni instrumentate ed esportare i dati in Google Cloud.

Prima di iniziare

L'esecuzione del raccoglitore OpenTelemetry creato da Google richiede le seguenti risorse:

  • Un progetto Google Cloud con le API Cloud Monitoring, Cloud Trace e Cloud Logging abilitate.

    • Se non hai un progetto Google Cloud, segui questi passaggi:

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

        Creare un nuovo progetto

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

      3. Vai a Fatturazione:

        Vai a Fatturazione

      4. Seleziona il progetto appena creato se non è già selezionato nella parte superiore della pagina.

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

      L'API Monitoring, l'API Trace e l'API Logging sono abilitate per impostazione predefinita per i nuovi progetti.

    • Se hai già un progetto Google Cloud, assicurati che le API Monitoring, Trace e Logging siano abilitate:

      Enable the APIs

  • Un cluster Kubernetes. Se non hai un cluster Kubernetes, segui le istruzioni riportate nella guida rapida per GKE.

  • I seguenti strumenti a riga di comando:

    • gcloud
    • kubectl

    Gli strumenti gcloud e kubectl fanno parte dell'interfaccia a riga di comando Google Cloud. Per informazioni sull'installazione, consulta Gestire i componenti dell'interfaccia a riga di comando Google Cloud. Per visualizzare i componenti dell'interfaccia a riga di comando gcloud che hai installato, esegui questo comando:

    gcloud components list

Configura le autorizzazioni per il raccoglitore

Se hai disattivato l'identità per i carichi di lavoro di GKE, puoi saltare questa sezione.

Per assicurarti che l'account di servizio Kubernetes di OpenTelemetry Collector disponga delle autorizzazioni necessarie per esportare la telemetria, chiedi all'amministratore di concedere all'account di servizio Kubernetes di OpenTelemetry Collector i seguenti ruoli IAM nel tuo progetto:

Per ulteriori informazioni sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

L'amministratore potrebbe anche essere in grado di assegnare all'account di servizio Kubernetes di OpenTelemetry Collector le autorizzazioni richieste tramite ruoli personalizzati o altri ruoli predefiniti.

Per configurare le autorizzazioni, utilizza i seguenti comandi add-iam-policy-binding:

gcloud projects add-iam-policy-binding projects/PROJECT_ID \
    --role=roles/logging.logWriter \
    --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector
gcloud projects add-iam-policy-binding projects/PROJECT_ID \
    --role=roles/monitoring.metricWriter \
    --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector
gcloud projects add-iam-policy-binding projects/PROJECT_ID \
    --role=roles/cloudtrace.agent \
    --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector

Prima di eseguire i comandi, sostituisci le seguenti variabili:

  • PROJECT_ID: l'identificatore del progetto.
  • PROJECT_NUMBER: il numero del progetto Google Cloud.

Esegui il deployment del raccoglitore

La pipeline del Collector può essere implementata direttamente dagli esempi esaminati forniti dal repo di importazione di Kubernetes OTLP autonomo. Puoi eseguire il deployment direttamente da GitHub con i seguenti comandi dopo aver sostituito PROJECT_ID con l'ID del tuo progetto: Google Cloud 

export GCLOUD_PROJECT=PROJECT_ID
kubectl kustomize https://github.com/GoogleCloudPlatform/otlp-k8s-ingest.git/k8s/base | envsubst | kubectl apply -f -

Prima di eseguire i comandi, sostituisci la seguente variabile:

  • PROJECT_ID: l'identificatore del progetto.

Configura il raccoglitore

Forniamo una configurazione di OpenTelemetry Collector da utilizzare con il Collector creato da Google. Questa configurazione è progettata per generare elevati volumi di metriche, log e tracce OTLP con metadati GKE e Kubernetes coerenti allegati. Questa configurazione è progettata anche per evitare i problemi comuni di importazione. Puoi aggiungere elementi alla configurazione, ma ti consigliamo vivamente di non rimuovere elementi.

Questa sezione descrive la configurazione fornita, i componenti chiave come esportatori, elaboratori, ricevitori e altri componenti disponibili.

Configurazione del raccoglitore fornita

Puoi trovare la configurazione del raccoglitore per gli ambienti Kubernetes nel repository otlp-k8s-ingest:

# Copyright 2024 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

exporters:
  googlecloud:
    log:
      default_log_name: opentelemetry-collector
    user_agent: Google-Cloud-OTLP manifests:0.2.0 OpenTelemetry Collector Built By Google/0.121.0 (linux/amd64)
  googlemanagedprometheus:
    user_agent: Google-Cloud-OTLP manifests:0.2.0 OpenTelemetry Collector Built By Google/0.121.0 (linux/amd64)

extensions:
  health_check:
    endpoint: ${env:MY_POD_IP}:13133
processors:
  filter/self-metrics:
    metrics:
      include:
        match_type: strict
        metric_names:
        - otelcol_process_uptime
        - otelcol_process_memory_rss
        - otelcol_grpc_io_client_completed_rpcs
        - otelcol_googlecloudmonitoring_point_count
  batch:
    send_batch_max_size: 200
    send_batch_size: 200
    timeout: 5s

  k8sattributes:
    extract:
      metadata:
      - k8s.namespace.name
      - k8s.deployment.name
      - k8s.statefulset.name
      - k8s.daemonset.name
      - k8s.cronjob.name
      - k8s.job.name
      - k8s.replicaset.name
      - k8s.node.name
      - k8s.pod.name
      - k8s.pod.uid
      - k8s.pod.start_time
    passthrough: false
    pod_association:
    - sources:
      - from: resource_attribute
        name: k8s.pod.ip
    - sources:
      - from: resource_attribute
        name: k8s.pod.uid
    - sources:
      - from: connection
  memory_limiter:
    check_interval: 1s
    limit_percentage: 65
    spike_limit_percentage: 20

  metricstransform/self-metrics:
    transforms:
    - action: update
      include: otelcol_process_uptime
      operations:
      - action: add_label
        new_label: version
        new_value: Google-Cloud-OTLP manifests:0.2.0 OpenTelemetry Collector Built By Google/0.121.0 (linux/amd64)

  resourcedetection:
    detectors: [gcp]
    timeout: 10s

  transform/collision:
    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")

  # The relative ordering of statements between ReplicaSet & Deployment and Job & CronJob are important.
  # The ordering of these controllers is decided based on the k8s controller documentation available at
  # https://kubernetes.io/docs/concepts/workloads/controllers.
  # The relative ordering of the other controllers in this list is inconsequential since they directly
  # create pods.
  transform/aco-gke:
    metric_statements:
    - context: datapoint
      statements:
      - set(attributes["top_level_controller_type"], "ReplicaSet") where resource.attributes["k8s.replicaset.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.replicaset.name"]) where resource.attributes["k8s.replicaset.name"] != nil
      - set(attributes["top_level_controller_type"], "Deployment") where resource.attributes["k8s.deployment.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.deployment.name"]) where resource.attributes["k8s.deployment.name"] != nil
      - set(attributes["top_level_controller_type"], "DaemonSet") where resource.attributes["k8s.daemonset.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.daemonset.name"]) where resource.attributes["k8s.daemonset.name"] != nil
      - set(attributes["top_level_controller_type"], "StatefulSet") where resource.attributes["k8s.statefulset.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.statefulset.name"]) where resource.attributes["k8s.statefulset.name"] != nil
      - set(attributes["top_level_controller_type"], "Job") where resource.attributes["k8s.job.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.job.name"]) where resource.attributes["k8s.job.name"] != nil
      - set(attributes["top_level_controller_type"], "CronJob") where resource.attributes["k8s.cronjob.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.cronjob.name"]) where resource.attributes["k8s.cronjob.name"] != nil

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: ${env:MY_POD_IP}:4317
      http:
        cors:
          allowed_origins:
          - http://*
          - https://*
        endpoint: ${env:MY_POD_IP}:4318
  otlp/self-metrics:
    protocols:
      grpc:
        endpoint: ${env:MY_POD_IP}:14317

service:
  extensions:
  - health_check
  pipelines:
    logs:
      exporters:
      - googlecloud
      processors:
      - k8sattributes
      - resourcedetection
      - memory_limiter
      - batch
      receivers:
      - otlp
    metrics/otlp:
      exporters:
      - googlemanagedprometheus
      processors:
      - k8sattributes
      - memory_limiter
      - resourcedetection
      - transform/collision
      - transform/aco-gke
      - batch
      receivers:
      - otlp
    metrics/self-metrics:
      exporters:
      - googlemanagedprometheus
      processors:
      - filter/self-metrics
      - metricstransform/self-metrics
      - k8sattributes
      - memory_limiter
      - resourcedetection
      - batch
      receivers:
      - otlp/self-metrics
    traces:
      exporters:
      - googlecloud
      processors:
      - k8sattributes
      - memory_limiter
      - resourcedetection
      - batch
      receivers:
      - otlp
  telemetry:
    logs:
      encoding: json
    metrics:
      readers:
      - periodic:
          exporter:
            otlp:
              protocol: grpc
              endpoint: ${env:MY_POD_IP}:14317

Esportatori

La configurazione del raccoglitore include i seguenti esportatori:

  • googlecloud esportatore per log e tracce. Questo esportatore è configurato con un nome log predefinito.

  • Esportatore googlemanagedprometheus per le metriche. Questo esportatore non richiede alcuna configurazione, ma sono disponibili opzioni di configurazione. Per informazioni sulle opzioni di configurazione per l'esportatore googlemanagedprometheus, consulta Introduzione a OpenTelemetry Collector nella documentazione di Google Cloud Managed Service per Prometheus.

Processori

La configurazione del Collector include i seguenti processori:

  • batch: configurato per raggruppare le richieste di telemetria in base al Google Cloud numero massimo di voci per richiesta o all' Google Cloud intervallo minimo di ogni 5 secondi (a seconda del caso).

  • memory_limiter: limita l'utilizzo della memoria del Collector per evitare arresti anomali dovuti a esaurimento della memoria eliminando i punti dati quando viene superato il limite.

  • resourcedetection: rileva automaticamente Google Cloud le etichette delle risorse, ad esempio project_id e cluster_name.

  • k8sattributes: mappa automaticamente gli attributi delle risorse Kubernetes alle etichette di telemetria.

  • transform: rinomina le etichette delle metriche in conflitto con le etichette delle Google Cloud risorse monitorate.

Ricevitori

La configurazione del Collector include solo il otlp ricevente. Per informazioni sulla strumentazione delle applicazioni per inviare tracce e metriche OTLP all'endpoint OTLP del Collector, consulta Scegliere un approccio di strumentazione.

Componenti disponibili

OpenTelemetry Collector creato da Google contiene i componenti di cui la maggior parte degli utenti avrà bisogno per attivare un'esperienza completa in Google Cloud Observability. Per un elenco completo dei componenti disponibili, consulta Componenti nel repository opentelemetry-operations-collector.

Per richiedere modifiche o aggiunte ai componenti disponibili, apri una richiesta di funzionalità. nel repository opentelemetry-operations-collector.

Generare dati di telemetria

Questa sezione descrive come eseguire il deployment di un'applicazione di esempio, indirizzarla all'endpoint OTLP del Collector e visualizzare la telemetria inGoogle Cloud. L'applicazione di esempio è un piccolo generatore che esporta tracce, log e metriche nel Collector.

Se hai già un'applicazione instrumentata con un SDK OpenTelemetry, puoi indirizzarla all'endpoint del Collector.

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

kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/otlp-k8s-ingest/main/sample/app.yaml

Per indirizzare le applicazioni esistenti che utilizzano l'SDK OpenTelemetry all'endpoint del Collector, imposta la variabile di ambiente OTEL_EXPORTER_OTLP_ENDPOINT su http://opentelemetry-collector.opentelemetry.svc.cluster.local:4317.

Dopo alcuni minuti, la telemetria generata dall'applicazione inizia a essere inviata tramite il Collector alla Google Cloud console per ogni indicatore.

Visualizza la telemetria

OpenTelemetry Collector, creato da Google, invia metriche, log e tracce dalle applicazioni instrumentate a Google Cloud Observability. Il Collector invia anche le metriche di auto-osservabilità. Le sezioni seguenti descrivono come visualizzare questa telemetria.

Visualizzare le metriche

OpenTelemetry Collector, creato da Google, raccoglie le metriche di Prometheus che puoi visualizzare utilizzando Metrics Explorer. Le metriche raccolte dipendono dalla misurazione dell'app, anche se il Collector creato da Google scrive anche alcune metriche proprie.

Per visualizzare le metriche raccolte dal Collector OpenTelemetry creato da Google, segui questi passaggi:

  1. Nella console Google Cloud, vai alla pagina  Esplora metriche:

    Vai a Esplora metriche

    Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Monitoring.

  2. Nella barra degli strumenti della console Google Cloud, seleziona il tuo progetto Google Cloud. Per le configurazioni di App Hub, seleziona il progetto host di App Hub o il progetto di gestione della cartella abilitata per le app.
  3. Nell'elemento Metrica, espandi il menu Seleziona una metrica, digita Prometheus Target nella barra dei filtri e poi utilizza i sottomenu per selezionare un tipo di risorsa e una metrica specifici:
    1. Nel menu Risorse attive, seleziona Destinazione Prometheus.
    2. Per selezionare una metrica, utilizza i menu Categorie di metriche attive e Metriche attive. Le metriche raccolte da OpenTelemetry Collector creato da Google hanno il prefisso prometheus.googleapis.com.
    3. Fai clic su Applica.
  4. Configura la visualizzazione dei dati.

    Quando le misurazioni di una metrica sono cumulative, Metrics Explorer normalizza automaticamente i dati misurati in base al periodo di allineamento, in modo che il grafico mostri una percentuale. Per maggiori informazioni, consulta Tipi, conversioni e tipi.

    Quando vengono misurati valori interi o doppi, ad esempio con le metriche counter, Metrics Explorer somma automaticamente tutte le serie temporali. Per modificare questo comportamento, imposta il primo menu della voce Aggregazione su Nessuna.

    Per ulteriori informazioni sulla configurazione di un grafico, consulta Selezionare le metriche durante l'utilizzo di Metrics Explorer.

Visualizzare le tracce

Per visualizzare i dati di traccia:

  1. Nella console Google Cloud, vai alla pagina Esplora tracce.

    Vai a Trace Explorer

    Puoi trovare questa pagina anche utilizzando la barra di ricerca.

  2. Nella barra degli strumenti della console Google Cloud, seleziona il tuo progetto Google Cloud. Per le configurazioni di App Hub, seleziona il progetto host di App Hub o il progetto di gestione della cartella abilitata per le app.
  3. Nella sezione della tabella della pagina, seleziona una riga.

  4. Nel grafico di Gantt nel riquadro Dettagli su Trace, seleziona un intervallo.

    Viene visualizzato un riquadro che mostra le informazioni sulla richiesta tracciata. Questi dettagli includono il metodo, il codice di stato, il numero di byte e l'agente utente del chiamante.

  5. Per visualizzare i log associati a questa traccia, seleziona la scheda Log ed eventi.

    La scheda mostra i singoli log. Per visualizzare i dettagli della voce di log, espandila. Puoi anche fare clic su Visualizza log e visualizzare il log utilizzando Esplora log.

Per ulteriori informazioni sull'utilizzo di Esplora tracce di Cloud, consulta Trovare ed esplorare le tracce.

Visualizza i log

In Esplora log puoi ispezionare i log e anche visualizzare le tracce associate, se esistono.

  1. Nella console Google Cloud, vai alla pagina Esplora log:

    Vai a Esplora log

    Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Logging.

  2. Individua una voce di log della tua app sottoposta a strumenti. Per visualizzare i dettagli, espandi la voce di log.

  3. Fai clic su Tracce in una voce di log con un messaggio di traccia e poi seleziona Visualizza dettagli traccia.

    Si apre un riquadro Dettagli su Trace che mostra la traccia selezionata.

Per ulteriori informazioni sull'utilizzo di Esplora log, consulta Visualizza i log utilizzando Esplora log.

Monitora ed esegui il debug del raccoglitore

OpenTelemetry Collector, creato da Google, fornisce automaticamente metriche di auto-osservabilità per aiutarti a monitorarne le prestazioni e garantire il tempo di attività continuo della pipeline di importazione OTLP.

Per monitorare il raccoglitore, installa la dashboard di esempio per il raccoglitore. Questa dashboard offre informazioni rapide su diverse metriche del Collector, tra cui uptime, utilizzo della memoria e chiamate API a Google Cloud Observability.

Per installare la dashboard:

  1. Nella console Google Cloud, vai alla pagina  Dashboard:

    Vai a Dashboard

    Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Monitoring.

  2. Fai clic su Modelli di dashboard.
  3. Cerca la dashboard del collezionista OpenTelemetry.
  4. (Facoltativo) Per visualizzare l'anteprima della dashboard, selezionala.

  5. Fai clic su Aggiungi dashboard al tuo elenco e completa la finestra di dialogo.

    La finestra di dialogo ti consente di selezionare il nome della dashboard e di aggiungervi le etichette.

Per saperne di più sull'installazione delle dashboard, consulta Installare un modello di dashboard.