OTLP-Logs in die Telemetry API schreiben

Diese Funktion unterliegt den „Bedingungen für Pre-GA-Angebote“ im Abschnitt „Allgemeine Dienstbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA‑Funktionen stehen in der vorliegenden Form zur Verfügung und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie unter den Beschreibungen der Startphase.

In diesem Dokument wird gezeigt, wie Sie OTLP-Logs direkt an den Logging-Endpunkt der Telemetry (OTLP) API, telemetry.googleapis.com, senden und wie Sie die aufgenommenen Logeinträge in Cloud Logging ansehen.

Hinweis

In diesem Abschnitt wird beschrieben, wie Sie Ihre Umgebung für die Verwendung der Telemetry API einrichten.

Google Cloud Projekt auswählen oder erstellen

Wählen Sie ein Google Cloud -Projekt für dieses Beispiel aus. Wenn Sie noch kein Google Cloud -Projekt haben, erstellen Sie eines:

Melden Sie sich in Ihrem Google Cloud -Konto an. Wenn Sie mit Google Cloudnoch nicht vertraut sind, erstellen Sie ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

gcloud einrichten

Das Tool gcloud ist Teil der Google Cloud CLI. Informationen zur Installation finden Sie unter Komponenten der Google Cloud CLI verwalten. Führen Sie den folgenden Befehl aus, um die installierten gcloud CLI-Komponenten aufzurufen:

gcloud components list

Führen Sie die folgenden Befehle aus, um die gcloud CLI zu konfigurieren. Ersetzen Sie dabei die Variable PROJECT_ID durch die ID IhresGoogle Cloud -Projekts.

export GOOGLE_CLOUD_PROJECT=PROJECT_ID

gcloud auth login
gcloud config set project PROJECT_ID

APIs aktivieren

Aktivieren Sie die Cloud Logging API und die Telemetry API in IhremGoogle Cloud -Projekt. Achten Sie besonders auf die Telemetry API, telemetry.googleapis.com. Möglicherweise ist dies das erste Mal, dass Sie auf diese API stoßen.

Wenn die APIs in der Ausgabe des folgenden Befehls angezeigt werden, sind sie bereits aktiviert:

gcloud services list

Wenn eine der APIs nicht aktiviert ist, führen Sie den entsprechenden Befehl aus:

gcloud services enable logging.googleapis.com
gcloud services enable telemetry.googleapis.com

Berechtigung zum Schreiben von Logs erhalten

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Schreiben von Logs in die Telemetry API und zum Aufrufen der erstellten Logeinträge benötigen:

• Loganzeige (roles/logging.viewer) für Ihr Projekt
• Log-Autor (roles/logging.logWriter) für Ihr Projekt
• Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) für Ihr Kontingentprojekt

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Informationen zum Konfigurieren eines Kontingentprojekts finden Sie unter Kontingentprojekt festlegen.

OTLP-Logs mit der Telemetry API schreiben

In diesem Abschnitt wird beschrieben, wie Sie einen OTLP-formatierten Logeintrag erstellen und ihn mit dem curl-Dienstprogramm an die Telemetry API senden.

OTLP-Log erstellen

Erstellen Sie eine JSON-Datei mit einem OTLP-formatierten Logdatensatz. Auf den folgenden Tabs finden Sie einen sehr einfachen Logeintrag und einen komplexeren Logeintrag mit mehreren Zeilen. Sie können eine der beiden Optionen auswählen oder beide nacheinander senden.

Einfaches OTLP-Log

{
  "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." },
          }
        ]
      }
      ]
    }
  ]
}

Komplexeres OTLP-Log

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

Kopieren Sie den JSON-Inhalt von einem der beiden Tabs in eine Datei und speichern Sie die Datei.

Beide JSON-Beispiele führen zu Cloud Logging-Logeinträgen, die dem überwachten Ressourcentyp gce_instance zugeordnet sind. Jedes logRecord-Element im scopedLogs-Array wird zu einem separaten Cloud Logging-Logeintrag in einem Log, das nach dem Wert des Felds eventName im OTLP-Logdatensatz benannt ist. Weitere Informationen dazu, wie OTLP-Logs Logging-Logeinträgen zugeordnet werden, finden Sie unter:

• Zuordnung von OTLP-Logdatensatz zu Logeintrag
• Zuordnung von OTLP-Attributen zu Ressourcentypen

Log an die Telemetry API senden

Nachdem Sie die Variable OTLP_LOG_JSON_FILE durch den Namen der von Ihnen erstellten Datei ersetzt haben, verwenden Sie den folgenden curl-Befehl, um den Inhalt der Datei an den Logging-Endpunkt der Telemetry API, https://telemetry.googleapis.com/v1/logs, zu senden:

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"

Wenn Sie mehrere Dateien mit JSON-Logdatensätzen erstellen, müssen Sie die Variable OTLP_LOG_JSON_FILE im Befehl curl ändern.

Der Befehl curl erzeugt eine Reihe von Nachrichten und bei Erfolg eine leere Antwort ({}). Die Ausgabe sieht in etwa so aus:

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

{}

Aufgenommene OTLP-Logs ansehen

Sie können die Logeinträge, die aus Ihren OTLP-Logs resultieren, mit einem der Cloud Logging-Tools ansehen, z. B. mit dem Log-Explorer und Observability Analytics. In den folgenden Abschnitten wird beschrieben, wie Sie Logeinträge mit den folgenden Tools aufrufen:

• Die gcloud-CLI
• Log-Explorer

gcloud zum Aufrufen von Logs verwenden

Mit dem Befehl gcloud logging read können Sie die gerade erstellten Logeinträge abrufen. Der folgende Befehl beschränkt die Ausgabe auf die Logeinträge im Log otlp-test-log, die in den letzten fünf Minuten geschrieben wurden:

gcloud logging read "LOG_ID(otlp-test-log)" --freshness=5m --format=json

Die Logeinträge, die den OTLP-Beispiellogs entsprechen, sehen so aus:

Einfacher Logeintrag

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

Komplexere Logeinträge

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

Logs mit dem Log-Explorer ansehen

So rufen Sie die Logeinträge auf, die aus Ihren OTLP-Logs in der Google Cloud Console erstellt wurden:

1. Rufen Sie in der Google Cloud Console das Segment und die Seite Log-Explorer auf:

   Zum Log-Explorer

   Wenn Sie diese Seite über die Suchleiste suchen, wählen Sie das Ergebnis mit der Zwischenüberschrift Logging aus.

2. Wählen Sie das Google Cloud -Projekt aus, an das Sie Ihre OTLP-Logs gesendet haben.

3. Geben Sie im Bereich Abfrage eine Abfrage ein. Die Beispiele in diesem Dokument werden in ein Log namens otlp-test-log geschrieben. Wenn Sie in diesem Log nach Einträgen suchen möchten, geben Sie die folgende Abfrage ein:

   LOG_ID(otlp-test-log)
   

4. Klicken Sie auf Abfrage ausführen.

Bereinigen

Wenn Sie ein neues Projekt erstellt haben und es nicht mehr benötigen, können Sie das Projekt löschen, um zu vermeiden, dass Ihrem Google Cloud -Konto Gebühren in Rechnung gestellt werden.

Nächste Schritte

Weitere Informationen zur Telemetry API finden Sie in den folgenden Dokumenten:

• In der API-Übersicht wird die Telemetry API für Logs, Messwerte und Traces beschrieben.
• Unter v1.logs wird der Telemetry API-Endpunkt für das Logging beschrieben. Außerdem finden Sie dort detaillierte Informationen dazu, wie OTLP-Logdatensätze als Cloud Logging-Logeinträge aufgenommen werden.