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:
Para cada
logRecord, el sistema crea unLogEntry.En los siguientes documentos, se describe cómo el sistema propaga el
LogEntrya partir de los datos de registro de OTLP:- Asignación de registros de OTLP a entrada de registro registro.
- Asignación de atributos de OTLP al tipo de recurso de Cloud Logging.
Debido a que cada
LogEntrycontiene información sobre el tipo de recurso de Cloud Logging correspondiente, cadaLogEntrypuede ser más grande que ellogRecordde OTLP correspondiente.La conversión de la estructura
resourceLogsde OTLP en una serie de estructurasLogEntrypuede tener pérdidas. Es decir, es posible que no puedas convertir de la estructuraLogEntrya los camposresourceylogRecordoriginales.Los receptores agregados en la jerarquía del proyecto y los receptores del proyecto enrutan la
LogEntryexactamente 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:
- Descripción general de las muestras de instrumentación basadas en recopiladores.
- Descripción general de la transferencia de OTLP.
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:
- Rol de consumidor de Service Usage
(
roles/serviceusage.serviceUsageConsumer) en el proyecto de cuota. - Rol de escritor de telemetría de Cloud
(
roles/telemetry.writer) en el proyecto. Este rol permite que tu aplicación escriba datos de registros, métricas y seguimientos.
- Rol de consumidor de Service Usage
(
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 LogEntryque 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: 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.