Compatibilité avec OTLP dans Google Cloud Observability

Vous pouvez ingérer des données de journaux, de métriques et de traces au format OTLP dans Google Cloud Observability à l'aide de l'API Telemetry (OTLP), qui implémente le protocole OpenTelemetry. Cette API vous permet de collecter des données de télémétrie indépendantes du fournisseur à partir des SDK et des collecteurs OpenTelemetry sans utiliser d'exportateurs Google Cloud personnalisés.

Lorsque vous envoyez des données de télémétrie à votre projet à l'aide de l'API Telemetry, Google Cloud Observability traite chaque signal comme suit :

  • Données de journal : convertit les enregistrements de journal OTLP en entrées de journal et les achemine pour le stockage.
  • Données de métriques : mappe les données de métriques aux séries temporelles Prometheus dans Cloud Monitoring.
  • Données de trace : stocke les traces distribuées dans un format généralement compatible avec OTLP.

Si vous exécutez des charges de travail sur Google Kubernetes Engine, vous pouvez utiliser OpenTelemetry géré pour GKE au lieu de déployer et de gérer manuellement un collecteur OpenTelemetry.

Compatibilité avec le protocole

Le point de terminaison OTLP est compatible avec tous les protocoles de transport et de sérialisation OTLP, y compris http/protobuf, http/json et grpc. Lorsque vous exportez directement depuis des applications à l'aide de SDK, nous vous recommandons d'utiliser l'exportateur OTLP gRPC plutôt que les exportateurs HTTP, car la plupart des exportateurs de SDK ne sont pas compatibles avec l'actualisation dynamique des jetons.

Authentification

Vous devez configurer vos exportateurs avec les identifiants nécessaires pour envoyer des données à votre projet Google Cloud . Par exemple, lorsque vous utilisez des collecteurs, vous utilisez généralement l'extension googleclientauth pour vous authentifier avec des identifiants Google.

Pour obtenir un exemple d'authentification lors de l'exportation directe de données de trace, consultez Configurer l'authentification. Cet exemple montre comment configurer l'exportateur avec vos Google Cloud identifiants par défaut de l'application (ADC) et ajouter une bibliothèque d'authentification Google spécifique au langage à votre application.

Pour envoyer des données de télémétrie à votre projet Google Cloud à l'aide de l'API Telemetry, vous devez également effectuer les opérations suivantes :

  • Configurer un projet de quota Pour en savoir plus, consultez Définir le projet de quota.

  • Attribuez les rôles IAM (Identity and Access Management) suivants à l'utilisateur ou au compte de service utilisé par l'application :

Ingestion OTLP

Cette section explique comment vos données de journaux, de métriques et de traces sont converties d'OTLP en structures de données Google Cloud Observability.

Ingestion des données de journaux

Lorsque vous utilisez l'API Telemetry pour ingérer des journaux au format OTLP, vos données de journaux sont converties en entrées de journal Cloud Logging. Une requête de journal entrante au format OTLP en JSON présente la structure générale suivante :

"resourceLogs": [
    {
      "resource": {
        "attributes": [...]
      },
      "scopeLogs": [
        {
          "scope": { ...}
          "logRecords": [...]
        }
      ]
    }
]

Chaque élément de chaque tableau logRecords devient une entrée de journal Cloud Logging unique. Les attributs resource déterminent la ressource surveillée dans le LogEntry obtenu. Pour en savoir plus sur les attributs requis pour l'ingestion de journaux au format OTLP, consultez Mappage des attributs OTLP au type de ressource.

Pour permettre l'ingestion de journaux au format OTLP, la structure LogEntry de Cloud Logging contient un champ supplémentaire, otel. Étant donné que les modèles de données OTLP et Cloud Logging diffèrent par leur structure, le champ otel conserve une copie des métadonnées de ressource, de champ d'application et d'entité de la requête OTLP entrante.

Par exemple, si vous envoyez une charge utile OTLP resourceLogs comme celle-ci à l'API Telemetry, chaque entrée de journal obtenue contient un champ resource (pour la ressource surveillée) et un champ otel, comme indiqué dans les autres onglets :

resourceLogs 

{
  "resourceLogs": [
    {
      "resource": {
        "attributes": [
          {
            "key": "gcp.project_id",
            "value": { "stringValue": "PROJECT_ID" }
          },
          {
            "key": "gcp.resource_type",
            "value": { "stringValue": "global" }
          }
        ]
      },
      "scopeLogs": [
        {
          "scope": {
            "name": "my.library",
            "version": "1.0.0",
            "attributes": [
              {
                "key": "my.scope.attribute",
                "value": { "stringValue": "some scope attribute" }
              }
            ]
          },
          "logRecords": [ ... ]
         }
       ]
     }
   ]
}

resource 

  {
    ...
    "resource": {
      "labels": {
        "project_id": "PROJECT_ID"
      },
      "type": "global"
    },
    ...
}

otel 

  {
    ...
    "otel": {
      "resource": {
        "attributes": {
          "gcp.project_id": "PROJECT_ID",
          "gcp.resource_type": "global"
        }
      },
      "scope": {
        "attributes": {
          "my.scope.attribute": "some scope attribute"
        },
        "name": "my.library",
        "version": "1.0.0"
      }
    },
   ...
  }

Comme les entrées de journal Cloud Logging sont autonomes et ne sont pas liées à des schémas de ressources externes, toutes les métadonnées de ressource, de champ d'application et d'entité OTLP sont copiées dans chaque entrée de journal.

Ingestion de données de métriques

OTLP pour les métriques Prometheus ne fonctionne qu'avec la version 0.140.0 ou ultérieure du collecteur OpenTelemetry.

Lorsque des métriques sont ingérées dans Cloud Monitoring à l'aide d'un collecteur OpenTelemetry et de l'exportateur otlphttp, ou envoyées directement à l'aide d'un SDK OpenTelemetry, les métriques OTLP sont mappées aux structures de métriques Cloud Monitoring. Pour en savoir plus sur ces mappages, consultez les ressources suivantes :

Google Cloud Observability convertit les métriques au format de série temporelle Prometheus. Les noms de métriques ne doivent pas avoir de domaine ou doivent avoir le domaine prometheus.googleapis.com. Après la conversion, le nom de la métrique inclut le préfixe prometheus.googleapis.com et un suffixe supplémentaire, en fonction du type de point OTLP. La métrique Cloud Monitoring obtenue présente la structure suivante :

prometheus.googleapis.com/{metric_name}/{suffix}

De plus, pour chaque ressource OpenTelemetry unique, la conversion ajoute une métrique target_info contenant tous les attributs de ressource, à l'exception de service.name, service.instance.id et service.namespace.

Étant donné que les noms de métriques et les clés d'étiquettes dans Cloud Monitoring ne sont pas entièrement compatibles avec UTF-8, les données de métriques peuvent être refusées :

  • Les noms de métriques qui ne sont pas conformes à l'expression régulière [a-zA-Z][a-zA-Z0-9_:./-]* sont rejetés. Les seuls caractères spéciaux autorisés dans les noms de métriques sont ceux de l'ensemble _:./-.
  • Les points de données contenant des attributs (c'est-à-dire des clés d'étiquette) qui ne sont pas conformes à l'expression régulière [a-zA-Z_][a-zA-Z0-9_.]* sont refusés. Les seuls caractères spéciaux autorisés dans les clés de libellé sont ceux de l'ensemble _.. Tous les caractères spéciaux sont autorisés dans les valeurs d'étiquette.

Pour éviter que vos métriques ne soient refusées pour ces raisons, utilisez la fonction replace_pattern pour transformer les noms et les attributs de vos métriques.

Ingestion de données de trace

Que vous utilisiez l'API Telemetry ou l'API Cloud Trace, les données de trace entrantes sont stockées dans un format compatible avec OTLP. Toutefois, nous vous recommandons d'utiliser l'API Telemetry, car elle fournit des quotas d'ingestion plus élevés que l'API Cloud Trace.

Voici un exemple de données de trace pouvant être envoyées d'une application à votre projet Google Cloud  :

{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [...]
      },
      "scopeSpans": [
        {
          "scope": { ...},
          "spans": [...]
        }
      ]
    }
  ]
}

Chaque élément de chaque tableau scopeSpans.spans devient un seul segment stocké :

  • Le champ resource de chaque segment contient une copie des données resourceSpans.resource.attributes.
  • Le champ instrumentation_scope de chaque segment contient une copie des données scopeSpans.scope.
  • Chaque segment correspond à une entrée du tableau scopeSpans.spans. Les champs tels que traceId, spanId et kind sont mappés à des champs portant un nom similaire dans le schéma de trace.

Pour en savoir plus, consultez les documents suivants :

Facturation

La facturation des données de journaux, de métriques et de traces ingérées à l'aide de l'API Telemetry dépend du signal de télémétrie. Pour en savoir plus, consultez la page "Facturation".

Facturation des données de journaux

Vous constaterez peut-être une modification de vos valeurs de stockage et de facturation Cloud Logging lorsque vous utilisez l'API Telemetry pour ingérer des journaux en raison d'une modification du volume de journaux.

Les modifications les plus importantes apportées au stockage et à la facturation de votre projet Google Cloud se produisent lorsque les deux conditions suivantes sont remplies :

  • Le champ resource contient des attributs à cardinalité élevée ou un grand nombre d'attributs. Ces attributs de ressource déterminent la ressource surveillée dans le LogEntry obtenu.
  • Le champ scopeLogs contient un grand nombre d'éléments dans les tableaux logRecords. Les champs scopeLogs.scope sont copiés dans le champ otel pour chaque entrée de journal.

Étant donné que ces métadonnées de ressource et de champ d'application sont copiées dans chaque entrée de journal, le volume de journaux stockés peut augmenter.

Pour réduire le volume de stockage, nous vous recommandons de procéder comme suit :

  • Utilisez un processeur de collecteur OpenTelemetry, tel qu'un processeur transform, pour supprimer les attributs de ressource ou de champ d'application inutiles avant d'exporter les données.
  • Si vous n'avez pas besoin de conserver les métadonnées supplémentaires dans le champ otel, utilisez l'option de mappage héritée, gcp.use_legacy_mapping, qui empêche le champ otel d'être renseigné.

Facturation des données de métriques

La facturation des métriques OTLP est comptabilisée sous le SKU "Échantillons Prometheus ingérés", le même que celui utilisé pour les métriques de Google Cloud Managed Service pour Prometheus.

Facturation des données de trace

L'API que vous utilisez pour envoyer des données de trace à votre projet n'a aucune incidence sur le calcul des frais pour ces données.

Interroger vos données de journaux, de métriques et de traces

Vous pouvez utiliser les pages de l'explorateur (Explorateur de journaux, Explorateur de métriques et Explorateur de traces) pour interroger vos données de journaux, de métriques et de traces. Vous pouvez également utiliser la page "Analyse de l'observabilité" pour analyser vos données de journaux et de traces à l'aide de SQL.

Les conseils suivants peuvent vous être utiles lorsque vous interrogez vos données de métriques à l'aide de l'explorateur de métriques :

  • Important : Pour interroger des noms de métriques et des clés d'étiquettes contenant des caractères spéciaux autres que le signe deux-points (:) et le trait de soulignement (_), vous devez les placer entre accolades ({}) et guillemets ("), conformément à la spécification UTF-8 de PromQL. Par exemple, les requêtes suivantes sont valides :

    • {"my.metric.name"}
    • {"my.metric.name", "label.key.KEY"="value"}

  • La conservation de l'étiquette le lors de l'interrogation d'histogrammes exponentiels peut renvoyer des résultats inattendus. Les requêtes histogram_quantile(.99, sum by (le) (metric)) plus courantes devraient fonctionner.

  • Il est possible que les métriques delta ne soient pas interrogées correctement dans certaines circonstances, par exemple lorsque les deltas sont très peu denses.

Limites et quotas

Les limites de l'API Telemetry s'appliquent à tous les types de signaux.

Les quotas et limites suivants s'appliquent également :

  • Données de journaux : les quotas et limites de l'API Cloud Logging s'appliquent.

  • Données de métriques : les quotas et limites de l'API Cloud Monitoring s'appliquent. Par exemple, les métriques ne peuvent pas comporter plus de 200 libellés.

    Le quota par défaut pour les métriques ingérées par l'API Telemetry est de 60 000 requêtes par minute. Avec une taille de lot maximale de 200 points par requête, ce quota est un quota par défaut effectif de 200 000 échantillons par seconde. Vous pouvez demander une augmentation de quota.

  • Données de trace : aucun quota ni aucune limite supplémentaires ne s'appliquent.

Étapes suivantes