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

Questo documento descrive come eseguire l'agente di raccolta OpenTelemetry creato da Google su Google Kubernetes Engine per raccogliere log, metriche e tracce OTLP dalle applicazioni instrumentate e quindi esportare questi dati in Google Cloud.

Prima di iniziare

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

Accedi al tuo Google Cloud account. Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

1. Per un cluster Kubernetes. Se non hai un cluster Kubernetes, segui le istruzioni nella guida rapida per GKE.

2. I seguenti strumenti a riga di comando:

   • gcloud
   • kubectl

   Gli strumenti gcloud e kubectl fanno parte di Google Cloud CLI. Per informazioni sulla loro installazione, consulta Gestire i componenti di Google Cloud CLI. Per visualizzare i componenti di gcloud CLI installati, esegui questo comando:

           gcloud components list
           

Configurare le autorizzazioni per l'agente di raccolta

Se hai disattivato Workload Identity GKE, puoi saltare questa sezione.

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

Importante: devi concedere questi ruoli al account di servizio Kubernetes del raccoglitore OpenTelemetry, non al tuo account utente. La mancata concessione dei ruoli all'entità corretta potrebbe comportare errori di autorizzazione.

• Monitoring Metric Writer (roles/monitoring.metricWriter)
• Logging Log Writer (roles/logging.logWriter)
• Cloud Trace Agent (roles/cloudtrace.agent)

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

L'amministratore potrebbe anche essere in grado di concedere al account di servizio Kubernetes del raccoglitore OpenTelemetry le autorizzazioni richieste tramite ruoli personalizzati o altri ruolipredefiniti.

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

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 Google Cloud numero di progetto.

Eseguire il deployment del raccoglitore

La pipeline del raccoglitore può essere sottoposta a deployment direttamente dagli esempi verificati forniti dal repository Self-Managed OTLP Kubernetes Ingestion. Puoi eseguire il deployment direttamente da GitHub con i seguenti comandi dopo aver sostituito PROJECT_ID con l'ID del tuo Google Cloud progetto:

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

Prima di eseguire i comandi, sostituisci le seguenti variabili:

• PROJECT_ID: l'identificatore del progetto.
• PROJECT_NUMBER: l'identificatore numerico del progetto.

Configurare l'agente di raccolta

Ti forniamo una configurazione del raccoglitore OpenTelemetry da utilizzare con il raccoglitore creato da Google. Questa configurazione è progettata per fornire volumi elevati di metriche, log e tracce OTLP con metadati GKE e Kubernetes coerenti allegati. Questa configurazione è progettata anche per prevenire problemi comuni di importazione. Puoi aggiungere elementi alla configurazione, ma ti consigliamo vivamente di non rimuoverli.

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

Configurazione dell'agente di raccolta fornita

Puoi trovare la configurazione dell'agente di raccolta 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.5.0 OpenTelemetry Collector Built By Google/0.131.0 (linux/amd64)
  googlemanagedprometheus:
    user_agent: Google-Cloud-OTLP manifests:0.5.0 OpenTelemetry Collector Built By Google/0.131.0 (linux/amd64)
  # The otlphttp exporter is used to send traces to Google Cloud Trace using OTLP http/proto
  # The otlp exporter could also be used to send them using OTLP grpc
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com
    # Use the googleclientauth extension to authenticate with Google credentials
    auth:
      authenticator: googleclientauth


extensions:
  health_check:
    endpoint: ${env:MY_POD_IP}:13133
  googleclientauth:


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.5.0 OpenTelemetry Collector Built By Google/0.131.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

  # When sending telemetry to the GCP OTLP endpoint, the gcp.project_id resource attribute is required to be set to your project ID.
  resource/gcp_project_id:
    attributes:
    - key: gcp.project_id
      # MAKE SURE YOU REPLACE THIS WITH YOUR PROJECT ID
      value: ${GOOGLE_CLOUD_PROJECT}
      action: insert
  # The metricstarttime processor is important to include if you are using the prometheus receiver to ensure the start time is set properly.
  # It is a no-op otherwise.
  metricstarttime:
    strategy: subtract_initial_point

receivers:
  # This collector is configured to accept OTLP metrics, logs, and traces, and is designed to receive OTLP from workloads running in the cluster.
  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
  - googleclientauth
  pipelines:
    logs:
      exporters:
      - googlecloud
      processors:
      - k8sattributes
      - resourcedetection
      - memory_limiter
      - batch
      receivers:
      - otlp
    metrics/otlp:
      exporters:
      - googlemanagedprometheus
      processors:
      - k8sattributes
      - memory_limiter
      - metricstarttime
      - 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:
      - otlphttp
      processors:
      - k8sattributes
      - memory_limiter
      - resource/gcp_project_id
      - resourcedetection
      - batch
      receivers:
      - otlp
  telemetry:
    logs:
      encoding: json
    metrics:
      readers:
      - periodic:
          exporter:
            otlp:
              protocol: grpc
              endpoint: http://${env:MY_POD_IP}:14317
              insecure: true

Esportatori

La configurazione dell'agente di raccolta include i seguenti esportatori:

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

• googlemanagedprometheus esportatore per le metriche. Questo esportatore non richiede alcuna configurazione, ma sono disponibili opzioni di configurazione. Per informazioni sulle opzioni di configurazione dell'esportatore googlemanagedprometheus, consulta la sezione Inizia a utilizzare l'agente di raccolta OpenTelemetry nella documentazione di Google Cloud Managed Service per Prometheus.

Processori

La configurazione dell'agente di raccolta include i seguenti processori:

• batch: configurato per raggruppare le richieste di telemetria al Google Cloud numero massimo di voci per richiesta o all' Google Cloud intervallo minimo di ogni 5 secondi (a seconda di quale si verifica per prima).

• memory_limiter: limita la memoria utilizzata dell'agente di raccolta per evitare arresti anomali dovuti a memoria insufficiente eliminando i punti dati quando viene superato il limite.

• resourcedetection: rileva automaticamente Google Cloud le etichette delle risorse come project_id e cluster_name.

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

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

Ricevitori

La configurazione dell'agente di raccolta include solo il otlp ricevitore. Per informazioni sull'instrumentazione delle applicazioni per inviare tracce OTLP e metriche all'endpoint OTLP del raccoglitore, consulta Scegliere un approccio di instrumentazione.

Componenti disponibili

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

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

Generare la telemetria

Questa sezione descrive il deployment di un'applicazione di esempio, l'indirizzamento dell'applicazione all'endpoint OTLP del raccoglitore e la visualizzazione della telemetria in Google Cloud. L'applicazione di esempio è un piccolo generatore che esporta tracce, log e metriche nell'agente di raccolta.

Se hai già un'applicazione instrumentata con un SDK OpenTelemetry, puoi indirizzare l'applicazione all'endpoint del raccoglitore.

Per eseguire il deployment dell'applicazione di esempio, esegui questo 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 raccoglitore, 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 fluire attraverso l'agente di raccolta alla Google Cloud console per ogni indicatore.

Visualizzare la telemetria

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

Visualizzare le metriche

L'agente di raccolta OpenTelemetry creato da Google raccoglie le metriche Prometheus che puoi visualizzare utilizzando Esplora metriche. Le metriche raccolte dipendono dall'instrumentazione dell'app, anche se l'agente di raccolta creato da Google scrive anche alcune metriche proprie.

Per visualizzare le metriche raccolte dall'agente di raccolta OpenTelemetry creato da Google:

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

   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 app.
3. Nell'elemento Metrica , espandi il menu Seleziona una metrica , inserisci 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 dall'agente di raccolta OpenTelemetry creato da Google hanno il prefisso prometheus.googleapis.com.
   3. Fai clic su Applica.

4. Per aggiungere filtri, che rimuovono le serie temporali dai risultati della query, utilizza l' elemento Filtro.

5. Configura la modalità di visualizzazione dei dati.
   

   Quando le misurazioni di una metrica sono cumulative, Metrics Explorer normalizza automaticamente i dati misurati in base a l periodo di allineamento, il che comporta la visualizzazione di una frequenza nel grafico. Per saperne di più, consulta Tipi, tipi e conversioni.

   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 Seleziona le metriche durante l'utilizzo di Esplora metriche.

Visualizzare le tracce

Per visualizzare i dati di traccia:

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

   Vai a Esplora tracce

   Puoi trovare questa pagina anche utilizzando la barra di ricerca.

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

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

   Si apre un riquadro che mostra informazioni sulla richiesta tracciata. Questi dettagli includono il metodo, il codice di stato, il numero di byte e lo user agent 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 saperne di più sull'utilizzo di Esplora tracce, consulta Trovare ed esplorare le tracce.

Visualizzare i log

Da Esplora log, puoi esaminare i log e visualizzare anche le tracce associate, se esistenti.

1. Nella Google Cloud console, vai alla pagina segmento 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 dell'app instrumentata. Per visualizzare i dettagli, espandi la voce di log.

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

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

Per saperne di più sull'utilizzo di Esplora log, consulta Visualizza i log utilizzando Esplora log.

Osservare ed eseguire il debug del raccoglitore

Il raccoglitore OpenTelemetry creato da Google fornisce automaticamente metriche di auto-osservabilità per aiutarti a monitorare le sue prestazioni e garantire la continuità dell'uptime della pipeline di importazione OTLP.

Per monitorare l'agente di raccolta, installa la dashboard di esempio per l'agente di raccolta. Questa dashboard offre informazioni rapide su diverse metriche dell'agente di raccolta, tra cui uptime, memoria utilizzata e chiamate API a Google Cloud Observability.

Per installare la dashboard:

1. Nella Google Cloud console, 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 Raccoglitore OpenTelemetry.
4. (Facoltativo) Per visualizzare l'anteprima della dashboard, selezionala.

5. Fai clic su Aggiungi dashboard all'elenco e completa la finestra di dialogo.

   La finestra di dialogo ti consente di selezionare il nome della dashboard e di aggiungere etichette alla dashboard.

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