Déployer Managed OpenTelemetry pour GKE

Ce document explique comment configurer Managed OpenTelemetry pour GKE afin d'envoyer des traces, des métriques et des journaux OpenTelemetry Protocol (OTLP) à Google Cloud Observability à partir d'applications exécutées sur GKE.

Pour en savoir plus sur le fonctionnement d'OpenTelemetry géré pour GKE, consultez OpenTelemetry géré pour GKE.

Vous pouvez utiliser Managed OpenTelemetry pour GKE pour effectuer les opérations suivantes :

  • Configurez les charges de travail exécutées sur GKE pour envoyer des traces, des métriques et des journaux OTLP (OpenTelemetry Protocol) au collecteur géré.
  • Recevez les traces, les métriques et les journaux OTLP (OpenTelemetry Protocol) des applications exécutées sur GKE.
  • Exportez ces données vers Google Cloud Observability.

Si vous avez besoin de filtrer et de contrôler au niveau du collecteur, utilisez le collecteur OpenTelemetry conçu par Google au lieu de cette offre gérée.

Avant de commencer

  1. Connectez-vous à votre compte Google Cloud . Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits sans frais pour exécuter, tester et déployer des charges de travail.

  2. Installez la Google Cloud CLI.

  3. Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

  4. Pour initialiser la gcloud CLI, exécutez la commande suivante : 

    gcloud init

  5. Créez ou sélectionnez un projet Google Cloud .

    Rôles requis pour sélectionner ou créer un projet

    • Sélectionnez un projet : la sélection d'un projet ne nécessite pas de rôle IAM spécifique. Vous pouvez sélectionner n'importe quel projet pour lequel un rôle vous a été attribué.
    • Créer un projet : pour créer un projet, vous devez disposer du rôle Créateur de projet (roles/resourcemanager.projectCreator), qui contient l'autorisation resourcemanager.projects.create. Découvrez comment attribuer des rôles.

    • Créez un projet Google Cloud  :

      gcloud projects create PROJECT_ID

      Remplacez PROJECT_ID par le nom du projet Google Cloud que vous créez.

    • Sélectionnez le projet Google Cloud que vous avez créé :

      gcloud config set project PROJECT_ID

      Remplacez PROJECT_ID par le nom de votre projet Google Cloud .

  6. Vérifiez que vous disposez des autorisations requises pour suivre les instructions de ce guide.

  7. Vérifiez que la facturation est activée pour votre projet Google Cloud .

  8. Activez les API GKE, Telemetry (OTLP), Cloud Logging, Cloud Monitoring et Cloud Trace :

    Rôles requis pour activer les API

    Pour activer les API, vous avez besoin du rôle IAM Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles. 

    gcloud services enable container.googleapis.com telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

  9. Installez la Google Cloud CLI.

  10. Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

  11. Pour initialiser la gcloud CLI, exécutez la commande suivante : 

    gcloud init

  12. Créez ou sélectionnez un projet Google Cloud .

    Rôles requis pour sélectionner ou créer un projet

    • Sélectionnez un projet : la sélection d'un projet ne nécessite pas de rôle IAM spécifique. Vous pouvez sélectionner n'importe quel projet pour lequel un rôle vous a été attribué.
    • Créer un projet : pour créer un projet, vous devez disposer du rôle Créateur de projet (roles/resourcemanager.projectCreator), qui contient l'autorisation resourcemanager.projects.create. Découvrez comment attribuer des rôles.

    • Créez un projet Google Cloud  :

      gcloud projects create PROJECT_ID

      Remplacez PROJECT_ID par le nom du projet Google Cloud que vous créez.

    • Sélectionnez le projet Google Cloud que vous avez créé :

      gcloud config set project PROJECT_ID

      Remplacez PROJECT_ID par le nom de votre projet Google Cloud .

  13. Vérifiez que vous disposez des autorisations requises pour suivre les instructions de ce guide.

  14. Vérifiez que la facturation est activée pour votre projet Google Cloud .

  15. Activez les API GKE, Telemetry (OTLP), Cloud Logging, Cloud Monitoring et Cloud Trace :

    Rôles requis pour activer les API

    Pour activer les API, vous avez besoin du rôle IAM Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles. 

    gcloud services enable container.googleapis.com telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com
    16.

Conditions requises

Pour utiliser Managed OpenTelemetry pour GKE, vous devez répondre aux exigences suivantes :

  • Le cluster doit disposer de GKE version 1.34.1-gke.2178000 ou ultérieure.
  • gcloud CLI activée avec la version 551.0.0 ou ultérieure.
  • Si vous utilisez Terraform pour provisionner votre infrastructure GKE, vous devez utiliser le fournisseur terraform-provider-google-beta à la version v7.17.0 ou ultérieure.

Rôles requis

Pour obtenir les autorisations nécessaires pour activer et utiliser OpenTelemetry géré par GKE, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Coûts

Pour en savoir plus sur les coûts liés à l'utilisation de Managed OpenTelemetry pour GKE, consultez Facturation.

Activer Managed OpenTelemetry pour GKE dans un cluster

Pour configurer Managed OpenTelemetry pour GKE, vous devez effectuer les opérations suivantes :

  • Activez Managed OpenTelemetry pour GKE dans un cluster.
  • Configurez l'application que vous surveillez pour qu'elle envoie des signaux au point de terminaison du collecteur géré.

Lorsque vous activez Managed OpenTelemetry pour GKE, les objets suivants sont déployés sur le cluster :

  • Déploiement du collecteur OpenTelemetry géré par GKE, déployé dans l'espace de noms gke-managed-otel. Le point de terminaison HTTP du collecteur OpenTelemetry géré dans le cluster pour les journaux, les métriques et les traces est le suivant : http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318.

  • Définition de ressource personnalisée, instrumentations.telemetry.googleapis.com, que vous pouvez utiliser pour configurer automatiquement vos charges de travail.

    Pour en savoir plus sur les ressources personnalisées, consultez Ressource personnalisée dans la documentation Kubernetes.

Activer sur un nouveau cluster

Pour activer Managed OpenTelemetry pour GKE sur un nouveau cluster, procédez comme suit :

gcloud

Pour un cluster Autopilot, utilisez la commande suivante :

gcloud beta container clusters create-auto CLUSTER_NAME \
  --project=PROJECT_ID \
  --managed-otel-scope=COLLECTION_AND_INSTRUMENTATION_COMPONENTS \
  --location=LOCATION \
  --cluster-version=VERSION

Remplacez les éléments suivants :

  • CLUSTER_NAME : nom du cluster.
  • PROJECT_ID : ID du projet Google Cloud .
  • LOCATION : région ou zone.
  • VERSION : version, qui doit être 1.34.1-gke.2178000 ou ultérieure.

Pour un cluster Standard, utilisez la commande suivante :

gcloud beta container clusters create CLUSTER_NAME \
  --project=PROJECT_ID \
  --managed-otel-scope=COLLECTION_AND_INSTRUMENTATION_COMPONENTS \
  --location=LOCATION \
  --cluster-version=VERSION

Remplacez les éléments suivants :

  • CLUSTER_NAME : nom du cluster.
  • PROJECT_ID : ID du projet Google Cloud .
  • LOCATION : région ou zone.
  • VERSION : version, qui doit être 1.34.1-gke.2178000 ou ultérieure.

Console

  • Pour un cluster Autopilot, procédez comme suit :

    1. Dans la console Google Cloud , accédez à la page Créer un cluster Autopilot.

      Accéder à la page "Créer un cluster Autopilot"

    2. Dans le panneau de navigation, cliquez sur Paramètres avancés.

    3. Dans la section Opérations, sélectionnez Activer OpenTelemetry géré.

    4. Cliquez sur Enregistrer.

  • Pour un cluster Standard, procédez comme suit :

    1. Dans la console Google Cloud , accédez à la page Créer un cluster Kubernetes.

      Accéder à la page "Créer un cluster Kubernetes"

    2. Dans le panneau de navigation, cliquez sur Fonctionnalités.

    3. Dans la section Opérations, sélectionnez Activer OpenTelemetry géré.

    4. Cliquez sur Enregistrer.

Terraform

Pour activer Managed OpenTelemetry pour GKE sur un nouveau cluster à l'aide de Terraform, reportez-vous à l'exemple suivant :

terraform {
  required_providers {
    google-beta = {
      source  = "hashicorp/google-beta"
      version = ">= 7.17.0"
    }
  }
}

resource "google_container_cluster" "default" {
  name     = "gke-standard-regional-with-managed-otel"
  provider = google-beta
  location = "us-west1"

  initial_node_count = 1
  release_channel {
    channel = "RAPID" # The default rapid version already has the feature available.
  }

  managed_opentelemetry_config {
    scope = "COLLECTION_AND_INSTRUMENTATION_COMPONENTS"
  }
}

Pour en savoir plus sur l'utilisation de Terraform, consultez la page Compatibilité de Terraform avec GKE.

Activer sur un cluster existant

Pour activer Managed OpenTelemetry pour GKE sur un cluster existant, procédez comme suit :

gcloud

  1. Assurez-vous que la version du cluster est 1.34.1-gke.2178000 ou ultérieure. Pour en savoir plus sur la mise à niveau d'un cluster existant, consultez Mises à niveau des clusters standards et Mises à niveau des clusters Autopilot.

  2. Activez Managed OpenTelemetry pour GKE à l'aide de la commande suivante :

    gcloud beta container clusters update CLUSTER_NAME \
  --project=PROJECT_ID \
  --managed-otel-scope=COLLECTION_AND_INSTRUMENTATION_COMPONENTS \
  --location=LOCATION

    Remplacez les éléments suivants :

    • CLUSTER_NAME : nom du cluster.
    • PROJECT_ID : ID du projet Google Cloud .
    • LOCATION : région ou zone.

Console

  1. Assurez-vous que la version du cluster est 1.34.1-gke.2178000 ou ultérieure. Pour en savoir plus sur la mise à niveau d'un cluster existant, consultez Mises à niveau des clusters standards et Mises à niveau des clusters Autopilot.

  2. Dans la console Google Cloud , accédez à la page "Clusters Kubernetes" :

    Accéder à la page "Clusters Kubernetes"

  3. Cliquez sur le nom du cluster.

  4. Dans la liste Fonctionnalités, recherchez l'option Managed OpenTelemetry. Si elle est désactivée, cliquez sur Modifier, puis sélectionnez Activer OpenTelemetry géré.

  5. Cliquez sur Enregistrer les modifications.

Terraform

Pour activer Managed OpenTelemetry pour GKE sur un cluster existant, ajoutez le bloc managed_opentelemetry_config à votre ressource google_container_cluster existante, comme dans l'exemple suivant :

terraform {
  required_providers {
    google-beta = {
      source  = "hashicorp/google-beta"
      version = ">= 7.17.0"
    }
  }
}

resource "google_container_cluster" "default" {
  name     = "gke-standard-regional-with-managed-otel"
  provider = google-beta
  location = "us-west1"

  initial_node_count = 1
  release_channel {
    channel = "RAPID" # The default rapid version already has the feature available.
  }

  managed_opentelemetry_config {
    scope = "COLLECTION_AND_INSTRUMENTATION_COMPONENTS"
  }
}

Pour en savoir plus sur l'utilisation de Terraform, consultez la page Compatibilité de Terraform avec GKE.

Configurer votre application pour utiliser le collecteur OpenTelemetry géré

Les applications doivent être configurées pour pouvoir envoyer des signaux au point de terminaison du collecteur géré. Une fois les applications configurées, le collecteur OpenTelemetry géré reçoit des signaux des applications exécutées sur le cluster où le collecteur est activé. Les signaux provenant de l'application incluent les traces, les métriques et les journaux.

Pour envoyer des signaux OpenTelemetry, les applications doivent déjà être instrumentées pour générer des métriques OpenTelemetry. Pour en savoir plus, consultez la page Charges de travail compatibles.

Vous pouvez configurer manuellement votre application pour qu'elle envoie des signaux au point de terminaison du collecteur géré ou utiliser la configuration automatique. Nous vous déconseillons d'utiliser les deux méthodes ensemble pour la même charge de travail, car la configuration automatique peut remplacer les modifications manuelles. Cette combinaison peut rendre plus difficile le suivi des modifications apportées à la configuration.

Les sections suivantes expliquent comment configurer les applications pour qu'elles envoient des signaux au collecteur à l'aide de la configuration automatique.

Configurer la configuration automatique

La configuration automatique utilise des variables d'environnement pour configurer les charges de travail afin qu'elles envoient des signaux au point de terminaison du collecteur géré.

Pour activer l'injection automatique de variables d'environnement dans les pods, vous devez utiliser la ressource personnalisée Instrumentation. Les variables d'environnement contiennent la configuration OpenTelemetry. Elles peuvent être injectées dans certains pods avec des libellés correspondants dans un espace de noms ou dans tous les pods d'un espace de noms.

Ensuite, lorsqu'une application est déployée dans l'espace de noms, GKE utilise la configuration pour injecter automatiquement des variables d'environnement dans les pods où les charges de travail s'exécutent.

  1. Pour configurer la ressource personnalisée Instrumentation :

    1. Enregistrez le fichier manifeste Instrumentation suivant dans un fichier nommé otlp-auto-config-namespace.yaml :

      apiVersion: telemetry.googleapis.com/v1alpha1
kind: Instrumentation
metadata:
  namespace: NAMESPACE
  name: NAME
spec:
  selector:
    matchLabels:
      KEY: VALUE
  autoInstrumentationConfig:
    configInjection:
      enabled: true
  otelSDKConfig:
    tracer_provider:
      sampler:
        parent_based:
          root:
            trace_id_ratio_based:
              ratio: "TRACE_RATIO"
    meter_provider:
      readers:
      - periodic:
          interval: METRICS_INTERVAL

      Remplacez les éléments suivants :

      • NAMESPACE : espace de noms contenant les pods que vous souhaitez cibler pour l'instrumentation automatique. Utilisez default pour cibler l'espace de noms par défaut.
      • NAME : nom du fichier manifeste. Dans cet exemple, le nom est otlp-auto-config-namespace.yaml.
      • (Facultatif) Libellé associé aux pods à cibler. Si un sélecteur vide est spécifié ({}), tous les pods de l'espace de noms sont ciblés.
        • KEY : clé de libellé.
        • VALUE : valeur du libellé.
      • TRACE_RATIO : ratio de données de trace à collecter. Si aucune valeur n'est spécifiée, la valeur par défaut est 1.0. Pour en savoir plus, consultez Modifier le taux d'échantillonnage des traces.
      • METRICS_INTERVAL : intervalle, en millisecondes, des données de surveillance à collecter. La valeur par défaut est 30000. La valeur doit être non négative, avec un minimum de 5 000 ms, un maximum de 300 000 ms et un multiple de 5 000 ms. Pour en savoir plus, consultez Modifier l'intervalle d'exportation des métriques.

    2. Si vous souhaitez modifier l'un des paramètres, consultez la section suivante pour modifier la configuration.

    3. Appliquez la configuration en exécutant la commande suivante :

      kubectl apply -f otlp-auto-config-namespace.yaml

  2. Pour injecter automatiquement les variables d'environnement, vous devez déployer l'application dans l'espace de noms de votre cluster auquel la configuration est appliquée.

    • Pour appliquer la configuration à une charge de travail qui n'est pas encore en cours d'exécution dans l'espace de noms, déployez la charge de travail à l'aide de la commande suivante :

      kubectl apply -f DEPLOYMENT_NAME -n NAMESPACE

      Remplacez les éléments suivants :

      • DEPLOYMENT_NAME : nom du déploiement.
      • NAMESPACE : espace de noms.

    • Pour appliquer la configuration à une charge de travail déjà en cours d'exécution dans l'espace de noms, redéployez la charge de travail à l'aide de la commande suivante :

      kubectl rollout restart deployment DEPLOYMENT_NAME -n NAMESPACE

      Remplacez les éléments suivants :

      • DEPLOYMENT_NAME : nom du déploiement.
      • NAMESPACE : espace de noms.

Une fois la configuration appliquée au cluster, GKE configure automatiquement toutes les charges de travail lorsqu'elles sont déployées dans le cluster. Les charges de travail sont instrumentées en injectant des variables d'environnement dans les pods où elles s'exécutent.

Lorsqu'une charge de travail configurée avec ces variables d'environnement s'exécute dans un cluster où le collecteur géré est déployé, elle envoie des signaux OpenTelemetry au collecteur géré pendant son exécution. Vous pouvez consulter ces signaux dans Google Cloud Observability.

Pour en savoir plus sur l'affichage des signaux, consultez Afficher la télémétrie. Pour obtenir un exemple, consultez Générer des données de télémétrie d'exemple.

Modifier la configuration

Pour modifier la configuration, vous devez procéder comme suit :

  1. Modifiez le fichier manifeste Instrumentation.

  2. Appliquez la configuration modifiée.

  3. Après avoir appliqué la configuration modifiée, redéployez ou redémarrez les applications dans l'espace de noms correspondant de votre cluster.

Pour en savoir plus sur ces étapes, suivez les instructions de la section Créer et déployer la configuration.

Modifier la quantité ou la fréquence de collecte des données

Vous pouvez modifier la quantité de données de trace collectées en modifiant le taux d'échantillonnage des traces.

Vous pouvez modifier la fréquence d'envoi des données de surveillance à Cloud Monitoring en modifiant l'intervalle d'exportation des métriques.

Vous ne pouvez pas modifier la quantité ni la fréquence des données de journalisation collectées. Vous pouvez toutefois désactiver la collecte de toutes les données de journalisation, de métriques ou de traçage. Pour en savoir plus, consultez Sélectionner le type de signal à collecter.

Modifier le taux d'échantillonnage des traces

Une charge de travail peut générer une grande quantité de données de trace. Dans votre cas, il est important de déterminer l'équilibre entre le coût de la collecte et du stockage des données, et le niveau de détail dont vous avez besoin pour que les données soient utiles.

Le comportement par défaut du SDK OpenTelemetry est always_on, ce qui équivaut à un ratio de 1.

Voici un exemple de configuration du taux d'échantillonnage des traces. Dans cet exemple, le ratio est de 0,25.Les données de trace sont donc collectées à un taux de 25 %. Modifiez ce nombre pour changer le taux d'échantillonnage.

    tracer_provider:
      sampler:
        parent_based:
          root:
            trace_id_ratio_based:
              ratio: "0.25"

Modifier l'intervalle d'exportation des métriques

L'intervalle d'exportation des métriques détermine la précision des données que vous pouvez consulter dans les graphiques de Cloud Monitoring.

Voici un exemple de configuration de l'intervalle d'exportation des métriques. Dans cet exemple, l'intervalle d'exportation est de 30 000 ms.

L'intervalle d'exportation des métriques permet de spécifier le délai entre le début de deux exportations consécutives de métriques à partir du SDK OpenTelemetry.

La valeur de cet intervalle doit être non négative, avec un minimum de 5 000 ms, un maximum de 300 000 ms et un multiple de 5 000 ms. La valeur est exprimée en millisecondes.

meter_provider:
  readers:
  - periodic:
      interval: 30000

Sélectionnez les types de signaux à collecter.

Vous pouvez contrôler les types de signaux collectés à partir d'une charge de travail en désactivant les types de signaux que vous ne souhaitez pas collecter. Les types de signaux sont les traces, les métriques et les journaux.

Vous désactivez les types de signaux à l'aide des variables d'environnement dans le conteneur où la charge de travail s'exécute. Pour modifier les variables d'environnement, vous devez modifier la ressource personnalisée Instrumentation, puis redéployer la charge de travail dans le conteneur.

L'exemple suivant est un fichier manifeste Instrumentation configuré pour la collecte des données de trace uniquement. La collecte des journaux et des métriques est désactivée, car meter_provider et logger_provider sont définis sur null.

apiVersion: telemetry.googleapis.com/v1alpha1
kind: Instrumentation
metadata:
  namespace: default
  name: otlp-auto-config-disable-metrics-logs
spec:
  selector:
    matchLabels: # Update the labels to match your workloads
      app: telemetrygen-app
  autoInstrumentationConfig:
    configInjection:
      enabled: true
  otelSDKConfig:
    meter_provider: null
    logger_provider: null

Collecter des données de requêtes et de réponses multimodales

Vous pouvez configurer Managed OpenTelemetry pour GKE afin de collecter les données des requêtes et des réponses multimodales.

Cette fonctionnalité est disponible pour les agents LangGraph ReAct et les agents d'IA générative créés avec le framework Agent Development Kit (ADK).

Pour configurer Managed OpenTelemetry pour GKE afin de collecter des données sur les requêtes et les réponses multimodales, procédez comme suit :

  1. Configurez votre projet Google Cloud et le SDK que vous utilisez en suivant les instructions de la section Collecter des requêtes et des réponses multimodales.

  2. Créez ou identifiez un bucket Cloud Storage à utiliser pour collecter les requêtes et les réponses multimodales. Pour en savoir plus, consultez Créer un bucket.

  3. Accordez au compte de service utilisé par votre application l'autorisation storage.objects.create pour le bucket Cloud Storage.

    Cette autorisation permet à votre application d'écrire des objets dans le bucket Cloud Storage. Ces objets stockent les requêtes et les réponses que l'application agentique crée et reçoit. Pour en savoir plus, consultez Définir et gérer des stratégies IAM sur des buckets.

  4. Configurez le champ promptsResponses.uploadBasePath dans la ressource personnalisée Instrumentation, par exemple :

    apiVersion: telemetry.googleapis.com/v1alpha1
kind: Instrumentation
metadata:
  namespace: default
  name: prompts-responses
spec:
  selector: {}
  promptsResponses:
    uploadBasePath: gs://BUCKET_NAME

    Remplacez BUCKET_NAME par le nom du bucket Cloud Storage.

Lorsque la ressource personnalisée Instrumentation est mise à jour et que les charges de travail sont redémarrées, les variables d'environnement qui configurent les invites et les réponses sont injectées dans les conteneurs des charges de travail.

Pour en savoir plus sur les types de contenus multimédias que vous pouvez collecter et sur la façon d'explorer vos requêtes et réponses multimodales, consultez Collecter et afficher les requêtes et réponses multimodales.

Désactiver la configuration automatique des charges de travail

Pour désactiver l'instrumentation automatique des charges de travail avec la configuration spécifiée, supprimez la ressource personnalisée Instrumentation de votre cluster. Pour ce faire, exécutez la commande suivante :

kubectl delete instrumentations.telemetry.googleapis.com INSTRUMENTATION_NAME -n NAMESPACE

Remplacez les éléments suivants :

  • INSTRUMENTATION_NAME : nom de la ressource personnalisée Instrumentation.
  • NAMESPACE : espace de noms contenant les pods pour lesquels vous souhaitez désactiver la configuration automatique.

Pour désactiver temporairement l'injection automatique de variable d'environnement tout en conservant la configuration de l'instrumentation automatique pour une utilisation ultérieure, définissez autoInstrumentationConfig.configInjection.enabled sur false et appliquez la ressource personnalisée mise à jour.

Voici un exemple de ressource personnalisée avec l'injection automatique de variable d'environnement temporairement désactivée :

apiVersion: telemetry.googleapis.com/v1alpha1
kind: Instrumentation
metadata:
  namespace: default
  name: otlp-auto-config-example
spec:
  selector:
    matchLabels: # Update the labels to match your workloads
      app: telemetrygen-app
  autoInstrumentationConfig:
    configInjection:
      enabled: false # disable environment variables config injection
  otelSDKConfig:
  ... # preserve OpenTelemetry configuration for future use

Une fois que vous avez supprimé la ressource personnalisée ou que vous l'avez mise à jour pour désactiver l'injection automatique de configuration, GKE n'instrumente pas automatiquement les nouvelles charges de travail ciblées par la ressource personnalisée Instrumentation.

Pour arrêter d'exporter des signaux OTLP vers le collecteur géré à partir d'une charge de travail qui a été instrumentée précédemment par la ressource personnalisée, vous devez redémarrer la charge de travail pour que la modification prenne effet. Pour ce faire, utilisez la commande suivante :

kubectl rollout restart deployment DEPLOYMENT_NAME -n NAMESPACE

Remplacez les éléments suivants :

  • DEPLOYMENT_NAME : nom du déploiement.
  • NAMESPACE : espace de noms.

Afficher la télémétrie

Lorsqu'une charge de travail configurée s'exécute sur GKE avec Managed OpenTelemetry pour GKE activé, les signaux OpenTelemetry sont envoyés à Google Cloud Observability.

Pour savoir comment afficher les données dans Google Cloud Observability, consultez les ressources suivantes :

Générer des données de télémétrie d'exemple

Cette section décrit comment déployer un exemple d'application, puis faire pointer cette application vers le point de terminaison OTLP du collecteur OpenTelemetry géré. Vous pouvez ensuite afficher la télémétrie dans Google Cloud.

L'exemple d'application est un petit générateur qui exporte des traces, des journaux et des métriques vers le point de terminaison HTTP du collecteur OpenTelemetry géré dans le cluster. Le point de terminaison OTLP est codé en dur dans l'application et pointe vers http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318.

Si vous disposez déjà d'une application instrumentée avec un SDK OpenTelemetry, vous pouvez générer des données de télémétrie à partir de votre application en la faisant pointer vers le point de terminaison du collecteur ou en configurant l'instrumentation automatique pour l'application.

Pour déployer l'exemple d'application, procédez comme suit :

  1. Connectez-vous au cluster sur lequel vous avez activé Managed OpenTelemetry. Pour ce faire, consultez Définir un cluster par défaut pour les commandes kubectl.

  2. Exécutez la commande suivante :

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

    Après quelques minutes, la télémétrie générée par l'application commence à circuler à travers le collecteur vers le backend Google Cloud pour chaque signal.

    1. Vérifiez que la télémétrie est ingérée en affichant les journaux, les métriques et les traces de l'application de démonstration dans la console Google Cloud  :

    2. Pour afficher les métriques, procédez comme suit :

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

        Accéder à l'explorateur de métriques

      2. Exécutez la requête PromQL suivante dans l'explorateur de métriques :

        sum(avg_over_time({"__name__"="gen","namespace"="opentelemetry-demo","job"="telemetrygen"}[1h]))

    3. Pour afficher les traces, procédez comme suit :

      1. Dans la console Google Cloud , accédez à la page Explorateur Trace.

        Accéder à l'explorateur Trace

      2. Filtrer les segments de trace par nom de segment égal à lets-go.

    4. Pour afficher les journaux, procédez comme suit :

      1. Dans la console Google Cloud , accédez à la page "Explorateur de journaux".

        Accéder à l'explorateur de journaux

      2. Exécutez la requête suivante :

        resource.type="k8s_pod"
resource.labels.namespace_name="opentelemetry-demo"

Désactiver Managed OpenTelemetry pour GKE

Vous pouvez désactiver Managed OpenTelemetry pour GKE dans le cluster. Lorsque vous désactivez le collecteur, le collecteur OpenTelemetry géré est supprimé du cluster et aucune nouvelle donnée de télémétrie n'est collectée.

Pour désactiver Managed OpenTelemetry pour GKE, procédez comme suit.

gcloud

Pour désactiver Managed OpenTelemetry pour GKE pour un cluster, exécutez la commande gcloud suivante :

  gcloud beta container clusters update CLUSTER_NAME \
  --project=PROJECT_ID \
  --managed-otel-scope=NONE \
  --location=LOCATION

Remplacez les éléments suivants :

  • CLUSTER_NAME : nom du cluster.
  • PROJECT_ID : ID du projet Google Cloud .
  • LOCATION : région ou zone.

Console

  1. Dans la console, accédez à la liste des clusters :

    Accéder à la page "Clusters Kubernetes"

  2. Sélectionnez le cluster pour lequel vous souhaitez désactiver le collecteur Managed OpenTelemetry.

  3. Dans Détails du cluster, à côté de Managed OpenTelemetry, sélectionnez l'icône Modifier.

  4. Décochez la case pour désactiver la fonctionnalité.

Terraform

Pour désactiver Managed OpenTelemetry pour GKE, mettez à jour le bloc managed_opentelemetry_config de votre ressource google_container_cluster afin de définir le champ d'application sur NONE.

  1. Mettez à jour votre fichier de configuration Terraform :

    resource "google_container_cluster" "default" {
  provider = google-beta
  name     = "CLUSTER_NAME"
  location = "LOCATION"
  project  = "PROJECT_ID"

  # ... other configuration ...

  managed_opentelemetry_config {
    scope = "NONE"
  }
}

  2. Appliquez la configuration Terraform :

    terraform apply

Remplacez les éléments suivants :

  • CLUSTER_NAME : nom du cluster.
  • LOCATION : région ou zone.
  • PROJECT_ID : ID du projet Google Cloud .

Lorsque vous désactivez Managed OpenTelemetry pour GKE, la définition de ressource personnalisée Instrumentation et les ressources personnalisées Instrumentation ne sont pas supprimées du cluster. Si vous réactivez OpenTelemetry géré, il utilise la configuration conservée dans les ressources personnalisées Instrumentation.

Si vous avez des données de télémétrie qui ont déjà été collectées par Managed OpenTelemetry pour GKE, la désactivation du collecteur n'a aucune incidence sur ces données. Les données existantes sont toujours stockées dans Google Cloud Observability, et aucune nouvelle donnée de télémétrie n'est collectée.

Dépannage

Charges de travail partenaires privilégiées Autopilot

Si vous essayez d'utiliser la configuration automatique avec une charge de travail privilégiée d'un partenaire Autopilot, il est possible que le pod de cette charge de travail ait été refusé.

L'injection de configuration OpenTelemetry n'est pas compatible avec les charges de travail privilégiées des partenaires GKE Autopilot. Cibler de telles charges de travail à l'aide d'une ressource personnalisée Instrumentation pour activer l'injection de variable d'environnement OpenTelemetry peut entraîner l'échec de la mise en correspondance de la charge de travail avec la liste d'autorisation des charges de travail privilégiées Autopilot. Cela signifie que le pod injecté par la configuration serait refusé par GKE Autopilot.

Les journaux, les métriques ou les traces ne sont pas visibles dans la console Google Cloud

Il peut y avoir de nombreuses raisons pour lesquelles les données ne sont pas visibles. Ces raisons incluent des autorisations manquantes pour afficher les données ou une configuration incorrecte qui empêche la collecte des données.

Voici quelques étapes que vous pouvez suivre pour résoudre les problèmes courants :

  • Assurez-vous que toutes les API requises sont activées dans votre projet.

  • Assurez-vous que la ressource personnalisée Instrumentation est correctement configurée, avec un espace de noms correspondant à celui dans lequel la charge de travail s'exécute et un sélecteur correspondant au libellé de votre charge de travail.

  • Inspectez le pod de la charge de travail pour voir si les variables d'environnement sont injectées correctement.

  • Consultez les journaux de conteneur du collecteur OpenTelemetry pour voir si des erreurs s'y trouvent. Pour ce faire, exécutez la commande suivante :

    kubectl logs -n gke-managed-otel -l app=opentelemetry-collector -c opentelemetry-collector

La désactivation d'un signal de télémétrie ne fonctionne pas

Lorsque vous désactivez un signal de télémétrie à l'aide de la ressource personnalisée Instrumentation, assurez-vous d'appliquer la ressource personnalisée et de redéployer les charges de travail.

Lorsque vous appliquez la ressource personnalisée, utilisez Server-Side Apply dans la commande kubectl apply lorsque vous mettez à jour la ressource personnalisée Instrumentation.

Pour savoir comment désactiver un signal de télémétrie, consultez Sélectionner les types de signaux à collecter.

Les variables injectées OpenTelemetry ne sont pas visibles dans ma charge de travail

Les variables sont injectées dans les conteneurs des pods de charge de travail , et non dans la charge de travail. Vérifiez les pods, et non les objets propriétaires tels que les ReplicaSets ou les déploiements.

Par exemple, pour vérifier que les variables sont correctement injectées pour l'exemple de charge de travail dans l'espace de noms par défaut utilisé dans la section précédente Générer des données de télémétrie, procédez comme suit :

  1. Exécutez la commande suivante :

    kubectl get pods -n default -l app=telemetrygen-app -o yaml

  2. Examinez le spec.containers[*].env des pods.

  3. Assurez-vous qu'il existe un objet Instrumentation dans le même espace de noms et vérifiez qu'il cible le pod et que la fonctionnalité d'injection de configuration est activée. Pour ce faire, exécutez la commande suivante :

    kubectl get instrumentations.telemetry.googleapis.com -n default -o yaml

Les variables ne sont injectées dans les conteneurs que lorsque les pods sont créés, car l'API Kubernetes ne permet pas de modifier la plupart des champs de la spécification d'un pod existant, tels que les variables d'environnement. Pour que la configuration prenne effet sur les charges de travail créées avant la création de l'objet Instrumentation, redémarrez la charge de travail. Par exemple, pour un déploiement nommé telemetry-gen-app, exécutez la commande suivante :

kubectl rollout restart deployment -n default telemetry-gen-app

Une quantité excessive de données de trace dans Cloud Trace

Pour réduire les données collectées par Cloud Trace, vous pouvez configurer un échantillonneur basé sur le parent avec un ratio d'ID de trace afin de n'échantillonner qu'un pourcentage de vos traces.

Par exemple, ajoutez les éléments suivants à l'objet Instrumentation :

spec:
  otelSDKConfig:
    tracer_provider:
      sampler:
        parent_based:
          root:
            trace_id_ratio_based:
              ratio: "0.01"

Le comportement par défaut du SDK OpenTelemetry est le traçage "always_on", qui équivaut à un ratio de 1.

Les variables d'environnement ne correspondent pas à la configuration

Si vous avez modifié l'objet Instrumentation, vérifiez que vous avez redémarré vos pods comme décrit dans la section Modifier la configuration.

Si la configuration de votre pod est incorrecte, vérifiez que l'objet Instrumentation cible correctement le pod et que vous n'avez pas plusieurs objets Instrumentation ciblant le même pod :

kubectl get instrumentations --all-namespaces \
-o custom-columns=NAMESPACE:.metadata.namespace,NAME:.metadata.name,SELECTOR:.spec.selector

kubectl get pod -n ${NAMESPACE:?} ${POD_NAME:?} --show-labels

Notez qu'un sélecteur vide cible tous les pods de son espace de noms.

Si plusieurs instrumentations ciblent le même pod lors de sa création, l'instrumentation qui a été mise à jour en dernier prend effet.

La commande kubectl logs ne renvoie aucun résultat.

Lorsque les journaux sont diffusés en flux continu directement d'une application vers un collecteur OpenTelemetry, ils contournent le chemin de journalisation standard pour l'environnement d'exécution du conteneur. Il s'agit du scénario courant lorsque vous utilisez OpenTelemetry pour les journaux. Par défaut, l'exportateur envoie les journaux au point de terminaison otlp au lieu des flux stdout et stderr.

Dans ce cas, comme les journaux ne sont pas écrits dans les flux stdout ou stderr pour que l'environnement d'exécution du conteneur les capture, la commande kubectl logs n'affichera aucun résultat pour cette application. En revanche, la sortie de journalisation est disponible dans Cloud Logging.

Si vous souhaitez utiliser le SDK OpenTelemetry et envoyer également des journaux au flux stdout, vous pouvez le configurer à l'aide de l'exportateur de journaux. Pour en savoir plus, consultez Exportateur de journaux : sortie standard.

Étapes suivantes