Présentation de v1.logs

Ce document explique comment les données de journal envoyées à votre Google Cloud projet à l'aide de l'API Telemetry (OTLP) sont mappées à une structure Cloud Logging. Cette API implémente le protocole OpenTelemetry Line. Vous pouvez envoyer des données à cette API lorsque vous instrumentez vos applications avec un otlphttp exportateur et un collecteur OpenTelemetry, ou lorsque vous utilisez les SDK OpenTelemetry.

OpenTelemetry est un projet Open Source compatible avec Google CloudGoogle Cloud des ingénieurs chargés d'assurer la prise en charge de l'ingestion et de la visualisation de votre télémétrie.

Structure générale des données de journal au format OTLP

Lorsque des données de journal sont envoyées à Google Cloud à l'aide de l'API Telemetry, ces données doivent être dans un format compatible avec OTLP. La structure générale de ces données est la suivante :

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

Notez qu'OpenTelemetry regroupe les journaux individuels, chacun étant représenté par une structure logRecord, avec des informations sur la source de ces journaux, représentée par la structure resource.

Lorsque Google Cloud Observability reçoit un objet resourceLogs, il crée un LogEntry pour chaque logRecord. Contrairement à OTLP, qui regroupe les informations sur la source avec une collection de journaux individuels, chaque structure LogEntry contient des informations sur la source du journal et le journal lui-même.

Pour en savoir plus sur la structure des données de journal au format OTLP, consultez logs.proto OpenTelemetry.

Traitement des données de journal au format OTLP

Lorsque vous envoyez une structure resourceLogs OTLP à l'API Telemetry, Google Cloud Observability effectue les actions suivantes :

  1. Pour chaque logRecord, le système crée une LogEntry.

    Les documents suivants décrivent comment le système remplit la LogEntry à partir des données de journal OTLP :

    Étant donné que chaque LogEntry contient des informations sur le type de ressource Cloud Logging correspondant, chaque LogEntry peut être plus volumineuse que le logRecord OTLP correspondant.

    La conversion de la structure resourceLogs OTLP en une série de structures LogEntry peut être avec pertes. Autrement dit, vous ne pourrez peut-être pas convertir la structure LogEntry en champs resource et logRecord d'origine.

  2. La LogEntry est acheminée vers des récepteurs agrégés dans la hiérarchie du projet et vers des récepteurs dans le projet, exactement comme si l'entrée de journal était envoyée à votre projet à l'aide de l'API Cloud Logging.

Bonnes pratiques

Lorsque vous instrumentez vos applications pour envoyer des données de trace à votre Google Cloud projet, nous vous recommandons d'utiliser un exportateur qui écrit des données au format OTLP dans un collecteur, qui envoie ensuite vos données de trace à l'API Telemetry. Dans votre collecteur, spécifiez uniquement l'URL racine :

exporters:
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com

OpenTelemetry détecte le type de données et ajoute automatiquement /v1/traces, /v1/metrics ou /v1/logs, selon le cas. Pour en savoir plus, consultez Requête OTLP/HTTP.

Pour obtenir des exemples d'exportation de données de trace ou de métriques vers l'API Telemetry, consultez les documents suivants :

Lorsque vous ne pouvez pas utiliser de collecteur, vous pouvez utiliser une bibliothèque OpenTelemetry contenant un exportateur OTLP intégré pour envoyer des données de télémétrie à l'API Telemetry. Pour savoir comment exporter directement des données de trace, consultez Exportateur Cloud Trace vers le point de terminaison OTLP.

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 aussi 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 à la langue à votre application.

Cloud Logging et résidence des données

Par défaut, Cloud Logging achemine les entrées de journal provenant d'un projet vers des buckets de journaux créés par le système. Les buckets de journaux sont des ressources régionales. Vous pouvez mettre à jour le récepteur de journal par défaut pour envoyer des entrées de journal à un bucket de journaux personnalisé situé à l'emplacement de votre choix. Pour en savoir plus, consultez Régionaliser vos journaux.

Cloud Logging fournit des paramètres que vous pouvez configurer pour les organisations et les dossiers. Ces paramètres spécifient l'emplacement des nouveaux buckets de journaux créés par le système, si ces buckets de journaux utilisent des clés de chiffrement gérées par le client (CMEK) et la configuration du récepteur de journal par défaut. Pour en savoir plus, consultez Prise en charge des organisations et des dossiers.

Où afficher les données ingérées ?

Vous pouvez afficher vos données de journal à l'aide des pages Explorateur de journaux et Analyse Observability. Pour en savoir plus, consultez les pages suivantes :

Limites

Cette section décrit les limites. Elle explique également comment Google Cloud Observability gère certains types de données.

Limites

Description Valeur Remarques
Nombre maximal de journaux par requête OTLP 8192 Fait référence au nombre maximal de logRecords dans une structure OTLP resourceLogs. Limite.
Taille maximale de chaque requête 5 Mio Limite.
Taille maximale d'une LogEntry
créée à partir d'un enregistrement de journal OTLP		 256 Kio Cloud Logging tronque ou supprime les données d'un enregistrement de journal OTLP si nécessaire. Limite.
Longueur maximale d'une clé d'attribut 512 octets Les clés de libellé surdimensionnées sont tronquées lorsque l'enregistrement de journal OTLP est converti en LogEntry. Limite.
Longueur maximale d'une valeur d'attribut 64 Kio Valeurs de libellé surdimensionnées lorsque l'enregistrement de journal OTLP est converti en LogEntry. Limite.
Profondeur maximale d'imbrication des attributs 5 Les attributs qui dépassent cette limite sont tronqués lorsque l'enregistrement de journal OTLP est converti en LogEntry.
Nombre maximal d'octets d'ingestion de journaux par minute

2,4 Go pour les régions suivantes : asia-east1, asia-northeast1, asia-southeast1, asia-south1, europe-west1, europe-west2, europe-west3, europe-west4, us-central1, us-east4, us-west1.

300 Mo pour toutes les autres régions.

 Quota.

Comportement

  • Lorsque le numéro de gravité OpenTelemetry et le texte de gravité sont définis, le système utilise le numéro de gravité pour déterminer le niveau de gravité Cloud Logging. Si l'enregistrement OTLP ne contient pas d'informations sur la gravité, le niveau de gravité Cloud Logging est défini sur DEFAULT.

  • Lorsqu'un enregistrement OTLP contient des clés d'attribut en double, le système conserve la première clé et supprime les attributs avec des clés en double.

  • Le système convertit les attributs associés à un enregistrement de journal en chaîne. Pour obtenir un exemple, consultez le champ Libellés.

  • Les noms de journaux doivent être compatibles avec les URL ou être encodés au format URL lors de l'ingestion. Pour en savoir plus sur la définition des noms de journaux, consultez Définition des champs LogEntry.