Esegui il deployment e utilizza il raccoglitore

Questo documento descrive come eseguire il deployment di OpenTelemetry Collector, configurare il collettore per utilizzare l'esportatore otlphttp e l' API Telemetry (OTLP) ed eseguire un generatore di telemetria per scrivere metriche in Cloud Monitoring. Puoi quindi visualizzare queste metriche in Cloud Monitoring.

Se utilizzi Google Kubernetes Engine, puoi seguire OpenTelemetry gestito per GKE anziché eseguire manualmente il deployment e la configurazione di un agente di raccolta OpenTelemetry che utilizza l'API Telemetry.

Se utilizzi un SDK per inviare metriche da un'applicazione direttamente all' API Telemetry, consulta Utilizzare gli SDK per inviare metriche dalle applicazioni per ulteriori informazioni ed esempi.

Puoi anche utilizzare un agente di raccolta OpenTelemetry e l'API Telemetry insieme alla strumentazione senza codice OpenTelemetry. Per ulteriori informazioni, consulta Utilizzare la strumentazione senza codice OpenTelemetry per Java.

Prima di iniziare

Questa sezione descrive come configurare l'ambiente per il deployment e l'utilizzo dell'agente di raccolta.

Seleziona o crea un Google Cloud progetto

Scegli un Google Cloud progetto per questa procedura dettagliata. Se non hai già un Google Cloud progetto, creane uno:

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

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

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

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

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

Installare gli strumenti a riga di comando

Questo documento utilizza 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

Per configurare gcloud CLI per l'utilizzo, esegui questi comandi:

gcloud auth login
gcloud config set project PROJECT_ID

Abilita API

Abilita l'API Cloud Monitoring e l'API Telemetry nel tuo Google Cloud progetto. Presta particolare attenzione all' API Telemetry, telemetry.googleapis.com; questo documento potrebbe essere la prima volta che incontri questa API.

Abilita le API eseguendo questi comandi:

gcloud services enable monitoring.googleapis.com
gcloud services enable telemetry.googleapis.com

Crea un cluster

Creare un cluster GKE.

  1. Crea un cluster Google Kubernetes Engine denominato otlp-test eseguendo questo comando:

    gcloud container clusters create-auto --location CLUSTER_LOCATION otlp-test --project PROJECT_ID

  2. Dopo aver creato il cluster, connettiti eseguendo questo comando:

    gcloud container clusters get-credentials otlp-test --region CLUSTER_LOCATION --project PROJECT_ID

Autorizzare il account di servizio Kubernetes

I seguenti comandi concedono i ruoli Identity and Access Management (IAM) necessari al account di servizio Kubernetes. Questi comandi presuppongono che tu stia utilizzando Workload Identity Federation for GKE:

export PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")

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

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 \
  --condition=None

gcloud projects add-iam-policy-binding projects/PROJECT_ID \
  --role=roles/telemetry.tracesWriter \
  --member=principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector \
  --condition=None

Se il tuo account di servizio ha un formato diverso, puoi utilizzare il comando nella documentazione di Google Cloud Managed Service per Prometheus per autorizzare il service account, con le seguenti modifiche:

  • Sostituisci il nome del service account gmp-test-sa con il tuo account di servizio.
  • Concedi i ruoli mostrati nel set di comandi precedente, non solo il ruolo roles/monitoring.metricWriter.

Eseguire il deployment di OpenTelemetry Collector

Crea la configurazione dell'agente di raccolta copiando il seguente file YAML e inserendolo in un file denominato collector.yaml. Puoi anche trovare la seguente configurazione su GitHub nel otlp-k8s-ingest repository.

Nella tua copia, assicurati di sostituire l'occorrenza di ${GOOGLE_CLOUD_PROJECT} con l'ID progetto, PROJECT_ID.

OTLP per le metriche di Prometheus funziona solo quando si utilizza OpenTelemetry Collector versione 0.140.0 o successive.

# 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:
  # The googlecloud exporter is used for logs
  googlecloud:
    log:
      default_log_name: opentelemetry-collector
    user_agent: Google-Cloud-OTLP manifests:0.4.0 OpenTelemetry Collector Built By Google/0.128.0 (linux/amd64)
  googlemanagedprometheus:
    user_agent: Google-Cloud-OTLP manifests:0.4.0 OpenTelemetry Collector Built By Google/0.128.0 (linux/amd64)
  # The otlphttp exporter is used to send traces to Google Cloud Trace and
  # metrics to Google Managed Prometheus 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:
  # Standard for the collector. Used for probes.
  health_check:
    endpoint: ${env:MY_POD_IP}:13133
  # This is an auth extension that adds Google Application Default Credentials to http and gRPC requests.
  googleclientauth:


processors:
  # This filter is a standard part of handling the collector's self-observability metrics. Not related to OTLP ingestion.
  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

  # The recommended batch size for the OTLP endpoint is 200 metric data points.
  batch:
    send_batch_max_size: 200
    send_batch_size: 200
    timeout: 5s

  # The k8sattributes processor adds k8s resource attributes to metrics based on the source IP that sent the metrics to the collector.
  # k8s attributes are important for avoiding errors from timeseries "collisions".
  # These attributes help distinguish workloads from each other, and provide useful metadata (e.g. namespace) when querying.
  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

  # Standard processor for gracefully degrading when overloaded to prevent OOM.
  memory_limiter:
    check_interval: 1s
    limit_percentage: 65
    spike_limit_percentage: 20

  # Standard processor for enriching self-observability metrics. Unrelated to OTLP ingestion.
  metricstransform/self-metrics:
    transforms:
    - action: update
      include: otelcol_process_uptime
      operations:
      - action: add_label
        new_label: version
        new_value: Google-Cloud-OTLP manifests:0.4.0 OpenTelemetry Collector Built By Google/0.128.0 (linux/amd64)

  # The resourcedetection processor, similar to the k8sattributes processor, enriches metrics with important metadata.
  # The gcp detector provides the cluster name and cluster location.
  resourcedetection:
    detectors: [gcp]
    timeout: 10s

  # This transform processor avoids ingestion errors if metrics contain attributes with names that are reserved for the prometheus_target resource.
  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
  # For each Prometheus unknown-typed metric, which is a gauge, create a counter that is an exact copy of this metric.
  # The GCP OTLP endpoint will add appropriate the appropriate suffixes for the counter and gauge.
  transform/unknown-counter:
    metric_statements:
    - context: metric
      statements:
      # Copy the unknown metric, but add a suffix so we can distinguish the copy from the original.
      - copy_metric(Concat([metric.name, "unknowncounter"], ":")) where metric.metadata["prometheus.type"] == "unknown" and not HasSuffix(metric.name, ":unknowncounter")
      # Change the copy to a monotonic, cumulative sum.
      - convert_gauge_to_sum("cumulative", true) where HasSuffix(metric.name, ":unknowncounter")
      # Delete the extra suffix once we are done.
      - set(metric.name, Substring(metric.name, 0, Len(metric.name)-Len(":unknowncounter"))) where HasSuffix(metric.name, ":unknowncounter")

  # 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

  # Push the collector's own self-observability metrics to the otlp receiver.
  otlp/self-metrics:
    protocols:
      grpc:
        endpoint: ${env:MY_POD_IP}:14317

service:
  extensions:
  - health_check
  - googleclientauth
  pipelines:
    # Recieve OTLP logs, and export logs using the googlecloud exporter.
    logs:
      exporters:
      - googlecloud
      processors:
      - k8sattributes
      - resourcedetection
      - memory_limiter
      - batch
      receivers:
      - otlp
    # Recieve OTLP metrics, and export metrics to GMP using the otlphttp exporter.
    metrics/otlp:
      exporters:
      - otlphttp
      processors:
      - k8sattributes
      - memory_limiter
      - resource/gcp_project_id
      - resourcedetection
      - transform/collision
      - transform/aco-gke
      - transform/unknown-counter
      - metricstarttime
      - batch
      receivers:
      - otlp
    # Scrape self-observability Prometheus metrics, and export metrics to GMP using the otlphttp exporter.
    metrics/self-metrics:
      exporters:
      - otlphttp
      processors:
      - filter/self-metrics
      - metricstransform/self-metrics
      - k8sattributes
      - memory_limiter
      - resource/gcp_project_id
      - resourcedetection
      - batch
      receivers:
      - otlp/self-metrics
    # Recieve OTLP traces, and export traces using the otlphttp exporter.
    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: ${env:MY_POD_IP}:14317

Configurare OpenTelemetry Collector di cui è stato eseguito il deployment

Configura il deployment dell'agente di raccolta creando risorse Kubernetes.

  1. Crea lo spazio dei nomi opentelemetry e crea la configurazione dell'agente di raccolta nello spazio dei nomi eseguendo questi comandi:

    kubectl create namespace opentelemetry

kubectl create configmap collector-config -n opentelemetry --from-file=collector.yaml

  2. Configura l'agente di raccolta con le risorse Kubernetes eseguendo questi comandi:

    kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/otlp-k8s-ingest/refs/heads/otlpmetric/k8s/base/2_rbac.yaml

kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/otlp-k8s-ingest/refs/heads/otlpmetric/k8s/base/3_service.yaml

kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/otlp-k8s-ingest/refs/heads/otlpmetric/k8s/base/4_deployment.yaml

kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/otlp-k8s-ingest/refs/heads/otlpmetric/k8s/base/5_hpa.yaml

  3. Attendi che i pod del collettore raggiungano lo stato "In esecuzione" e che 1/1 container siano pronti. Se questo è il primo workload di cui è stato eseguito il deployment, l'operazione richiede circa tre minuti su Autopilot. Per controllare i pod, utilizza questo comando:

    kubectl get po -n opentelemetry -w

    Per interrompere il monitoraggio dello stato del pod, premi Ctrl-C per interrompere il comando.

  4. Puoi anche controllare i log dell'agente di raccolta per assicurarti che non ci siano errori evidenti:

    kubectl logs -n opentelemetry deployment/opentelemetry-collector

Eseguire il deployment del generatore di telemetria

Puoi testare la configurazione utilizzando lo strumento open source telemetrygen tool. Questa app genera la telemetria e la invia all'agente di raccolta.

  1. Per eseguire il deployment dell'app telemetrygen nello spazio dei nomi opentelemetry-demo, esegui questo comando:

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

  2. Dopo aver creato il deployment, potrebbe essere necessario un po' di tempo prima che i pod vengano creati e inizino a essere eseguiti. Per controllare lo stato dei pod, esegui questo comando:

    kubectl get po -n opentelemetry-demo -w

    Per interrompere il monitoraggio dello stato del pod, premi Ctrl-C per interrompere il comando.

Eseguire una query su una metrica utilizzando Metrics Explorer

Lo strumento telemetrygen scrive in una metrica denominata gen. Puoi eseguire una query su questa metrica sia dall'interfaccia di creazione di query sia dall'editor di query PromQL in Metrics Explorer.

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.

  • Se utilizzi l'interfaccia di creazione di query di Metrics Explorer, il nome completo della metrica è prometheus.googleapis.com/gen/gauge.
  • Se utilizzi l'editor di query PromQL, puoi eseguire una query sulla metrica utilizzando il nome gen.

L'immagine seguente mostra un grafico della metrica gen in Metrics Explorer:

Un grafico mostra la metrica gen, acquisita dall'esportatore otlphttp.

Elimina il cluster

Dopo aver verificato il deployment eseguendo una query sulla metrica, puoi eliminare il cluster. Per eliminare il cluster, esegui questo comando:

gcloud container clusters delete --location CLUSTER_LOCATION otlp-test --project PROJECT_ID

Passaggi successivi