Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

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 LogEntry a partir del registro de OTLP, cuando ese registro se envía a Google Cloud con la API de Telemetry.

Los exportadores de Google Cloud para Cloud Logging convierten los datos de registro con formato OTLP en objetos LogEntry. Luego, envían estos datos a tu proyecto de Google Cloud con la API de Cloud Logging. Sin embargo, las reglas predeterminadas que usan Google Cloud Observability y los exportadores para construir entradas de registro son diferentes. Para obtener más información, consulta Configura Google Cloud Observability para usar las asignaciones del exportador.

Estructura general de los datos de registro con formato de OTLP

Cuando los datos de registro se envían 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 está representado por una estructura logRecord, con información sobre la fuente de esos registros, que está representada por la estructura resource.

Cuando Google Cloud Observability recibe un objeto resourceLogs, construye un 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 OTLP, consulta el 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 de HTTP)	Cómo determina el sistema el valor del campo
`logName`	El sistema usa el valor del campo `event_name` en el `LogRecord` de OTLP. Si ese campo no existe o no está configurado, el sistema usa la siguiente lista priorizada de atributos de registro de OpenTelemetry para determinar el nombre del registro: `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` Los nombres de los registros deben ser seguros para URL o se codifican 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 al tipo de recurso.
`timestamp`	El sistema usa la siguiente lista priorizada de campos de registro de OpenTelemetry para determinar el `timestamp`: `time_unix_nano` cuando no es cero. `observed_time_unix_nano` cuando no es cero. Es la 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 Cuotas de Cloud Logging.
`receiveTimestamp`	Se establece en la hora en que se transfiere 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 Campo de gravedad.
`httpRequest`	El sistema asigna los atributos `gcp.http_request` del registro a los campos `LogEntry` equivalentes. El sistema acepta estos atributos como atributos estructurados o como una cadena JSON. Para obtener más información, consulta Campo HttpRequest.
`labels`	El sistema establece este campo con los valores de los atributos del registro. Para obtener más información, consulta Campo de 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`	El sistema establece este campo según el bit menos significativo del campo `flags` del registro. Si el bit menos significativo es igual a `1`, este campo se establece en `true`; de lo contrario, permanece 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`	Para 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`. Para obtener más información, consulta Campo de Otel.
`operation`	El sistema asigna los atributos `gcp.operation` del registro a los campos `LogEntry` equivalentes. Para obtener más información, consulta Campo de operación.
Carga útil	El sistema establece la carga útil convirtiendo el cuerpo de un registro en un tipo de carga útil adecuado. Para obtener más información, consulta Campo de carga útil.

Campo HttpRequest

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

Atributos planos

En la siguiente tabla, se describe cómo Google Cloud Observability asigna atributos planos que se aplican a las solicitudes HTTP a los campos 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 de HTTP)	Tipo aceptado
`http.request.method`	`httpRequest.requestMethod`	cadena
`url.full` `http.url`	`httpRequest.requestUrl`	cadena
`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`	cadena
`client.address`	`remoteIp`	string
`server.address`	`serverIp`	string
`referrer`	`httpRequest.referer`	cadena
`latency`	`httpRequest.latency`	string, int
`cacheLookup`	`httpRequest.cacheLookup`	booleano
`cacheHit`	`httpRequest.cacheHit`	booleano
`cacheValidatedWithOriginServer`	`httpRequest.cacheValidatedWithOriginServer`	booleano
`cacheFillBytes`	`httpRequest.cacheFillBytes`	string, int
`network.protocol.version` `protocol`	`httpRequest.protocol`	cadena

Atributos anidados

En esta sección, se describe cómo Google Cloud Observability asigna 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 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",
    }
  }
}

El formato del campo gcp.http_request puede ser atributos anidados estructurados o una cadena JSON de atributos estructurados.

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

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 la entrada de registro:

OpenTelemetry `LogRecord.attribute` par clave-valor.	Valor almacenado en el siguiente campo `LogEntry` (Nombres de la referencia de 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`	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`	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`	string, int
`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`	string, int
`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 cualquier atributo que se haya asignado a campos específicos de LogEntry.

Por ejemplo, supongamos que hay atributos adjuntos a un 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 específicos de LogEntry, quedan 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, en el siguiente ejemplo, se muestra 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 de los atributos es cinco. Se trunca cualquier contenido que tenga un anidamiento más profundo.

Campo de operación

Google Cloud Observability asigna los atributos de OTLP que se aplican a la operación al campo operation de un LogEntry. En las siguientes secciones, se describe cómo el sistema asigna los atributos anidados.

El atributo gcp.operation debe contener tipos de pares clave-valor. No se admiten los nombres de atributos unificados. En el siguiente ejemplo, se ilustra un registro cuyo atributo gcp.operation contiene cuatro pares clave-valor:

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

En la siguiente tabla, se describe cómo Google Cloud Observability asigna el gcp.operation al LogEntry:

OpenTelemetry `LogRecord.attribute.operation` par clave-valor.	Valor almacenado en el siguiente campo de operación `LogEntry`	Tipo aceptado
`id`	`id`	cadena
`producer`	`httpRequest.requestUrl`	cadena
`first`	`first`	booleano
`last`	`last`	booleano

Campo de OpenTelemetry

Para 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 de protobuf Value:

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 los 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, al mismo tiempo, conserva las líneas nuevas. Luego, copia la cadena en el campo LogEntry.textPayload.
KeyValueList: El sistema convierte esos pares en JSON y, luego, propaga el campo LogEntry.jsonPayload, con las siguientes restricciones:
- Cuando un registro de OTLP contiene claves de atributo duplicadas, el sistema conserva la primera clave y descarta los atributos con claves duplicadas.
- Cuando la profundidad de anidamiento de un par JSON es mayor que 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 se establece. De lo contrario, 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)	Gravedad de Cloud Logging Enum (valor)
`SEVERITY_NUMBER_UNSPECIFIED` (0)	"default" no establecido	`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 LogEntry. Esta asignación 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 de HTTP)	Tipo aceptado
`code.file.path: Value`	`sourceLocation.file`	cadena
`code.function.name: Value`	`sourceLocation.function`	cadena
`code.function.number: Value`	`sourceLocation.line`	string, int

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. Limitado.
Tamaño máximo de cada solicitud	5 MiB	Limitado.
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. Limitado.
Longitud máxima de una clave de atributo	512 B	Las claves de etiqueta de gran tamaño se truncan cuando el registro de OTLP se convierte en un `LogEntry`. Limitado.
Longitud máxima de un valor de atributo	64 KiB	Valores de etiqueta de gran tamaño cuando el registro de OTLP se convierte en un `LogEntry`. Limitado.
Profundidad máxima de anidación de atributos	20	Las solicitudes con atributos que superan este límite se rechazan 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 establecen el número y el texto de gravedad de OpenTelemetry, 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 atributo duplicadas, el sistema conserva la primera clave y descarta los atributos con claves duplicadas.
El sistema convierte los atributos adjuntos a un registro en una cadena. Para ver un ejemplo, consulta Campo de etiquetas.
Los nombres de los registros deben ser seguros para URL o se codifican 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.

Configura Google Cloud Observability para usar las asignaciones del exportador

Google Cloud Observability y el exportador de Google Cloud para Cloud Logging usan reglas diferentes para construir objetos LogEntry a partir de datos de registro con formato OTLP. Por ejemplo, Google Cloud Observability propaga el campo otel, pero los exportadores no lo hacen.

Si deseas que Google Cloud Observability use las mismas reglas de asignación que los exportadores, realiza los siguientes cambios en las aplicaciones que envían registros de OTLP a la API de Telemetry:

Agrega el atributo gcp.use_legacy_mapping al recurso incluido en la solicitud. Para obtener más información, consulta Agrega o borra atributos.

Cuando se establece este atributo, ocurre lo siguiente:
1. El campo otel no se propaga.
2. Los atributos que comienzan con gcp se descartan con las siguientes excepciones:
  - gcp.log.name
  - gcp.insert_id
  Los dos atributos anteriores se asignan a los campos LogEntry.
La regla de asignación heredada hace que Google Cloud Observability descarte parte del contenido. Sin embargo, el tamaño de los objetos LogEntry es menor.
Agrega procesadores a tu recopilador de HTTP de OTLP que establezcan las siguientes etiquetas de registro:
- instrumentation_scope: Configurado como instrumentation_scope.name.
- instrumentation_version: configurado como instrumentation_scope.version
- service.name: configurado como resource.attributes["service.name"]
- service.namespace: Configurado como resource.attributes["service.namespace"].
- service.instance.id: Se establece en resource.attributes["service.instance.id"].
Para ver un ejemplo, consulta Migra al exportador de OTLP: Procesadores.