Asignación de registros de OTLP a entrada de registro

En este documento, se describe cómo Google Cloud Observability determina los campos de un objeto LogEntry a partir del registro de OTLP cuando se envía ese registro a Google Cloud con la API de Telemetry.

Estructura general de los datos de registro con formato de OTLP

Cuando se envían datos de registro a Google Cloud con la API de Telemetry, estos datos deben tener un formato coherente con OTLP. La estructura general de estos datos es la siguiente:

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

Ten en cuenta que OpenTelemetry agrupa los registros individuales, cada uno de los cuales se representa con una estructura logRecord, con información sobre la fuente de esos registros, que se representa con la estructura resource.

Cuando Google Cloud Observability recibe un objeto resourceLogs, construye un objeto LogEntry para cada logRecord. A diferencia de OTLP, que agrupa la información de origen con una colección de registros individuales, cada estructura LogEntry contiene información sobre el origen del registro y el registro en sí.

Para obtener más información sobre la estructura de los datos de registro con formato de OTLP, consulta logs.proto de OpenTelemetry.

Cómo se configuran los campos de LogEntry

Google Cloud Observability usa las siguientes reglas para determinar los valores de los campos LogEntry:

Campo `LogEntry` (Nombres de la referencia HTTP)	Cómo determina el sistema el valor del campo
`logName`	El sistema usa la siguiente lista priorizada de atributos de registros de OpenTelemetry para determinar el nombre del registro: `gcp.log_name` `log_name` `event_name` Los nombres de los registros deben ser seguros para URLs o estar codificados como URL durante la transferencia.
`resource`	El sistema usa la información establecida en el campo `resource` o infiere el recurso. Para obtener más detalles, consulta Asignación de atributos de OTLP a tipos de recursos.
`timestamp`	El sistema usa la siguiente lista priorizada de campos de registros de OpenTelemetry para determinar el `timestamp`: `time_unix_nano` cuando no es cero. `observed_time_unix_nano` cuando no es cero. Es la fecha y hora en que se transfirió la entrada de registro. El período de retención del bucket de registros que almacena los datos determina la marca de tiempo más antigua que se puede transferir. Para obtener más información, consulta las cuotas de Cloud Logging.
`receiveTimestamp`	Se establece en la hora en que se ingiere el `LogEntry`.
`severity`	El sistema asigna la gravedad de OpenTelemetry en el registro a una gravedad de Cloud Logging. Para obtener más detalles, consulta el campo Gravedad.
`httpRequest`	El sistema asigna los atributos `gcp.http_request` del registro de registro a los campos `LogEntry` equivalentes. Para obtener más información, consulta el campo HttpRequest. FIXME. Hay otros campos que se asignan a este.
`labels`	El sistema configura este campo con los valores de los atributos del registro. Para obtener más información, consulta el campo Etiquetas.
`trace`	El sistema establece este campo en el valor del campo `traceId` del registro. El valor debe ser una cadena hexadecimal válida de 32 caracteres; de lo contrario, se rechazará la entrada.
`spanId`	El sistema establece este campo en el valor del campo `spanId` del registro. El valor debe ser una cadena hexadecimal válida de 16 caracteres; de lo contrario, se rechazará la entrada.
`traceSampled`	Sin establecer
`sourceLocation`	El sistema establece este campo en los valores de los atributos Code del registro. Para obtener más información, consulta el campo SourceLocation.
`split`	Sin establecer
`apphub` `apphubDestination` `apphubSource`	Sin establecer
`otel`	En el caso de los campos de los datos de registro de OTLP que no tienen un campo equivalente en un objeto `LogEntry`, el sistema convierte los tipos de datos y, luego, agrega los datos convertidos al campo `otel`. Para obtener más información, consulta el campo Otel.
Carga útil	El sistema establece la carga útil convirtiendo el cuerpo de un registro de registro en un tipo de carga útil adecuado. Para obtener más información, consulta el campo Payload.

Campo HttpRequest

Google Cloud Observability asigna los atributos de OTLP que se aplican a las solicitudes HTTP a los campos de LogEntry. En las siguientes secciones, se describe cómo el sistema asigna atributos planos y anidados.

Atributos simples

En la siguiente tabla, se describe cómo Google Cloud Observability asigna atributos planos que se aplican a las solicitudes HTTP a los campos de LogEntry. Por ejemplo, el valor del atributo http.request.method: "GET", se establece como el valor del campo httpRequest.requestMethod en una entrada de registro:

OpenTelemetry `LogRecord.attribute` par clave-valor.	Valor almacenado en el siguiente campo `LogEntry` (nombres de la referencia HTTP)	Tipo aceptado
`http.request.method`	`httpRequest.requestMethod`	cadena
`url.full` `http.url`	`httpRequest.requestUrl`	cadena
`http.request.body.size`	`httpRequest.requestSize`	cadena, entero
`http.response.status_code`	`httpRequest.status`	cadena, entero
`http.response.body.size`	`httpRequest.responseSize`	cadena, número entero
`user_agent.original` `http.user_agent`	`httpRequest.userAgent`	cadena
`client.address`	`remoteIp`	string
`server.address`	`serverIp`	string
`referrer`	`httpRequest.referer`	cadena
`latency`	`httpRequest.latency`	cadena, entero
`cacheLookup`	`httpRequest.cacheLookup`	booleano
`cacheHit`	`httpRequest.cacheHit`	booleano
`cacheValidatedWithOriginServer`	`httpRequest.cacheValidatedWithOriginServer`	booleano
`cacheFillBytes`	`httpRequest.cacheFillBytes`	cadena, entero
`network.protocol.version` `protocol`	`httpRequest.protocol`	cadena

Atributos anidados

En esta sección, se describe cómo Google Cloud Observability asigna los atributos de OTLP anidados que se aplican a las solicitudes HTTP a los campos de un LogEntry. En el siguiente ejemplo, se ilustra un registro de registro que contiene dos atributos, cada uno de los cuales contiene al menos otro atributo:

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

En la tabla, los atributos anidados se muestran con llaves. Por ejemplo, gcp.http_request {requestMethod} significa que el atributo gcp.http_request contiene el atributo requestMethod. El valor del atributo más interno se asigna al valor del campo de entrada de registro:

OpenTelemetry `LogRecord.attribute` par clave-valor.	Valor almacenado en el siguiente campo `LogEntry` (nombres de la referencia HTTP)	Tipo aceptado
`gcp.http_request {requestMethod}` `http_request {requestMethod}`	`httpRequest.requestMethod`	cadena
`gcp.http_request {requestUrl}` `http_request {requestUrl}`	`httpRequest.requestUrl`	cadena
`gcp.http_request {requestSize}` `http_request {requestSize}`	`httpRequest.requestSize`	cadena, entero
`gcp.http_request {status}` `http_request {status}`	`httpRequest.status`	cadena, entero
`gcp.http_request {responseSize}` `http_request {responseSize}`	`httpRequest.responseSize`	cadena, número entero
`gcp.http_request {userAgent}` `http_request {userAgent}`	`httpRequest.userAgent`	cadena
`gcp.http_request {remoteIp}` `http_request {remoteIp}`	`httpRequest.remoteIp`	string
`gcp.http_request {serverIp}` `http_request {serverIp}`	`httpRequest.serverIp`	string
`gcp.http_request {referer}` `http_request {referrer}`	`httpRequest.referer`	cadena
`gcp.http_request {latency}` `http_request {latency}`	`httpRequest.latency`	cadena, entero
`gcp.http_request {cacheLookup}` `http_request {cacheLookup}`	`httpRequest.cacheLookup`	booleano
`gcp.http_request {cacheHit}` `http_request {cacheHit}`	`httpRequest.cacheHit`	booleano
`gcp.http_request { cacheValidatedWithOriginServer}` `http_request { cacheValidatedWithOriginServer}`	`httpRequest.cacheValidatedWithOriginServer`	booleano
`gcp.http_request {cacheFillBytes}` `http_request {cacheFillBytes}`	`httpRequest.cacheFillBytes`	cadena, entero
`gcp.http_request {protocol}` `http_request {protocol}`	`httpRequest.protocol`	cadena

Campo de etiquetas

Para determinar qué etiquetas adjuntar a la entrada de registro, el sistema realiza las siguientes acciones:

Quita del registro de OTLP los atributos que se hayan asignado a campos LogEntry específicos.

Por ejemplo, supongamos que hay los siguientes atributos adjuntos a un registro de registro:

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",
  },
}

Después de quitar los campos que se asignan a campos LogEntry específicos, permanecen los siguientes campos:

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

Si un atributo contiene un array o elementos JSON, el sistema convierte el valor en una cadena.

Por ejemplo, a continuación, se ilustra cómo LogEntry representa los atributos anteriores:
```
labels: {
    "log_array_attr": "[\"value1\",\"value2\"]",
    "log_json_attr": "{\"json_key\":\"json_value\"}",
    "log-string-attr": "string",
}
```
La profundidad máxima de anidación para los atributos es de cinco. Se trunca cualquier contenido que tenga una anidación más profunda.

Campo de Otel

En el caso de los campos de los datos de registro de OTLP que no tienen un campo equivalente en un LogEntry, el sistema convierte los tipos de datos y, luego, agrega los datos convertidos al campo otel. Por ejemplo, el campo otel almacena atributos de los campos resource, scope y entity.

El sistema usa las siguientes reglas para convertir los tipos de datos de OpenTelemetry en tipos Value de protobuf:

Tipo de OpenTelemetry	Tipo de protobuf
`string`	`string`
`boolean`	`bool`
`integer`	`double`
`float`	`double`
`Array`	`ListValues`
`KeyValueList`	`Struct`

Para evitar errores de doble precisión, pasa números enteros como cadenas.

Campo de carga útil

El tipo de datos del campo logRecord.body de OTLP determina la estructura de la carga útil de LogEntry:

string: El sistema copia la cadena en el campo LogEntry.textPayload.
Array: El sistema crea una cadena de los elementos del array y conserva los saltos de línea. Luego, copia la cadena en el campo LogEntry.textPayload.
KeyValueList: El sistema convierte esos pares en JSON y, luego, completa el campo LogEntry.jsonPayload con las siguientes restricciones:
- Cuando un registro de OTLP contiene claves de atributos duplicadas, el sistema conserva la primera clave y descarta los atributos con claves duplicadas.
- Cuando la profundidad de anidación de un par JSON es superior a cinco, el sistema trunca el contenido a una profundidad de cinco.

Campo de gravedad

En esta sección, se describe cómo Google Cloud Observability asigna los campos de gravedad de OpenTelemetry a los niveles de gravedad de Cloud Logging. OpenTelemetry define un número y un texto de gravedad. logs.proto define los números de gravedad.

Google Cloud Observability determina la gravedad de Logging a partir del número de gravedad de OpenTelemetry, si está configurado. De lo contrario, se usa el texto de gravedad. Si no se establece ninguno, la gravedad del registro se establece en DEFAULT.

Número de gravedad de OpenTelemetry Enum (valor)	Texto de gravedad de OpenTelemetry (las pruebas no distinguen mayúsculas de minúsculas)	Severidad de Cloud Logging Enum (valor)
`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)

Campo SourceLocation

Google Cloud Observability asigna el siguiente código de OTLP directamente a los campos de LogEntry. Este mapeo es posible porque estos atributos de OpenTelemetry son semánticamente idénticos a los conceptos de Cloud Logging.

OpenTelemetry `LogRecord.attribute` par clave-valor.	Valor almacenado en el siguiente campo `LogEntry` (nombres de la referencia HTTP)	Tipo aceptado
`code.file.path: Value`	`sourceLocation.file`	cadena
`code.function.name: Value`	`sourceLocation.function`	cadena
`code.function.number: Value`	`sourceLocation.line`	cadena, entero

Limitaciones

En esta sección, se describen los límites. También se describe cómo Google Cloud Observability controla ciertos tipos de datos.

Límites

Descripción	Valor	Notas
Cantidad máxima de registros por solicitud de OTLP	8192	Se refiere a la cantidad máxima de `logRecords` en una estructura de `resourceLogs` de OTLP. Límite.
Tamaño máximo de cada solicitud	5 MiB	Límite.
Tamaño máximo de un `LogEntry` que se crea a partir de un registro de OTLP	256 KiB	Cloud Logging trunca o descarta datos de un registro de OTLP cuando es necesario. Límite.
Longitud máxima de una clave de atributo	512 B	Las claves de etiquetas de gran tamaño se truncan cuando el registro de OTLP se convierte en un `LogEntry`. Límite.
Longitud máxima de un valor de atributo	64 KiB	Valores de etiquetas de gran tamaño cuando el registro de OTLP se convierte en un `LogEntry`. Límite.
Profundidad máxima de anidación de atributos	5	Los atributos que superan este límite se truncan cuando el registro de OTLP se convierte en un `LogEntry`.
Cantidad máxima de bytes de transferencia de registros por minuto	2.4 GB para las siguientes regiones: `asia-east1, asia-northeast1, asia-southeast1, asia-south1, europe-west1, europe-west2, europe-west3, europe-west4, us-central1, us-east4, us-west1`. 300 MB para todas las demás regiones	Cuota.

Comportamiento

Cuando se configuran tanto el número de gravedad de OpenTelemetry como el texto de gravedad, el sistema usa el número de gravedad para determinar el nivel de gravedad de Cloud Logging. Si el registro de OTLP no contiene información de gravedad, el nivel de gravedad de Cloud Logging se establece en DEFAULT.
Cuando un registro de OTLP contiene claves de atributos duplicadas, el sistema conserva la primera clave y descarta los atributos con claves duplicadas.
El sistema convierte en una cadena los atributos adjuntos a un registro de registro. Para ver un ejemplo, consulta Campo Etiquetas.
Los nombres de los registros deben ser seguros para URLs o estar codificados como URL durante la transferencia. Para obtener información sobre cómo se configuran los nombres de los registros, consulta Cómo se configuran los campos LogEntry.