Présentation de l'ingestion OTLP

Ce document présente l'utilisation de l' API Telemetry (OTLP), telemetry.googleapis.com, qui implémente le protocole OpenTelemetry. L'API Telemetry vous permet d'ingérer des données de journaux, de métriques et de traces au format OTLP dans Google Cloud Observability :

  • Les enregistrements de journaux OTLP sont convertis en entrées de journal puis acheminés et stockés. Pour en savoir plus sur le processus de conversion, consultez la section Ingestion des journaux OTLP de ce document.
  • Les données de métriques sont ingérées dans Cloud Monitoring. Pour en savoir plus sur les noms de métriques et de libellés, ainsi que sur les restrictions d'ingestion, consultez la section Ingestion des métriques OTLP de ce document.
  • Les données de trace sont stockées dans un format généralement cohérent avec OTLP. Pour en savoir plus, consultez la section Ingestion des traces OTLP.

Vous pouvez envoyer des données de télémétrie à l'API Telemetry à partir d'applications qui utilisent des SDK ou en exportant à partir d'un collecteur OpenTelemetry.

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

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 à partir d'applications à l'aide de SDK, nous vous recommandons d'utiliser l'exportateur gRPC OTLP 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 Google Cloud projet. 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 lorsque vous utilisez 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 à la langue à votre application.

Pour envoyer des données de télémétrie à votre Google Cloud projet à l'aide de l'API Telemetry, vous devez également procéder comme suit :

  • Configurez 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 log entries. Une requête de journal au format OTLP entrante au format 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 résultant. Pour en savoir plus sur les attributs requis pour l'ingestion de journaux au format OTLP, consultez la section Mappage des attributs OTLP aux types de ressources.

Pour prendre en charge l'ingestion de journaux au format OTLP, la structure Cloud Logging LogEntry contient un champ supplémentaire, otel. Étant donné que les modèles de données OTLP et Cloud Logging diffèrent en termes de 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 suit à l'API Telemetry, chaque entrée de journal résultante 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"
      }
    },
   ...
  }

Étant donné que 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 des données de métriques

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

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 sur les 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 résultante présente la structure suivante :

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

De plus, pour chaque ressource OpenTelemetry unique, la conversion ajoute une target_info métrique qui contient 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 de libellés dans Cloud Monitoring ne sont pas compatibles avec l'UTF-8 complet, les données de métriques peuvent être rejeté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 appartiennent à l'ensemble _:./-.
  • Les points de données contenant des attributs (c'est-à-dire des clés de libellés) 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 clés de libellés appartiennent à l'ensemble _.. Tous les caractères spéciaux sont autorisés dans les valeurs de libellés.

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

Ingestion des 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 cohérent avec OTLP. Toutefois, nous vous recommandons d'utiliser l'API Telemetry, car elle offre des quotas d'ingestion plus élevés que l'API Cloud Trace.

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

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

Chaque élément de chaque tableau scopeSpans.spans devient une étendue stockée unique :

  • Le champ resource de chaque étendue contient une copie des resourceSpans.resource.attributes données.
  • Le champ instrumentation_scope de chaque étendue 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 dans 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 obtenir des informations complètes, consultez la page Facturation.

Facturation des données de journaux

Vous constaterez peut-être une modification des valeurs de stockage et de facturation de Cloud Logging lorsque vous utiliserez 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 Google Cloud projet 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 résultant.
  • 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 individuelle.

Étant donné que ces métadonnées de ressource et de champ d'application sont copiées dans chaque entrée de journal individuelle, 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 que les métadonnées supplémentaires soient conservées dans le champ otel, utilisez l'option de mappage hérité, 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 la référence "Échantillons Prometheus ingérés", la même que celle utilisée 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 pas d'incidence sur le mode de 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 Observability Analytics 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 de libellés 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"}

  • Conserver le libellé 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 classiques devraient fonctionner.

  • Les métriques delta peuvent ne pas être interrogées correctement dans certaines circonstances, par exemple lorsque les deltas sont très rares.

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 limite supplémentaire ne s'applique.

Étape suivante