Questo documento mostra come inviare i log OTLP direttamente all'endpoint di logging
dell'API Telemetry (OTLP),
telemetry.googleapis.com e come visualizzare le voci di log inserite in
Cloud Logging.
Prima di iniziare
Questa sezione descrive come configurare l'ambiente per l'utilizzo dell'API Telemetry.
Seleziona o crea un Google Cloud progetto
Scegli un Google Cloud progetto per questo esempio. Se non hai ancora un progetto Google Cloud , creane uno:
- Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei carichi di lavoro.
-
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
Lo strumento gcloud fa parte di Google Cloud CLI. Per informazioni
sull'installazione, vedi
Gestione dei componenti di Google Cloud CLI.
Per visualizzare i componenti di gcloud CLI installati, esegui questo comando:
gcloud components list
Per configurare gcloud CLI per l'utilizzo, esegui i seguenti comandi dopo aver sostituito la variabile PROJECT_ID con l'identificatore del tuo progettoGoogle Cloud .
export GOOGLE_CLOUD_PROJECT=PROJECT_ID gcloud auth login gcloud config set project PROJECT_ID
Abilita API
Abilita l'API Cloud Logging e l'API Telemetry nel tuo progettoGoogle Cloud . Presta particolare attenzione all'API Telemetry, telemetry.googleapis.com; questo documento potrebbe essere la prima volta che incontri questa API.
Se le API vengono visualizzate nell'output del seguente comando, significa che sono già abilitate:
gcloud services list
Se una delle API non è abilitata, esegui il comando corrispondente:
gcloud services enable logging.googleapis.com gcloud services enable telemetry.googleapis.com
Richiedere l'autorizzazione per scrivere log
Per ottenere le autorizzazioni necessarie per scrivere log nell'API Telemetry e visualizzare le voci di log create, chiedi all'amministratore di concederti i seguenti ruoli IAM:
- Visualizzatore log (
roles/logging.viewer) sul tuo progetto - Logs Writer (
roles/logging.logWriter) sul tuo progetto - Service Usage Consumer (
roles/serviceusage.serviceUsageConsumer) sul progetto quota
Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.
Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.
Per scoprire come configurare un progetto quota, consulta Imposta il progetto quota.
Scrivere log OTLP utilizzando l'API Telemetry
Questa sezione descrive come creare un record di log in formato OTLP e inviarlo all'API Telemetry utilizzando l'utilità curl.
Crea un log OTLP
Crea un file JSON contenente un record di log formattato OTLP. Le schede seguenti contengono un record di log molto semplice e un record di log multiplo più complesso. Puoi scegliere uno o l'altro o inviarli in successione.
Log OTLP semplice
{
"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." },
}
]
}
]
}
]
}
Log OTLP più complesso
{
"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 i contenuti JSON da una delle schede in un file e salva il file.
Entrambi questi esempi JSON generano voci di log di Cloud Logging che
vengono scritte in base al tipo di risorsa monitorata
gce_instance. Ogni elemento logRecord nell'array scopedLogs
diventa una voce di log di Cloud Logging separata in un log denominato in base al valore
del campo eventName nel record di log OTLP.
Per saperne di più su come vengono mappati i log OTLP
alle voci di log di Logging, consulta quanto segue:
Invia il log all'API Telemetry
Dopo aver sostituito la variabile OTLP_LOG_JSON_FILE con il nome del file che hai creato, utilizza il seguente comando curl per pubblicare i contenuti del file nell'endpoint di logging dell'API 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"
Se crei più file di record di log JSON, assicurati di modificare la variabile OTLP_LOG_JSON_FILE nel comando curl.
Il comando curl produce una sequenza di messaggi e, se l'operazione va a buon fine, una risposta vuota ({}). L'output è simile al seguente:
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
{}
Visualizza i log OTLP importati
Puoi visualizzare le voci di log risultanti dai log OTLP utilizzando uno qualsiasi degli strumenti Cloud Logging, inclusi Esplora log e Observability Analytics. Le sezioni seguenti descrivono come visualizzare le voci di log utilizzando quanto segue:
Utilizzare gcloud per visualizzare i log
Puoi recuperare le voci di log che hai appena creato utilizzando il comando
gcloud logging read.
Il seguente comando limita l'output alle voci di log nel log otlp-test-log scritte negli ultimi cinque minuti:
gcloud logging read "LOG_ID(otlp-test-log)" --freshness=5m --format=json
Le voci di log corrispondenti ai log OTLP di esempio hanno il seguente aspetto:
Voce di log semplice
[
{
"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"
}
]
Voci di log più complesse
[
{
"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"
}
]
Utilizzo di Esplora log per visualizzare i log
Per visualizzare le voci di log create dai log OTLP nella console Google Cloud :
-
Nella console Google Cloud , vai alla pagina Esplora log:
Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Logging.
- Seleziona il progetto Google Cloud a cui hai inviato i log OTLP.
Utilizza il riquadro Query per inserire una query. Gli esempi in questo documento vengono scritti in un log denominato
otlp-test-log. Per cercare voci in questo log, inserisci la seguente query:LOG_ID(otlp-test-log)Fai clic su Esegui query.
Esegui la pulizia
Se hai creato un nuovo progetto e non ne hai più bisogno, puoi eliminarlo per evitare addebiti sul tuo account Google Cloud .
Passaggi successivi
Per saperne di più sull'API Telemetry, consulta i seguenti documenti:
- La panoramica dell'API descrive l'API Telemetry per log, metriche e tracce.
- v1.logs descrive l'endpoint dell'API Telemetry per la registrazione e fornisce informazioni dettagliate su come i record di log OTLP vengono inseriti come voci di log di Cloud Logging.