Déployer et utiliser le collecteur

Ce document explique comment déployer le collecteur OpenTelemetry, configurer le collecteur pour qu'il utilise l'exportateur otlphttp et l' API Telemetry (OTLP), et exécuter un générateur de télémétrie pour écrire des métriques dans Cloud Monitoring. Vous pouvez ensuite consulter ces métriques dans Cloud Monitoring.

Si vous utilisez Google Kubernetes Engine, vous pouvez suivre la section OpenTelemetry géré pour GKE au lieu de déployer et de configurer manuellement un collecteur OpenTelemetry qui utilise l' API Telemetry.

Si vous utilisez un SDK pour envoyer des métriques d'une application directement à l'API Telemetry, consultez la section Utiliser des SDK pour envoyer des métriques à partir d'applications pour obtenir des informations et des exemples supplémentaires.

Vous pouvez également utiliser un collecteur OpenTelemetry et l'API Telemetry en association avec l'instrumentation sans code OpenTelemetry. Pour en savoir plus, consultez la section Utiliser l'instrumentation sans code OpenTelemetry pour Java.

Avant de commencer

Cette section explique comment configurer votre environnement pour déployer et utiliser le collecteur.

Sélectionner ou créer un Google Cloud projet

Choisissez un Google Cloud projet pour cette procédure. Si vous n'en avez pas encore, créez-en un Google Cloud :

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

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

Installer les outils de ligne de commande

Ce document utilise les outils de ligne de commande suivants :

  • gcloud
  • kubectl

Les outils gcloud et kubectl font partie de Google Cloud CLI. Pour en savoir plus sur leur installation, consultez la page Gérer les composants de Google Cloud CLI. Pour afficher les composants de gcloud CLI que vous avez installés, exécutez la commande suivante :

gcloud components list

Pour configurer gcloud CLI, exécutez les commandes suivantes :

gcloud auth login
gcloud config set project PROJECT_ID

Activer les API

Activez l'API Cloud Monitoring et l'API Telemetry dans votre Google Cloud projet. Portez une attention particulière à l' API Telemetry, telemetry.googleapis.com : il s'agit peut-être de la première fois que vous rencontrez cette API.

Activez les API en exécutant les commandes suivantes :

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

Créer un cluster

créer un cluster GKE ;

  1. Crée un cluster Google Kubernetes Engine nommé otlp-test en exécutant la commande suivante :

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

  2. Une fois le cluster créé, connectez-vous-y en exécutant la commande suivante :

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

Autoriser le compte de service Kubernetes

Les commandes suivantes attribuent les rôles Identity and Access Management (IAM) nécessaires au compte de service Kubernetes. Ces commandes supposent que vous utilisez Workload Identity Federation pour 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./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./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./subject/ns/opentelemetry/sa/opentelemetry-collector \
  --condition=None

Si votre compte de service a un format différent, vous pouvez utiliser la commande de la documentation Google Cloud Managed Service pour Prometheus pour autoriser le compte de service, en apportant les modifications suivantes :

  • Remplacez le nom du compte de service gmp-test-sa par votre compte de service.
  • Attribuez les rôles affichés dans l'ensemble de commandes précédent, et pas seulement le rôle roles/monitoring.metricWriter.

Déployer le collecteur OpenTelemetry

Créez la configuration du collecteur en copiant le fichier YAML suivant et en le plaçant dans un fichier nommé collector.yaml. Vous pouvez également trouver la configuration suivante sur GitHub dans le otlp-k8s-ingest dépôt.

Dans votre copie, veillez à remplacer l'occurrence de ${GOOGLE_CLOUD_PROJECT} par l'ID de votre projet, PROJECT_ID.

OTLP pour les métriques Prometheus ne fonctionne que lorsque vous utilisez le collecteur OpenTelemetry version 0.140.0 ou ultérieure.

# 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

Configurer le collecteur OpenTelemetry déployé

Configurez le déploiement du collecteur en créant des ressources Kubernetes.

  1. Créez l'espace de noms opentelemetry et la configuration du collecteur dans l'espace de noms en exécutant les commandes suivantes :

    kubectl create namespace opentelemetry

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

  2. Configurez le collecteur avec des ressources Kubernetes en exécutant les commandes suivantes :

    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. Attendez que les pods du collecteur atteignent l'état "Running" et que 1/1 conteneurs soient prêts. Cela prend environ trois minutes sur Autopilot, s'il s'agit de la première charge de travail déployée. Pour vérifier les pods, exécutez la commande suivante :

    kubectl get po -n opentelemetry -w

    Pour arrêter de surveiller l'état du pod, appuyez sur Ctrl+C.

  4. Vous pouvez également consulter les journaux du collecteur pour vous assurer qu'il n'y a pas d'erreurs évidentes :

    kubectl logs -n opentelemetry deployment/opentelemetry-collector

Déployer le générateur de télémétrie

Vous pouvez tester votre configuration à l'aide de l'outil Open Source telemetrygen. Cette application génère des données de télémétrie et les envoie au collecteur.

  1. Pour déployer l'application telemetrygen dans l'espace de noms opentelemetry-demo, exécutez la commande suivante :

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

  2. Une fois le déploiement créé, la création et le démarrage des pods peuvent prendre un certain temps. Pour vérifier l'état des pods, exécutez la commande suivante :

    kubectl get po -n opentelemetry-demo -w

    Pour arrêter de surveiller l'état du pod, appuyez sur Ctrl+C.

Interroger une métrique à l'aide de l'explorateur de métriques

L'outil telemetrygen écrit dans une métrique appelée gen. Vous pouvez interroger cette métrique à partir de l'interface du générateur de requêtes et de l'éditeur de requêtes PromQL dans l'explorateur de métriques.

Dans la Google Cloud console, accédez à la  page Explorateur de métriques :

Accéder à l'Explorateur de métriques

Si vous utilisez la barre de recherche pour trouver cette page, sélectionnez le résultat dont le sous-titre est Monitoring.

  • Si vous utilisez l'interface du générateur de requêtes de l'explorateur de métriques, le nom complet de la métrique est prometheus.googleapis.com/gen/gauge.
  • Si vous utilisez l'éditeur de requêtes PromQL, vous pouvez interroger la métrique à l'aide du nom gen.

L'image suivante montre un graphique de la métrique gen dans l'explorateur de métriques :

Un graphique montre la métrique "gen", capturée par l'exportateur otlphttp.

Supprimer le cluster

Après avoir vérifié votre déploiement en interrogeant la métrique, vous pouvez supprimer le cluster. Pour supprimer le cluster, exécutez la commande suivante :

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

Utiliser d'autres collecteurs basés sur OpenTelemetry

Vous pouvez peut-être utiliser d'autres collecteurs basés sur OpenTelemetry pour envoyer des métriques OTLP à l'API Telemetry, bien que Google Cloud ne fournisse pas d'assistance client pour les collecteurs non standards basés sur OpenTelemetry.

Par exemple, vous pouvez envoyer des métriques à l'aide de Grafana Alloy version 1.16.0 ou ultérieure en vous authentifiant avec le otelcol.auth.google composant et en le configurant de la même manière qu'un collecteur OpenTelemetry standard à l'aide des instructions de ce document.

Étape suivante