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 neutres du point de vue du fournisseur à partir des SDK et 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 journaux : convertit les enregistrements de journaux OTLP en entrées de journaux 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 : stockent 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 Managed OpenTelemetry 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 des 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 projet Google Cloud . Par exemple, lorsque vous utilisez des collecteurs, vous utilisez généralement l'extension googleclientauth pour vous authentifier avec les identifiants Google.

Pour obtenir un exemple d'authentification lors de l'exportation directe des 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 comment ajouter une bibliothèque d'authentification Google spécifique à une langue à 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 décrit 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 de 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 au format OTLP entrant en JSON a 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 Mappage des attributs OTLP aux types de ressources.

Pour prendre en charge 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 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 associées à des schémas de ressources externes, toutes les métadonnées OTLP de ressource, de champ d'application et d'entité sont copiées dans chaque entrée de journal.

Ingestion de 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 pages suivantes :

Google Cloud Observability convertit les métriques au format de série temporelle Prometheus. Les noms de métriques ne doivent pas comporter de domaine ou doivent comporter 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, basé sur le 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 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 entièrement compatibles avec l'UTF-8, les données de métriques peuvent être refusées :

  • Les noms de métriques qui ne respectent pas 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 noms de métriques sont ceux de l'ensemble _:./-.
  • Les points de données contenant des attributs (c'est-à-dire des clés de libellé) qui ne respectent pas 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é appartiennent à l'ensemble _.. Tous les caractères spéciaux sont autorisés dans les valeurs de libellé.

Pour éviter que vos métriques ne soient refusées pour ces raisons, utilisez la fonction replace_pattern pour transformer vos noms et attributs de 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 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 projet Google Cloud  :

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

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

  • Le champ resource de chaque span contient une copie des données resourceSpans.resource.attributes.
  • Le champ instrumentation_scope de chaque span contient une copie des données scopeSpans.scope.
  • Chaque span correspond à une entrée dans le 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 trace 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

Lorsque vous utilisez l'API Telemetry pour ingérer des journaux, vous pouvez constater une modification des valeurs de stockage et de facturation de Cloud Logging en raison d'un changement du volume de journaux.

Les plus grands changements apportés 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 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 ressources et de portée sont copiées dans chaque entrée de journal individuelle, le volume de journaux stockés peut augmenter.

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

  • Utilisez un processeur OpenTelemetry Collector, tel qu'un processeur transform, pour supprimer les attributs de ressource ou de portée 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'ancienne option de mappage, 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", qui est 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 les données de vos journaux, métriques et 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 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 lorsque vous interrogez des histogrammes exponentiels peut renvoyer des résultats inattendus. Les requêtes histogram_quantile(.99, sum by (le) (metric)) plus classiques devraient fonctionner.

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

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 correspond à un quota par défaut effectif de 200 000 échantillons par seconde. Vous pouvez demander une augmentation de quota.

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

Étapes suivantes