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 proyecto de Google Cloud
Elige un Google Cloud proyecto para este ejemplo. Si aún no tienes un proyecto Google Cloud , crea uno:
- Accede a tu cuenta de Google Cloud . 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.
Configurar gcloud
La herramienta gcloud forma parte de Google Cloud CLI. Para obtener información sobre cómo instalarlo, consulta Administra los componentes de Google Cloud CLI.
Para ver los componentes de gcloud CLI que instalaste, ejecuta el siguiente comando:
gcloud components list
Para configurar gcloud CLI para su uso, ejecuta los siguientes comandos después de reemplazar la variable PROJECT_ID por el identificador de tu proyectoGoogle Cloud .
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 proyecto deGoogle Cloud . Presta especial atención a la API de Telemetry, telemetry.googleapis.com, ya que es posible que esta sea la primera vez que te encuentras con ella.
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
Cómo obtener permiso para escribir registros
Para obtener los permisos que necesitas para escribir registros en la API de Telemetría y ver las entradas de registro creadas, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu principal:
-
Visor de registro (
roles/logging.viewer) -
Escritor de registros (
roles/logging.logWriter)
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.
Escribe registros de OTLP con la API de Telemetry
En esta sección, se describe cómo crear un registro de registro con formato de 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 de OTLP. Las siguientes pestañas contienen un registro muy simple y un registro más complejo con varios registros. Puedes elegir una u otra, o bien enviarlas de forma sucesiva.
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 generan 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 independiente de Cloud Logging en un registro con el nombre del valor del campo eventName en el 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 registros de OTLP a entrada de registro registro
- Asignación de atributos de OTLP a tipos de recursos
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 JSON, asegúrate de cambiar la variable OTLP_LOG_JSON_FILE en el comando curl.
El comando curl produce una secuencia de mensajes y, si se ejecuta correctamente, una respuesta vacía ({}). El resultado se ve 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
{}
Cómo ver 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 los siguientes métodos:
Usa gcloud para ver los registros
Puedes recuperar las entradas de registro que acabas de crear con el comando gcloud logging read.
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 se ven de la siguiente manera:
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 consola de Google Cloud , ve a la página Explorador de registros del :
Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Logging.
- Selecciona el proyecto Google Cloud 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.
Realiza una limpieza
Si creaste un proyecto nuevo y ya no lo necesitas, puedes borrarlo para evitar que se generen cargos en tu cuenta de Google Cloud .
¿Qué sigue?
Para obtener más información sobre la API de Telemetry, consulta los siguientes documentos:
- En Descripción general de la API, se describe la API de Telemetry para registros, métricas y seguimientos.
- v1.logs describe el extremo de la API de Telemetry para el registro y proporciona información detallada sobre cómo se incorporan los registros de OTLP como entradas de registro de Cloud Logging.