Esegui il deployment del raccoglitore OpenTelemetry creato da Google su Compute Engine

Questo documento mostra come eseguire l'agente di raccolta OpenTelemetry integrato in Google su Compute 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 integrato in Google richiede le seguenti risorse:

Accedi al tuo Google Cloud account. Se non hai mai utilizzato Google Cloud, crea un account per valutare il rendimento dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per eseguire, testare ed eseguire il deployment dei carichi di lavoro.

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 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 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. Un'istanza Compute Engine. Se non hai un'istanza Compute Engine segui le istruzioni riportate in Crea e avvia un' istanza Compute Engine.
2. Un'installazione di gcloud. Per informazioni sull'installazione di gcloud, consulta Installa l'interfaccia a riga di comando gcloud.

Configura le autorizzazioni per l'agente di raccolta

Per impostazione predefinita, le istanze Compute Engine utilizzano il service account predefinito di Compute Engine, [e-mail]. Questo account di servizio in genere dispone dei ruoli Identity and Access Management (IAM) necessari per scrivere le metriche e i log descritti in questo documento:

• Monitoring Metric Writer (roles/monitoring.metricWriter)
• Logs Writer (roles/logging.logWriter)
• Agente Cloud Trace

Se scegli di utilizzare un account di servizio gestito dall'utente anziché quello predefinito, devi assegnargli gli stessi ruoli. Per saperne di più, consulta Service account.

Installa l'agente di raccolta

Per installare l'agente di raccolta OpenTelemetry integrato in Google come pacchetto per l'istanza Compute Engine, completa i seguenti passaggi.

Debian e Ubuntu

1. Apri una connessione terminale all'istanza VM utilizzando SSH o uno strumento simile e assicurati di avere accesso sudo.

2. Esegui il comando seguente per configurare il repository dei pacchetti:

   sudo mkdir -p /etc/apt/keyrings
   sudo curl -o /etc/apt/keyrings/otelcol-google.asc https://packages.cloud.google.com/apt/doc/apt-key.gpg
   cat <<EOF | sudo tee /etc/apt/sources.list.d/otelcol-google.list
   deb [signed-by=/etc/apt/keyrings/otelcol-google.asc] https://us-apt.pkg.dev/projects/cloud-ops-agents-artifacts google-cloud-opentelemetry-collector-apt main
   EOF
   

3. Aggiorna il gestore di pacchetti e installa il pacchetto:

   sudo apt update
   sudo apt install otelcol-google
   

   Una volta installato, il raccoglitore OpenTelemetry integrato in Google viene avviato automaticamente.

CentOS, RHEL e Rocky Linux

1. Apri una connessione terminale all'istanza VM utilizzando SSH o uno strumento simile e assicurati di avere accesso sudo.

2. Esegui il comando seguente per configurare il repository dei pacchetti:

   cat <<EOF | sudo tee /etc/yum.repos.d/otelcol-google.repo
   [otelcol-google]
   name=Google Built OpenTelemetry Collector
   baseurl=https://us-yum.pkg.dev/projects/cloud-ops-agents-artifacts/google-cloud-opentelemetry-collector-yum
   autorefresh=0
   enabled=1
   type=rpm-md
   gpgcheck=1
   repo_gpgcheck=0
   gpgkey=http://dl.google.com/linux/linux_signing_key.pub
   EOF
   

3. Installa il pacchetto:

   sudo yum install otelcol-google
   

   Una volta installato, il raccoglitore OpenTelemetry integrato in Google viene avviato automaticamente.

SLES

1. Apri una connessione terminale all'istanza VM utilizzando SSH o uno strumento simile e assicurati di avere accesso sudo.

2. Esegui il comando seguente per configurare il repository dei pacchetti:

   cat <<EOF | sudo tee /etc/zypp/repos.d/otelcol-google.repo
   [otelcol-google]
   name=Google Built OpenTelemetry Collector
   baseurl=https://us-yum.pkg.dev/projects/cloud-ops-agents-artifacts/google-cloud-opentelemetry-collector-yum
   autorefresh=0
   enabled=1
   type=rpm-md
   gpgkey=http://dl.google.com/linux/linux_signing_key.pub
   EOF
   

3. Installa il pacchetto:

   sudo zypper install otelcol-google
   

   Una volta installato, il raccoglitore OpenTelemetry integrato in Google viene avviato automaticamente.

Windows

1. Connettiti all'istanza utilizzando RDP o uno strumento simile ed esegui l'accesso a Windows.

2. Apri un terminale PowerShell con privilegi di amministratore facendo clic con il tasto destro del mouse sull'icona di PowerShell e selezionando Esegui come amministratore.

3. Esegui il seguente comando PowerShell per configurare il repository dei pacchetti:

   googet addrepo otelcol-google `
       https://us-googet.pkg.dev/projects/cloud-ops-agents-artifacts/repos/google-cloud-opentelemetry-collector-googet
   

4. Installa il pacchetto:

   googet install otelcol-google
   

   Una volta installato, il raccoglitore OpenTelemetry integrato in Google viene avviato automaticamente.

Esegui il deployment del raccoglitore

Per impostazione predefinita, l'agente di raccolta OpenTelemetry integrato in Google include una configurazione minima che non esporta la telemetria. Per esportare la telemetria, dopo aver installato l'agente di raccolta, configura l'agente di raccolta sostituendo la configurazione predefinita. Inserisci la configurazione dell'agente di raccolta nei seguenti file:

• Per Linux: /etc/otelcol-google/config.yaml
• Per Windows: C:\Program Files\Google\OpenTelemetry Collector\config.yaml

Configura l'agente di raccolta

Ti forniamo una configurazione dell'agente di raccolta OpenTelemetry da utilizzare con l'agente di raccolta integrato in Google. Questa configurazione è progettata per fornire volumi elevati di metriche, log e tracce OTLP. Questa configurazione è progettata anche per prevenire problemi di importazione comuni. 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 del raccoglitore nella google-built-opentelemetry-collector directory del opentelemetry-operations-collector repository:

receivers:
  # Open two OTLP servers:
  # - On port 4317, open an OTLP GRPC server
  # - On port 4318, open an OTLP HTTP server
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector/tree/main/receiver/otlpreceiver
  otlp:
    protocols:
      grpc:
        endpoint: localhost:4317
      http:
        cors:
          # This effectively allows any origin
          # to make requests to the HTTP server.
          allowed_origins:
          - http://*
          - https://*
        endpoint: localhost:4318

processors:
  # The batch processor is in place to regulate both the number of requests
  # being made and the size of those requests.
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector/tree/main/processor/batchprocessor
  batch:
    send_batch_max_size: 200
    send_batch_size: 200
    timeout: 5s

  # The memorylimiter will check the memory usage of the collector process.
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector/tree/main/processor/memorylimiterprocessor
  memory_limiter:
    check_interval: 1s
    limit_percentage: 65
    spike_limit_percentage: 20

  # The resourcedetection processor is configured to detect GCP resources.
  # Resource attributes that represent the GCP resource the collector is
  # running on will be attached to all telemetry that goes through this
  # processor.
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor#gcp-metadata
  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")

exporters:
  # The googlecloud exporter will export telemetry to different
  # Google Cloud services:
  # Logs -> Cloud Logging
  # Metrics -> Cloud Monitoring
  # Traces -> Cloud Trace
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/googlecloudexporter
  googlecloud:
    log:
      default_log_name: opentelemetry-collector

  # The googlemanagedprometheus exporter will send metrics to
  # Google Managed Service for Prometheus.
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/googlemanagedprometheusexporter
  googlemanagedprometheus:

extensions:
  # Opens an endpoint on 13133 that can be used to check the
  # status of the collector. Since this does not configure the
  # `path` config value, the endpoint will default to `/`.
  #
  # When running on Cloud Run, this extension is required and not optional.
  # In other environments it is recommended but may not be required for operation
  # (i.e. in Container-Optimized OS or other GCE environments).
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/extension/healthcheckextension
  health_check:
    endpoint: 0.0.0.0:13133

service:
  extensions:
  - health_check
  pipelines:
    logs:
      receivers:
      - otlp
      processors:
      - resourcedetection
      - memory_limiter
      - batch
      exporters:
      - googlecloud
    metrics/otlp:
      receivers:
      - otlp
      processors:
      - resourcedetection
      - transform/collision
      - memory_limiter
      - batch
      exporters:
      - googlemanagedprometheus
    traces:
      receivers:
      - otlp
      processors:
      - resourcedetection
      - memory_limiter
      - batch
      exporters:
      - googlecloud
  # Internal telemetry for the collector supports both push and pull-based telemetry data transmission.
  # Leveraging the pre-configured OTLP receiver eliminates the need for an additional port.
  #
  # Docs:
  # https://opentelemetry.io/docs/collector/internal-telemetry/
  telemetry:
    metrics:
      readers:
        - periodic:
            exporter:
              otlp:
                protocol: grpc
                endpoint: http://localhost:4317
                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 pagina Introduzione all'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'intervallo minimo di ogni 5 secondi (a seconda di quale si verifica per primo). Google Cloud

• 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 le Google Cloud etichette delle risorse, ad esempio project_id.

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

L'agente di raccolta OpenTelemetry integrato in 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.

Genera telemetria

Puoi testare la configurazione utilizzando lo strumento open source telemetrygen tool. Le istruzioni per scaricare ed eseguire lo strumento sono incluse nel link. Per eseguire lo strumento, devi installare Go o Docker.

Dopo alcuni minuti, la telemetria generata dall'applicazione inizia a fluire attraverso l'agente di raccolta alla Google Cloud console per ogni indicatore.

Visualizza la telemetria

Il raccoglitore OpenTelemetry integrato in 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.

Visualizza le metriche

Il raccoglitore OpenTelemetry integrato in 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 integrato in Google scrive anche alcune metriche automatiche.

Per visualizzare le metriche raccolte dal raccoglitore OpenTelemetry integrato in 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 , 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 Prometheus Target.
   2. Per selezionare una metrica, utilizza i menu Categorie di metriche attive e Metriche attive. Le metriche raccolte dall'agente di raccolta OpenTelemetry integrato in 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.

Visualizza 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.

Visualizza i log

Da Esplora log, puoi ispezionare 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 ulteriori informazioni sull'utilizzo di Esplora log, vedi Visualizza i log utilizzando Esplora log.

Osserva ed esegui il debug del raccoglitore

Il raccoglitore OpenTelemetry integrato in Google fornisce automaticamente metriche di auto-osservabilità per aiutarti a monitorare le prestazioni e garantire la continuità dell'operatività 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.