Mappage d'un enregistrement de journal OTLP à une entrée de journal

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 utilisées par Google Cloud Observability et les exportateurs pour créer des entrées de journal sont différentes. Pour en savoir plus, consultez Configurer Google Cloud Observability pour utiliser les mappages de l'exportateur.

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

Lorsque des données de journaux sont envoyées à Google Cloud à l'aide de l'API Telemetry, elles 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 journal au format OTLP, consultez la page logs.proto d'OpenTelemetry.

Comment les champs LogEntry sont définis

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

Champ LogEntry
(noms de la documentation de référence HTTP)		 Comment le système détermine la valeur du champ
logName

Le système utilise la valeur du champ event_name sur l'LogRecord OTLP. Si ce champ n'existe pas ou n'est pas défini, le système utilise la liste d'attributs d'enregistrement de journal OpenTelemetry suivante, classée par ordre de priorité, pour déterminer le nom du journal :

  • log.name
  • gcp.log.name
  • log_name
  • gcp.log_name
  • logging.googleapis.com/logName
  • service.name
  • gcp.service.name
  • service_name
  • gcp.service_name
  • event.name
  • gcp.event.name
  • event_name
  • gcp.event_name

Les noms de journaux doivent être compatibles avec les URL, sinon ils sont 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 au type de ressource.
timestamp

Le système utilise la liste hiérarchisée suivante de champs d'enregistrement de journal OpenTelemetry pour déterminer le timestamp :

  • time_unix_nano si la valeur est différente de zéro.
  • observed_time_unix_nano si la valeur est différente de zéro.
  • Heure à laquelle l'entrée de journal a été ingérée.

La durée 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éfinie sur l'heure d'ingestion de LogEntry.
severity Le système mappe la gravité OpenTelemetry de l'enregistrement de journal à une gravité Cloud Logging. Pour en savoir plus, consultez la section Champ de gravité.
httpRequest

Le système mappe les attributs gcp.http_request de l'enregistrement de journal aux champs LogEntry équivalents. Le système accepte ces attributs sous forme d'attributs structurés ou de chaîne JSON. Pour en savoir plus, consultez Champ HttpRequest.
labels Le système définit ce champ à l'aide des valeurs des attributs de l'enregistrement de journal. Pour en savoir plus, consultez Champ "Labels".
trace Le système définit ce champ sur la valeur du champ traceId de l'enregistrement de 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 de journal. La valeur doit être une chaîne hexadécimale valide de 16 caractères, sinon l'entrée est refusée.
traceSampled Le système définit ce champ en fonction du bit de poids faible du champ flags de l'enregistrement de journal. Si le bit le moins significatif est égal à 1, ce champ est défini sur true. Sinon, il n'est pas défini.
sourceLocation Le système définit ce champ sur les valeurs des attributs Code de l'enregistrement de journal. Pour en savoir plus, consultez le champ SourceLocation.
split Non défini.
apphub
apphubDestination
apphubSource
 Non défini.
otel Pour les champs des données de journal 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.
operation

Le système mappe les attributs gcp.operation de l'enregistrement de journal aux champs LogEntry équivalents. Pour en savoir plus, consultez Champ d'opération.
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 de charge utile.

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 plats

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 :

Paire clé-valeur OpenTelemetry
LogRecord.attribute
.		 Valeur stockée dans le champ
LogEntry suivant
(noms 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",
    }
  }
}

Le format du champ gcp.http_request peut être constitué d'attributs imbriqués structurés ou d'une chaîne JSON d'attributs structurés.

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

Dans le tableau, les attributs imbriqués sont indiqués par des 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 interne est attribuée à la valeur du champ d'entrée de journal :

Paire clé-valeur OpenTelemetry
LogRecord.attribute
.		 Valeur stockée dans le champ
LogEntry suivant
(noms 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 "Labels" (Libellés)

Pour déterminer les étiquettes à 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 à des champs LogEntry spécifiques, il reste les champs suivants :

    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'exemple suivant illustre la manière dont 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 des attributs est de cinq. Tout contenu ayant une imbrication plus profonde est tronqué.

Champ d'opération

Google Cloud Observability mappe les attributs OTLP qui s'appliquent à l'opération au champ operation d'un LogEntry. Les sections suivantes décrivent comment le système mappe les attributs imbriqués.

L'attribut gcp.operation doit contenir des types clé-valeur. Les noms d'attributs aplatis ne sont pas acceptés. L'exemple suivant illustre un enregistrement de journal dont l'attribut gcp.operation contient quatre paires clé-valeur :

log_record {
  attributes: {
    gcp.operation {
      "id": "abc123",
      "producer": "my_producer",
      "first": "true",
      "last": "false",
    }
  }
}

Le tableau suivant décrit comment Google Cloud Observability mappe gcp.operation à LogEntry :

Paire clé-valeur OpenTelemetry
LogRecord.attribute.operation
.		 Valeur stockée dans le champ d'opération
LogEntry suivant
 Type accepté
id id string
producer
 httpRequest.requestUrl string
first first Bool
last last Bool

Champ Otel

Pour les champs des données de journal 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 entiers sous forme de chaînes.

Champ de charge utile

Le type de données du champ OTLP logRecord.body 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 des éléments du tableau tout en conservant les nouvelles lignes. Elle copie ensuite la chaîne dans le champ LogEntry.textPayload.

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

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

Champ de 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 niveaux de gravité.

Google Cloud Observability détermine la gravité Logging à partir du numéro de gravité OpenTelemetry, s'il est défini. Sinon, il utilise le texte de gravité. Si aucune de ces options n'est définie, 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 de Cloud Logging.

Paire clé-valeur OpenTelemetry
LogRecord.attribute
.		 Valeur stockée dans le champ
LogEntry suivant
(noms 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 string, 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 OTLP resourceLogs. 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 d'étiquette trop grandes sont tronquées lorsque l'enregistrement de journal OTLP est converti en LogEntry. Limite.
Longueur maximale d'une valeur d'attribut 64 Kio Valeurs d'étiquette surdimensionnées lorsque l'enregistrement de journal OTLP est converti en LogEntry. Limite.
Profondeur maximale d'imbrication des attributs 20 Les requêtes dont les attributs dépassent cette limite sont rejetées 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 tous deux 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 de 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 la section Champ "Labels".

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

Configurer Google Cloud Observability pour utiliser les mappages de l'exportateur

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

Si vous souhaitez que Google Cloud Observability 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 aux champs LogEntry.

    L'ancienne règle de mappage entraîne l'abandon 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 étiquettes de journal suivantes :

    • 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.