Descripción general de v1.logs

En este documento, se describe cómo los datos de registro que se envían a tu proyecto Google Cloud con la API de Telemetry (OTLP) se asignan a una estructura de Cloud Logging. Esta API implementa el protocolo de línea 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 SDKs de OpenTelemetry.

OpenTelemetry es un proyecto de código abierto compatible con Google Cloudque cuenta con ingenieros Google Cloudpara garantizar la compatibilidad con la transferencia y visualización de tus datos de telemetría.

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 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 el logs.proto de OpenTelemetry.

Cómo se procesan los datos de registro con formato de 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 completa LogEntry a partir de los datos de registro de OTLP:

    Dado que cada LogEntry contiene información sobre el tipo de recurso de Cloud Logging correspondiente, cada LogEntry podría 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 podría ser con pérdida. Es decir, es posible que no puedas convertir la estructura de LogEntry a los campos originales resource y logRecord.

  2. Los receptores agregados en la jerarquía del proyecto y los receptores en el proyecto enrutan el LogEntry exactamente de la misma manera que si la entrada de registro se hubiera enviado a tu proyecto con la API de Cloud Logging.

Prácticas recomendadas

Cuando instrumentes tus aplicaciones para enviar datos de seguimiento a tu proyecto deGoogle Cloud , te recomendamos que uses un exportador que escriba datos con formato de OTLP en un Collector, que luego envía 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 de OTLP/HTTP.

Si deseas ver ejemplos que 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 el proceso para enviar datos de telemetría a la API de Telemetry. Para obtener información sobre cómo 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 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 Google Cloud credenciales predeterminadas de la aplicación (ADC) y agregar una biblioteca de Google Auth específica del idioma 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:

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 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 tus registros.

Cloud Logging proporciona parámetros de configuración que puedes establecer 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 en las páginas Explorador de registros y Análisis de observabilidad. Para obtener más 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 objeto 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

 Es la 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.