Descripción general de v1.logs

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

OpenTelemetry es un proyecto de código abierto respaldado por Google Cloudcon ingenieros de Google Cloud asignados para garantizar la compatibilidad con la transferencia y la visualización de tu 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 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 la 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:

  1. Para cada logRecord, el sistema crea un LogEntry.

    En los siguientes documentos, se describe cómo el sistema propaga el LogEntry a partir de los datos de registro de OTLP:

    Debido a 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.

  2. Los receptores agregados en la jerarquía del proyecto y los receptores del proyecto enrutan la LogEntry 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 instrumentas tus aplicaciones para enviar datos de seguimiento a tu proyecto deGoogle Cloud , 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 HTTP de OTLP.

Para ver ejemplos en los que se exportan datos de seguimiento o de 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 de forma directa, consulta Exportador de Cloud Trace al extremo de OTLP.

Autenticación

Debes configurar tus exportadores con las credenciales necesarias para enviar datos a tu proyecto de Google Cloud . Por ejemplo, cuando usas recopiladores, por lo general, 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 ilustra cómo configurar el exportador con tus credenciales predeterminadas de la aplicación (ADC) de Google Cloud y agregar una biblioteca de Google Auth específica del lenguaje a tu aplicación.

Para enviar datos de telemetría a tu proyecto de Google Cloud con la API de Telemetry, también debes hacer lo siguiente:

  • Configura un proyecto de cuota. Para obtener más información, consulta Configura el proyecto de cuota.

  • Otorga los siguientes roles de Identity and Access Management (IAM) al usuario o a la cuenta de servicio que usa la 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 registros creados por el sistema. Los buckets de registros son recursos regionales. Puedes actualizar el receptor de registros 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 establecer para organizaciones y carpetas. Esta configuración especifica la ubicación de los buckets de registros nuevos creados por el sistema, si estos buckets de registros usan claves de encriptación administradas por el cliente (CMEK) y la configuración del receptor de registros predeterminado. Para obtener más información, consulta Asistencia para organizaciones y carpetas.

Dónde ver los datos transferidos

Puedes ver tus datos de registro con las páginas Explorador de registros y Estadísticas de observabilidad. 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 resourceLogs de OTLP. Límite.
Tamaño máximo de cada solicitud 5 MiB Límite.
Tamaño acumulativo máximo de los objetos LogEntry convertidos por solicitud 64 MiB Incluye metadatos replicados de Resource y InstrumentationScope por LogEntry. Cloud Logging rechaza los registros que superan este límite del sistema con un error INVALID_ARGUMENT. Límite.
Tamaño máximo de un LogEntry
que se crea a partir de un registro de OTLP
256 KiB Cloud Logging rechaza los registros de registro cuyo LogEntry convertido supera este tamaño con un error INVALID_ARGUMENT. Límite.
Longitud máxima de una clave de atributo 512 B Se aplica a los atributos LogRecord, Resource y InstrumentationScope. Cloud Logging rechaza las claves de gran tamaño con un error INVALID_ARGUMENT. Límite.
Longitud máxima de un valor de atributo 64 KiB Se aplica a los atributos LogRecord, Resource y InstrumentationScope. Cloud Logging rechaza los valores de gran tamaño con un error INVALID_ARGUMENT. Límite.
Profundidad máxima de anidación de atributos 20 Se aplica a los atributos LogRecord y Resource. Cloud Logging rechaza las solicitudes que superan esta profundidad con un error INVALID_ARGUMENT. Límite.
Cantidad máxima de atributos de recursos por objeto ResourceLogs 1,024 Cloud Logging rechaza los registros en objetos ResourceLogs que superan este límite del sistema con un error INVALID_ARGUMENT. Límite.
Tamaño máximo de las URLs de esquema 8,192 bytes Se aplica a ResourceLogs.schema_url y ScopeLogs.schema_url. Cloud Logging rechaza los registros con URLs de esquema de gran tamaño con un error INVALID_ARGUMENT. Límite.
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.

Cuotas

Para obtener información sobre las cuotas asociadas con la API de Telemetry, consulta Límites de la API de Telemetry.