En este documento, se muestra cómo enviar registros de OTLP directamente al extremo de registro
de la API de Telemetry (OTLP),
telemetry.googleapis.com, y cómo ver las entradas de registro transferidas en
Cloud Logging.
Antes de comenzar
En esta sección, se describe cómo configurar tu entorno para usar la API de Telemetry.
Selecciona o crea un Google Cloud proyecto
Elige un Google Cloud proyecto para este ejemplo. Si aún no tienes un Google Cloud proyecto, crea uno:
- Accede a tu Google Cloud cuenta de. Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Configura gcloud
La herramienta gcloud forma parte de Google Cloud CLI. Para obtener información
sobre cómo instalarla, consulta
Administra los componentes de la CLI de Google Cloud.
Para ver los componentes de gcloud CLI que instalaste, ejecuta el siguiente comando:
gcloud components list
Para configurar la gcloud CLI para su uso, ejecuta los siguientes comandos después de reemplazar la variable PROJECT_ID por el identificador de tuGoogle Cloud proyecto.
export GOOGLE_CLOUD_PROJECT=PROJECT_ID gcloud auth login gcloud config set project PROJECT_ID
Habilita las APIs
Habilita la API de Cloud Logging y la API de Telemetry en tu
Google Cloud proyecto. Presta especial atención a la
API de Telemetry, telemetry.googleapis.com; es posible que esta sea la primera vez que te encuentres con esta API.
Si las APIs aparecen en el resultado del siguiente comando, significa que ya están habilitadas:
gcloud services list
Si alguna de las APIs no está habilitada, ejecuta el comando correspondiente:
gcloud services enable logging.googleapis.com gcloud services enable telemetry.googleapis.com
Obtén permiso para escribir registros
Para obtener los permisos que necesitas para escribir registros en la API de Telemetry y ver las entradas de registro creadas, pídele a tu administrador que te otorgue los siguientes roles de IAM:
- Visualizador de registros (
roles/logging.viewer) en tu proyecto - Escritor de registros (
roles/logging.logWriter) en tu proyecto - Consumidor de Service Usage (
roles/serviceusage.serviceUsageConsumer) en tu proyecto de cuota
Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.
También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.
Para obtener información sobre cómo configurar un proyecto de cuota, consulta Configura el proyecto de cuota.
Escribe registros de OTLP con la API de Telemetry
En esta sección, se describe cómo crear un registro de registro con formato OTLP y enviarlo a la API de Telemetry con la utilidad curl.
Crea un registro de OTLP
Crea un archivo JSON que contenga un registro de registro con formato OTLP. Las siguientes pestañas contienen un registro de registro muy simple y un registro de registro más complejo y múltiple. Puedes elegir uno u otro, o enviar cada uno en sucesión.
Registro de OTLP simple
{
"resourceLogs": [
{
"resource": {
"attributes": [
{"key": "gcp.project_id", "value": {"stringValue": "PROJECT_ID"}},
{"key": "cloud.platform", "value": {"stringValue": "gcp_compute_engine"}},
{"key": "zone", "value": {"stringValue": "us-central1"}},
{"key": "instance_id", "value": {"stringValue": "12345"}},
]
},
"scopeLogs": [
{
"logRecords": [
{ "eventName": "otlp-test-log",
"body": { "stringValue": "This is a trivial log message." },
}
]
}
]
}
]
}
Registro de OTLP más complejo
{
"resourceLogs": [
{
"resource": {
"attributes": [
{"key": "gcp.project_id", "value": {"stringValue": "PROJECT_ID"}},
{"key": "cloud.platform", "value": {"stringValue": "gcp_compute_engine"}},
{"key": "zone", "value": {"stringValue": "us-central1"}},
{"key": "instance_id", "value": {"stringValue": "12345"}},
]
},
"scopeLogs": [
{
"logRecords": [
{ "eventName": "otlp-test-log",
"severityText": "INFO",
"body": { "stringValue": "This is an informational message." },
"attributes": [
{"key": "string.attribute",
"value": { "stringValue": "Here's some general info."}},
{"key": "int.attribute",
"value": { "intValue": "666"}},
{"key": "double.attribute",
"value": { "doubleValue": "3.14159"}},
{"key": "boolean.attribute",
"value": { "boolValue": true}},
]
},
{ "eventName": "otlp-test-log",
"severityText": "DEBUG",
"body": { "stringValue": "This is a debug message." },
"attributes": [
{"key": "string.attribute",
"value": { "stringValue": "Here's some debug info."}},
{"key": "int.attribute",
"value": { "intValue": "42"}},
{"key": "double.attribute",
"value": { "doubleValue": "6373.392"}},
{"key": "boolean.attribute",
"value": { "boolValue": false}},
]
}
]
}
]
}
]
}
Copia el contenido JSON de cualquiera de las pestañas en un archivo y guárdalo.
Ambos ejemplos de JSON dan como resultado entradas de registro de Cloud Logging que
se escriben en el tipo de recurso supervisado gce_instance. Cada elemento logRecord del array scopedLogs se convierte en una entrada de registro de Cloud Logging separada en un registro con el nombre del valor del campo eventName en el registro de registro de OTLP.
Para obtener más información sobre cómo se asignan los registros de OTLP a las entradas de registro de Logging, consulta lo siguiente:
- Asignación de registro de OTLP a entrada de registro
- Asignación de atributos de OTLP a tipo de recurso
Envía el registro a la API de Telemetry
Después de reemplazar la variable OTLP_LOG_JSON_FILE por el nombre del archivo que
creaste, usa el siguiente comando curl para publicar el contenido del archivo en
el extremo de registro de la API de Telemetry,
https://telemetry.googleapis.com/v1/logs:
curl -i -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" -H "X-Goog-User-Project: ${PROJECT_ID}" \
-d @OTLP_LOG_JSON_FILE \
"https://telemetry.googleapis.com/v1/logs"
Si creas varios archivos de registros de registro JSON, asegúrate de cambiar la
OTLP_LOG_JSON_FILE variable en el curl comando.
El comando curl produce una secuencia de mensajes y, si se ejecuta correctamente, una respuesta vacía ({}). El resultado es similar al siguiente:
HTTP/2 200
x-google-esf-cloud-client-params: backend_service_name: "telemetry.googleapis.com" backend_fully_qualified_method: "opentelemetry.proto.collector.logs.v1.LogsService.Export"
[...]
x-google-gfe-response-code-details-trace: response_code_set_by_backend
x-google-gfe-response-body-transformations: gunzipped,chunked
x-google-shellfish-status: CA0gBEBG
x-google-gfe-version: 2.970.1
alt-svc: h3=":443"; ma=2592000,h3-29=":443"; ma=2592000
accept-ranges: none
{}
Visualiza los registros de OTLP transferidos
Puedes ver las entradas de registro que resultan de tus registros de OTLP con cualquiera de las herramientas de Cloud Logging, incluidos el Explorador de registros y Observability Analytics. En las siguientes secciones, se describe cómo ver las entradas de registro con lo siguiente:
Usa gcloud para ver registros
Puedes recuperar las entradas de registro que acabas de crear con el
gcloud logging read comando.
El siguiente comando restringe el resultado a las entradas de registro del registro otlp-test-log que se escribieron en los últimos cinco minutos:
gcloud logging read "LOG_ID(otlp-test-log)" --freshness=5m --format=json
Las entradas de registro que corresponden a los registros de OTLP de muestra son similares a las siguientes:
Entrada de registro simple
[
{
"insertId": "1yt9bu7a0",
"logName": "projects/PROJECT_ID/logs/otlp-test-log",
"otel": {
"resource": {
"attributes": {
"cloud.platform": "gcp_compute_engine",
"gcp.project_id": "PROJECT_ID",
"instance_id": "12345",
"zone": "us-central1"
}
}
},
"receiveTimestamp": "2026-03-18T20:17:00.128801819Z",
"resource": {
"labels": {
"instance_id": "12345",
"project_id": "PROJECT_ID",
"zone": "us-central1"
},
"type": "gce_instance"
},
"textPayload": "This is a trivial log message.",
"timestamp": "2026-03-18T20:17:00.128801819Z"
}
]
Entradas de registro más complejas
[
{
"insertId": "1aw7fsja1",
"labels": {
"boolean.attribute": "false",
"double.attribute": "6373.39",
"int.attribute": "42",
"string.attribute": "Here's some debug info."
},
"logName": "projects/PROJECT_ID/logs/otlp-test-log",
"otel": {
"resource": {
"attributes": {
"cloud.platform": "gcp_compute_engine",
"gcp.project_id": "PROJECT_ID",
"instance_id": "12345",
"zone": "us-central1"
}
}
},
"receiveTimestamp": "2026-03-16T17:11:19.461096569Z",
"resource": {
"labels": {
"instance_id": "12345",
"project_id": "PROJECT_ID",
"zone": "us-central1"
},
"type": "gce_instance"
},
"severity": "DEBUG",
"textPayload": "This is a debug message.",
"timestamp": "2026-03-16T17:11:19.461096569Z"
},
{
"insertId": "1aw7fsja0",
"labels": {
"boolean.attribute": "true",
"double.attribute": "3.14159",
"int.attribute": "666",
"string.attribute": "Here's some general info."
},
"logName": "projects/PROJECT_ID/logs/otlp-test-log",
"otel": {
"resource": {
"attributes": {
"cloud.platform": "gcp_compute_engine",
"gcp.project_id": "PROJECT_ID",
"instance_id": "12345",
"zone": "us-central1"
}
}
},
"receiveTimestamp": "2026-03-16T17:11:19.461096569Z",
"resource": {
"labels": {
"instance_id": "12345",
"project_id": "PROJECT_ID",
"zone": "us-central1"
},
"type": "gce_instance"
},
"severity": "INFO",
"textPayload": "This is an informational message.",
"timestamp": "2026-03-16T17:11:19.461096569Z"
}
]
Usa el Explorador de registros para ver registros
Para ver las entradas de registro creadas a partir de tus registros de OTLP en la Google Cloud consola, haz lo siguiente:
-
En la Google Cloud consola de, ve a la Explorador de registros del segmento:
Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Logging.
- Selecciona el Google Cloud proyecto al que enviaste tus registros de OTLP.
Usa el panel Consulta para ingresar una consulta. Las muestras de este documento se escriben en un registro llamado
otlp-test-log. Para buscar entradas en este registro, ingresa la siguiente consulta:LOG_ID(otlp-test-log)Haz clic en Ejecutar consulta.
Limpia
Si creaste un proyecto nuevo y ya no lo necesitas, puedes borrarlo para evitar que se generen cargos en tu Google Cloud cuenta.
¿Qué sigue?
Para obtener más información sobre la API de Telemetry, consulta los siguientes documentos:
- En la descripción general de la API, se describe la API de Telemetry para registros, métricas y seguimientos.
- En v1.logs, se describe el extremo de la API de Telemetry para el registro y se proporciona información detallada sobre cómo se transfieren los registros de OTLP como entradas de registro de Cloud Logging.