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.
Projekt auswählen oder erstellen Google Cloud
Wählen Sie ein Google Cloud Projekt für dieses Beispiel aus. Wenn Sie noch kein Projekt haben, erstellen Sie eines: Google Cloud
- Melden Sie sich in Ihrem Google Cloud Konto an. Wenn Sie noch kein Konto bei Google Cloudhaben, erstellen Sie eines, um die Leistung 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 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.
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 für die Verwendung zu konfigurieren. Ersetzen Sie dabei die PROJECT_ID Variable durch die ID Ihres Google 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 Ihrem
Google Cloud Projekt. Achten Sie besonders auf die
Telemetry API, telemetry.googleapis.com. Möglicherweise ist dies das erste Mal, dass Sie mit dieser API in Berührung kommen.
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 für Ihr Prinzipal zu gewähren, um die Berechtigungen zu erhalten, die Sie zum Schreiben von Logs in die Telemetry API und zum Aufrufen der erstellten Logeinträge benötigen:
-
Logs Viewer (
roles/logging.viewer) -
Logs Writer (
roles/logging.logWriter)
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.
OTLP-Logs mit der Telemetry API schreiben
In diesem Abschnitt wird beschrieben, wie Sie einen OTLP-formatierten Logeintrag erstellen und ihn mit dem Dienstprogramm curl an die Telemetry API senden.
OTLP-Log erstellen
Erstellen Sie eine JSON-Datei mit einem OTLP-formatierten Logeintrag. Die folgenden Tabs enthalten einen sehr einfachen Logeintrag und einen komplexeren Logeintrag mit mehreren Logs. Sie können einen der beiden Einträge auswählen oder beide nacheinander senden.
Einfacher OTLP-Logeintrag
{
"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." },
}
]
}
]
}
]
}
Komplexerer OTLP-Logeintrag
{
"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
für den gce_instance
überwachten Ressourcentyp geschrieben werden. Jedes logRecord-Element im Array scopedLogs wird zu einem separaten Cloud Logging-Logeintrag in einem Log, das nach dem Wert des Felds eventName im OTLP-Logeintrag benannt ist.
Weitere Informationen dazu, wie OTLP-Logs Cloud Logging-Logeinträgen zugeordnet werden, finden Sie unter:
Log an die Telemetry API senden
Ersetzen Sie die Variable OTLP_LOG_JSON_FILE durch den Namen der von Ihnen
erstellten Datei und 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-Logeinträgen erstellen, müssen Sie die
OTLP_LOG_JSON_FILE Variable im curl Befehl ändern.
Der curl-Befehl 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 allen Cloud Logging-Tools ansehen, einschließlich Log-Explorer und Observability Analytics. In den folgenden Abschnitten wird beschrieben, wie Sie Logeinträge mit den folgenden Tools ansehen:
Logs mit gcloud ansehen
Sie können gerade erstellte Logeinträge mit dem
gcloud logging read Befehl 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 Beispiel-OTLP-Logs 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:
-
Rufen Sie in der Google Cloud Console das Segment und die Seite Log-Explorer auf:
Wenn Sie diese Seite über die Suchleiste suchen, wählen Sie das Ergebnis mit der Zwischenüberschrift Logging aus.
- Wählen Sie das Google Cloud Projekt aus, an das Sie Ihre OTLP-Logs gesendet haben.
Geben Sie im Bereich Abfrage eine Abfrage ein. Die Beispiele in diesem Dokument werden in ein Log namens
otlp-test-loggeschrieben. Geben Sie die folgende Abfrage ein, um nach Einträgen in diesem Log zu suchen:LOG_ID(otlp-test-log)Klicken Sie auf Abfrage ausführen.
Bereinigen
Wenn Sie ein neues Projekt erstellt haben und es nicht mehr benötigen, können Sie es löschen um zu vermeiden, dass Ihnen Kosten für Ihr Google Cloud Konto 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 und es werden detaillierte Informationen dazu bereitgestellt, wie OTLP-Logeinträge als Cloud Logging-Logeinträge aufgenommen werden.