Présentation de v1.logs

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

OpenTelemetry est un projet Open Source compatible avec Google Cloud. Des ingénieurs Google Cloudsont chargés d'assurer la prise en charge de l'ingestion et de la visualisation de vos données de télémétrie.

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

Lorsque des données de journaux 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, qui est représentée par la structure resource.

Lorsque Google Cloud Observability reçoit un objet resourceLogs, il construit un LogEntry pour chaque logRecord. Contrairement à OTLP, qui regroupe les informations sources 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 journaux au format OTLP, consultez logs.proto sur OpenTelemetry.

Traitement des données de journaux au format OTLP

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

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

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

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

    La conversion de la structure resourceLogs OTLP en une série de structures LogEntry peut entraîner une perte de données. Autrement dit, vous ne pourrez peut-être pas convertir la structure LogEntry vers les champs d'origine resource et logRecord.

  2. LogEntry est acheminé par les récepteurs agrégés de la hiérarchie du projet et par les récepteurs du projet, exactement de la même manière que si l'entrée de journal avait été 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 projetGoogle Cloud , 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 la télémétrie à l'API Telemetry. Pour savoir comment exporter directement les 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 projet Google Cloud . Par exemple, lorsque vous utilisez des collecteurs, vous utilisez généralement aussi 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 à 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 modifier le récepteur de journaux par défaut pour envoyer les entrées de journal vers 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, indiquent si ces buckets de journaux utilisent des clés de chiffrement gérées par le client (CMEK) et définissent la configuration du collecteur de journaux par défaut. Pour en savoir plus, consultez Assistance pour les organisations et les dossiers.

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

Vous pouvez afficher vos données de journaux à l'aide des pages Explorateur de journaux et Analytics sur l'observabilité. Pour en savoir plus, consultez les ressources suivantes :

Limites

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

Limites

Description Valeur Remarques
Nombre maximal de journaux par requête OTLP 8 192 Fait référence au nombre maximal de logRecords dans une structure resourceLogs OTLP. Limite.
Taille maximale de chaque requête 5 Mio Limite.
Taille maximale d'un LogEntry
créé à 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és 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 et le texte de gravité OpenTelemetry 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'attributs en double, le système conserve la première clé et supprime les attributs avec des clés en double.

  • Le système convertit en chaîne de caractères les attributs associés à un enregistrement de journal. Pour obtenir un exemple, consultez 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 savoir comment définir les noms de journaux, consultez Comment définir les champs LogEntry.