Mappage des enregistrements de journaux OTLP vers les entrée de journal

Aperçu

Ce produit ou cette fonctionnalité sont soumis aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les produits et fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une compatibilité limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Ce document explique comment Google Cloud Observability détermine les champs d'un LogEntry à partir de l'enregistrement de journal OTLP, lorsque cet enregistrement est envoyé à Google Cloud à l'aide de l'API Telemetry.

Les exportateurs Google Cloud pour Cloud Logging convertissent les données de journaux au format OTLP en objets LogEntry. Ils envoient ensuite ces données à votre projet Google Cloud à l'aide de l'API Cloud Logging. Toutefois, les règles par défaut que Google Cloud Observability et les exportateurs utilisent pour créer des entrées de journal sont différentes. Pour en savoir plus, consultez Configurer Google Cloud Observability pour utiliser les mappages d'exportateurs.

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.

Comment les champs LogEntry sont-ils définis ?

Google Cloud Observability utilise les règles suivantes pour déterminer les valeurs des champs LogEntry :

Champ LogEntry (Noms issus de la référence HTTP)	Comment le système détermine-t-il la valeur du champ ?
logName	Le système utilise la liste hiérarchisée suivante d'attributs d'enregistrement de journaux OpenTelemetry pour déterminer le nom du journal : gcp.log_name log_name event_name Les noms de journaux doivent être compatibles avec les URL ou être encodés au format URL lors de l'ingestion.
resource	Le système utilise les informations définies dans le champ resource ou déduit la ressource. Pour en savoir plus, consultez Mappage des attributs OTLP aux types de ressources.
timestamp	Le système utilise la liste hiérarchisée suivante des champs d'enregistrement de journaux OpenTelemetry pour déterminer le timestamp : time_unix_nano lorsqu'il est non nul. observed_time_unix_nano lorsqu'il est non nul. Heure à laquelle l'entrée de journal a été ingérée. La période de conservation du bucket de journaux qui stocke les données détermine le code temporel le plus ancien pouvant être ingéré. Pour en savoir plus, consultez Quotas Cloud Logging.
receiveTimestamp	Défini sur l'heure à laquelle LogEntry est ingéré.
severity	Le système mappe la gravité OpenTelemetry dans l'enregistrement du journal à une gravité Cloud Logging. Pour en savoir plus, consultez la section Champ "Gravité".
httpRequest	Le système mappe les attributs gcp.http_request de l'enregistrement du journal aux champs LogEntry équivalents. Pour en savoir plus, consultez la section Champ HttpRequest. FIXME. D'autres champs sont mappés sur ce champ.
labels	Le système définit ce champ à l'aide des valeurs des attributs de l'enregistrement du journal. Pour en savoir plus, consultez la section Champ "Libellés".
trace	Le système définit ce champ sur la valeur du champ traceId de l'enregistrement du journal. La valeur doit être une chaîne hexadécimale valide de 32 caractères, sinon l'entrée est refusée.
spanId	Le système définit ce champ sur la valeur du champ spanId de l'enregistrement du journal. La valeur doit être une chaîne hexadécimale valide de 16 caractères. Sinon, l'entrée est refusée.
traceSampled	Non défini.
sourceLocation	Le système définit ce champ sur les valeurs des attributs Code de l'enregistrement du journal. Pour en savoir plus, consultez la section Champ SourceLocation.
split	Non défini.
apphub apphubDestination apphubSource	Non défini.
otel	Pour les champs des données de journaux OTLP qui n'ont pas de champ équivalent dans un LogEntry, le système convertit les types de données, puis ajoute les données converties au champ otel. Pour en savoir plus, consultez Champ Otel.
Charge utile	Le système définit la charge utile en convertissant le corps d'un enregistrement de journal en un type de charge utile approprié. Pour en savoir plus, consultez Champ "payload".

Champ HttpRequest

Google Cloud Observability mappe les attributs OTLP qui s'appliquent aux requêtes HTTP aux champs LogEntry. Les sections suivantes décrivent comment le système mappe les attributs plats et imbriqués.

Attributs simples

Le tableau suivant décrit comment Google Cloud Observability mappe les attributs plats qui s'appliquent aux requêtes HTTP aux champs LogEntry. Par exemple, la valeur de l'attribut http.request.method: "GET", est définie comme valeur du champ httpRequest.requestMethod dans une entrée de journal :

OpenTelemetry LogRecord.attribute paire clé/valeur.	Valeur stockée dans le champ LogEntry (noms issus de la référence HTTP)	Type accepté
http.request.method	httpRequest.requestMethod	string
url.full http.url	httpRequest.requestUrl	string
http.request.body.size	httpRequest.requestSize	string, int
http.response.status_code	httpRequest.status	string, int
http.response.body.size	httpRequest.responseSize	string, int
user_agent.original http.user_agent	httpRequest.userAgent	string
client.address	remoteIp	chaîne
server.address	serverIp	chaîne
referrer	httpRequest.referer	string
latency	httpRequest.latency	string, int
cacheLookup	httpRequest.cacheLookup	Bool
cacheHit	httpRequest.cacheHit	Bool
cacheValidatedWithOriginServer	httpRequest.cacheValidatedWithOriginServer	Bool
cacheFillBytes	httpRequest.cacheFillBytes	string, int
network.protocol.version protocol	httpRequest.protocol	string

Attributs imbriqués

Cette section décrit comment Google Cloud Observability mappe les attributs OTLP imbriqués qui s'appliquent aux requêtes HTTP aux champs d'un LogEntry. L'exemple suivant illustre un enregistrement de journal contenant deux attributs, chacun contenant au moins un autre attribut :

log_record {
  attributes: {
    gcp.http_request {
      "requestMethod": "GET",
      "requestUrl": "some-URL",
    }
    http_request {
      "requestMethod": "GET",
    }
  }
}

Dans le tableau, les attributs imbriqués sont indiqués à l'aide d'accolades. Par exemple, gcp.http_request {requestMethod} signifie que l'attribut gcp.http_request contient l'attribut requestMethod. La valeur de l'attribut le plus imbriqué est attribuée à la valeur du champ d'entrée de journal :

OpenTelemetry LogRecord.attribute paire clé/valeur.	Valeur stockée dans le champ LogEntry (noms issus de la référence HTTP)	Type accepté
gcp.http_request {requestMethod} http_request {requestMethod}	httpRequest.requestMethod	string
gcp.http_request {requestUrl} http_request {requestUrl}	httpRequest.requestUrl	string
gcp.http_request {requestSize} http_request {requestSize}	httpRequest.requestSize	string, int
gcp.http_request {status} http_request {status}	httpRequest.status	string, int
gcp.http_request {responseSize} http_request {responseSize}	httpRequest.responseSize	string, int
gcp.http_request {userAgent} http_request {userAgent}	httpRequest.userAgent	string
gcp.http_request {remoteIp} http_request {remoteIp}	httpRequest.remoteIp	chaîne
gcp.http_request {serverIp} http_request {serverIp}	httpRequest.serverIp	chaîne
gcp.http_request {referer} http_request {referrer}	httpRequest.referer	string
gcp.http_request {latency} http_request {latency}	httpRequest.latency	string, int
gcp.http_request {cacheLookup} http_request {cacheLookup}	httpRequest.cacheLookup	Bool
gcp.http_request {cacheHit} http_request {cacheHit}	httpRequest.cacheHit	Bool
gcp.http_request { cacheValidatedWithOriginServer} http_request { cacheValidatedWithOriginServer}	httpRequest.cacheValidatedWithOriginServer	Bool
gcp.http_request {cacheFillBytes} http_request {cacheFillBytes}	httpRequest.cacheFillBytes	string, int
gcp.http_request {protocol} http_request {protocol}	httpRequest.protocol	string

Champ "Libellés"

Pour déterminer les libellés à associer à l'entrée de journal, le système effectue les actions suivantes :

1. Il supprime de l'enregistrement de journal OTLP tous les attributs qui ont été mappés à des champs LogEntry spécifiques.

   Par exemple, supposons que les attributs suivants soient associés à un enregistrement de journal :

   attributes: {
       "log_array_attr: ["value1", "value2"],
       "log_json_attr": {"json_key": "json_value"}
       "log-string-attr": "string",
       "code.file.path": "my-file.cc",
       "code.function.name: "my-func",
       "code.line.number": 123,
       "gcp.http_request": {
           "requestMethod": "GET",
           "requestUrl": "my-URL",
     },
   }
   

   Après avoir supprimé les champs mappés sur des champs LogEntry spécifiques, les champs suivants restent :

   attributes: {
       "log_array_attr: ["value1", "value2"],
       "log_json_attr": {"json_key": "json_value"}
       "log-string-attr": "string",
   }
   

2. Si un attribut contient un tableau ou des éléments JSON, le système convertit la valeur en chaîne.

   Par exemple, l'illustration suivante montre comment LogEntry représente les attributs précédents :

   labels: {
       "log_array_attr": "[\"value1\",\"value2\"]",
       "log_json_attr": "{\"json_key\":\"json_value\"}",
       "log-string-attr": "string",
   }
   

   La profondeur d'imbrication maximale pour les attributs est de cinq. Tout contenu imbriqué plus profondément est tronqué.

Champ Otel

Pour les champs des données de journaux OTLP qui n'ont pas de champ équivalent dans un LogEntry, le système convertit les types de données, puis ajoute les données converties au champ otel. Par exemple, le champ otel stocke les attributs des champs resource, scope et entity.

Le système utilise les règles suivantes pour convertir les types de données OpenTelemetry en types protobuf Value :

Type OpenTelemetry	Type Protobuf
string	string
boolean	bool
integer	double
float	double
Array	ListValues
KeyValueList	Struct

Pour éviter les erreurs de double précision, transmettez les nombres entiers sous forme de chaînes.

Champ de charge utile

Remarque : La taille maximale d'un LogEntry est de 256 Kio. Cette limite est approximative et basée sur la taille interne des données. Si nécessaire, le système tronque le champ de charge utile.

Le type de données du champ logRecord.body OTLP détermine la structure de la charge utile LogEntry :

• string : le système copie la chaîne dans le champ LogEntry.textPayload.

• Array : le système crée une chaîne à partir des éléments du tableau tout en conservant les sauts de ligne. Il copie ensuite la chaîne dans le champ LogEntry.textPayload.

• KeyValueList : le système convertit ces paires en JSON, puis remplit le champ LogEntry.jsonPayload, avec les restrictions suivantes :

  • 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.
  • Lorsque la profondeur d'imbrication d'une paire JSON est supérieure à cinq, le système tronque le contenu à une profondeur de cinq.

Champ "Gravité"

Cette section décrit comment Google Cloud Observability mappe les champs de gravité OpenTelemetry aux niveaux de gravité Cloud Logging. OpenTelemetry définit un numéro et un texte de gravité. logs.proto définit les numéros de gravité.

Google Cloud Observability détermine la gravité de la journalisation à partir du numéro de gravité OpenTelemetry, le cas échéant. Sinon, il utilise le texte de gravité. Si aucun des deux n'est défini, la gravité de la journalisation est définie sur DEFAULT.

Numéro de gravité OpenTelemetry Énumération (valeur)	Texte de gravité OpenTelemetry (les tests ne sont pas sensibles à la casse)	Gravité Cloud Logging Énumération (valeur)
SEVERITY_NUMBER_UNSPECIFIED (0)	"default" not set	DEFAULT (0)
SEVERITY_NUMBER_TRACE (1) SEVERITY_NUMBER_TRACE2 (2) SEVERITY_NUMBER_TRACE3 (3) SEVERITY_NUMBER_TRACE4 (4)	"trace" "trace2" "trace3" "trace4"	DEBUG (100)
SEVERITY_NUMBER_DEBUG (5) SEVERITY_NUMBER_DEBUG2 (6) SEVERITY_NUMBER_DEBUG3 (7) SEVERITY_NUMBER_DEBUG4 (8)	"debug" "debug2" "debug3" "debug4"	DEBUG (100)
SEVERITY_NUMBER_INFO (9) SEVERITY_NUMBER_INFO2 (10)	"info" "info2"	INFO (200)
SEVERITY_NUMBER_INFO3 (11) SEVERITY_NUMBER_INFO4 (12)	"notice" "info3" "info4"	NOTICE (300)
SEVERITY_NUMBER_WARN (13) SEVERITY_NUMBER_WARN2 (14) SEVERITY_NUMBER_WARN3 (15) SEVERITY_NUMBER_WARN4 (16)	"warning" "warn" "warn2" "warn3" "warn4"	WARNING (400)
SEVERITY_NUMBER_ERROR (17) SEVERITY_NUMBER_ERROR2 (18) SEVERITY_NUMBER_ERROR3 (19) SEVERITY_NUMBER_ERROR4 (20)	"error" "error2" "error3" "error4"	ERROR (500)
SEVERITY_NUMBER_FATAL (21) SEVERITY_NUMBER_FATAL2 (22)	"critical" "fatal" "fatal2"	CRITICAL (600)
SEVERITY_NUMBER_FATAL3 (23)	"alert" "fatal3"	ALERT (700)
SEVERITY_NUMBER_FATAL4 (24)	"emergency" "fatal4"	EMERGENCY (800)

Champ SourceLocation

Google Cloud Observability mappe le code OTLP suivant directement aux champs LogEntry. Ce mappage est possible, car ces attributs OpenTelemetry sont sémantiquement identiques aux concepts Cloud Logging.

OpenTelemetry LogRecord.attribute paire clé/valeur.	Valeur stockée dans le champ LogEntry (noms issus de la référence HTTP)	Type accepté
code.file.path: Value	sourceLocation.file	string
code.function.name: Value	sourceLocation.function	string
code.function.number: Value	sourceLocation.line	chaîne, int

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.

Configurer Google Cloud Observability pour utiliser les mappages d'exportateurs

Google Cloud Observability et l'exportateur Google Cloud pour Cloud Logging utilisent des règles différentes pour construire des objetsLogEntryà partir de données de journaux au format OTLP. Par exemple, Google Cloud Observability remplit le champ otel, mais pas les exportateurs.

Si vous souhaitez que l'observabilité Google Cloud utilise les mêmes règles de mappage que les exportateurs, apportez les modifications suivantes à vos applications qui envoient des enregistrements de journaux OTLP à l'API Telemetry :

1. Ajoutez l'attribut gcp.use_legacy_mapping à la ressource incluse dans la requête. Pour en savoir plus, consultez Ajouter ou supprimer des attributs.

   Lorsque cet attribut est défini, les événements suivants se produisent :

   1. Le champ otel n'est pas renseigné.

   2. Les attributs commençant par gcp sont supprimés, à l'exception des suivants :

      • gcp.log.name
      • gcp.insert_id

      Les deux attributs précédents sont mappés sur des champs LogEntry.

   L'ancienne règle de mappage entraîne la suppression de certains contenus par Google Cloud Observability. Toutefois, la taille des objets LogEntry est plus petite.

2. Ajoutez des processeurs à votre collecteur HTTP OTLP qui définissent les libellés de journaux suivants :

   • Définissez instrumentation_scope sur instrumentation_scope.name.
   • Définissez instrumentation_version sur instrumentation_scope.version.
   • Définissez service.name sur resource.attributes["service.name"].
   • Définissez service.namespace sur resource.attributes["service.namespace"].
   • service.instance.id : définissez cette valeur sur resource.attributes["service.instance.id"].

   Pour obtenir un exemple, consultez Migrer vers l'exportateur OTLP : processeurs.