Scrivere log OTLP nell'API Telemetry

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 importate 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 già un Google Cloud progetto, creane uno:

Accedi al tuo Google Cloud account. 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 workload.

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 the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

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 the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

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, consulta Gestire i 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 questi comandi dopo aver sostituito la variabile PROJECT_ID con l'identificatore del tuo Google Cloud progetto.

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 Google Cloud progetto. 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

Richiedi l'autorizzazione per scrivere i log

Per ottenere le autorizzazioni necessarie per scrivere i log nell'API Telemetry e visualizzare le voci di log create, chiedi all'amministratore di concederti i seguenti ruoli IAM nella tua entità:

Visualizzatore log (roles/logging.viewer)
Scrittore log (roles/logging.logWriter)

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.

Scrivi i 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 in formato OTLP. Le seguenti schede contengono un record di log molto semplice e un record di log multiplo più complesso. Puoi scegliere uno o l'altro oppure 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 sono scritte rispetto 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 i log OTLP vengono mappati 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 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 OTLP_LOG_JSON_FILE variabile nel curl comando.

Il comando curl produce una sequenza di messaggi e, in caso di esito positivo, 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 di Cloud Logging, inclusi Esplora log e Observability Analytics. Le seguenti sezioni descrivono come visualizzare le voci di log utilizzando:

gcloud CLI
Esplora log

Utilizza `gcloud` per visualizzare i log

Puoi recuperare le voci di log appena create utilizzando il gcloud logging read comando. 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 sono simili alle seguenti:

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"
  }
]

Utilizza Esplora log per visualizzare i log

Per visualizzare le voci di log create dai log OTLP nella Google Cloud console, procedi nel seguente modo:

Nella Google Cloud console, vai alla pagina Esplora log:
Vai a Esplora log

Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Logging.
Seleziona il Google Cloud progetto 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 le voci in questo log, inserisci la seguente query:
```
LOG_ID(otlp-test-log)
```
Fai clic su Esegui query.

Libera spazio

Se hai creato un nuovo progetto e non ne hai più bisogno, puoi eliminare il progetto per evitare di addebitare costi al tuo Google Cloud account.

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 trace.
v1.logs descrive l'endpoint dell'API Telemetry per la registrazione e fornisce informazioni dettagliate su come i record di log OTLP vengono importati come voci di log di Cloud Logging.