Descripción general de v1.logs

En este documento, se describe cómo los datos de registro que se envían a your Google Cloud project con la API de Telemetry (OTLP) se asignan a una estructura de Cloud Logging. Esta API implementa el protocolo OTLP de OpenTelemetry. Puedes enviar datos a esta API cuando instrumentas tus aplicaciones con un otlphttp exportador y un recopilador de OpenTelemetry, o cuando usas los SDKs de OpenTelemetry.

OpenTelemetry es un proyecto de código abierto compatible con Google Cloudingenieros que garantizan la compatibilidad para transferir y visualizar tu Google Cloud telemetría.

Estructura general de los datos de registro con formato 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 procesa por lotes 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 uno LogEntry para cada logRecord. A diferencia de OTLP, que procesa por lotes la información de origen con una colección de registros individuales, cada estructura LogEntry contiene información sobre la fuente 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 logs.proto de OpenTelemetry.

Cómo se procesan los datos de registro con formato OTLP

Cuando envías una estructura resourceLogs de OTLP a la API de Telemetry, Google Cloud Observability realiza las siguientes acciones:

Para cada logRecord, el sistema crea un LogEntry.

En los siguientes documentos, se describe cómo el sistema propaga el LogEntry desde los datos de registro de OTLP:
- Asignación de registros de OTLP a entrada de registro registro.
- Asignación de atributos de OTLP a tipos de recursos de Cloud Logging.
Dado que cada LogEntry contiene información sobre el tipo de recurso de Cloud Logging correspondiente, cada LogEntry puede ser más grande que el logRecord de OTLP correspondiente.

La conversión de la estructura resourceLogs de OTLP en una serie de estructuras LogEntry puede tener pérdidas. Es decir, es posible que no puedas convertir de la estructura LogEntry a los campos resource y logRecord originales.
El LogEntry se enruta a través de receptores agregados en la jerarquía del proyecto y de receptores en el proyecto, exactamente de la misma manera que si la entrada de registro se enviara a tu proyecto con la API de Cloud Logging.

Prácticas recomendadas

Cuando instrumentes tus aplicaciones para enviar datos de seguimiento a tu Google Cloud proyecto, te recomendamos que uses un exportador que escriba datos con formato OTLP en un recopilador, que luego envíe tus datos de seguimiento a la API de Telemetry. En tu recopilador, especifica solo la URL raíz:

exporters:
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com

OpenTelemetry detecta el tipo de datos y agrega automáticamente /v1/traces, /v1/metrics o /v1/logs según corresponda. Para obtener más información, consulta Solicitud OTLP/HTTP.

Para ver ejemplos que exportan datos de seguimiento o métricas a la API de Telemetry, consulta los siguientes documentos:

Cuando no puedes usar un recopilador, puedes usar una biblioteca de OpenTelemetry que contenga un exportador de OTLP en proceso para enviar telemetría a la API de Telemetry. Para aprender a exportar datos de seguimiento directamente, consulta Exportador de Cloud Trace al extremo de OTLP.

Autenticación

Debes configurar tus exportadores con las credenciales necesarias para enviar datos a tu Google Cloud proyecto. Por ejemplo, cuando usas recopiladores, por lo general, también usas la extensión googleclientauth para autenticarte con las credenciales de Google.

Para ver un ejemplo de autenticación cuando se usa la exportación directa de datos de seguimiento, consulta Configura la autenticación. En este ejemplo, se muestra cómo configurar el exportador con tus Google Cloud Credenciales predeterminadas de la aplicación (ADC) y agregar una biblioteca de autenticación de Google específica del lenguaje a tu aplicación.

Cloud Logging y residencia de datos

De forma predeterminada, Cloud Logging enruta las entradas de registro que se originan en un proyecto a buckets de registro creados por el sistema. Los buckets de registro son recursos regionales. Puedes actualizar el receptor de registro predeterminado para enviar entradas de registro a un bucket de registros personalizado que se encuentre en la ubicación que elijas. Para obtener más información, consulta Regionaliza los registros.

Cloud Logging proporciona parámetros de configuración que puedes configurar para organizaciones y carpetas. Estos parámetros de configuración especifican la ubicación de los buckets de registro nuevos creados por el sistema, si estos buckets de registro usan claves de encriptación administradas por el cliente (CMEK) y la configuración del receptor de registro predeterminado. Para obtener más información, consulta Compatibilidad con organizaciones y carpetas.

Dónde ver los datos transferidos

Puedes ver tus datos de registro con las páginas Explorador de registros y Observability Analytics. Para obtener información, consulta lo siguiente:

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 OTLP `resourceLogs`. 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 del anidamiento 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 establecen el número de gravedad 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 atributos 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 el campo Etiquetas.
Los nombres de registro deben ser seguros para URL o estar codificados como URL durante la transferencia. Para obtener información sobre cómo se establecen los nombres de registro, consulta Cómo se establecen los campos LogEntry.