Menulis log OTLP ke Telemetry API

Dokumen ini menunjukkan cara mengirim log OTLP langsung ke endpoint logging Telemetry (OTLP) API, telemetry.googleapis.com, dan cara melihat entri log yang di-ingest di Cloud Logging.

Sebelum memulai

Bagian ini menjelaskan cara menyiapkan lingkungan Anda untuk menggunakan Telemetry API.

Pilih atau buat Google Cloud project

Pilih project Google Cloud untuk contoh ini. Jika Anda belum memiliki project Google Cloud , buat project:

  1. Login ke akun Google Cloud Anda. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

  2. 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

  3. Verify that billing is enabled for your Google Cloud project.

  4. 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

  5. Verify that billing is enabled for your Google Cloud project.

Siapkan gcloud

Alat gcloud adalah bagian dari Google Cloud CLI. Untuk mengetahui informasi tentang cara menginstalnya, lihat Mengelola komponen Google Cloud CLI. Untuk melihat komponen gcloud CLI yang telah Anda instal, jalankan perintah berikut:

gcloud components list

Untuk mengonfigurasi gcloud CLI agar dapat digunakan, jalankan perintah berikut setelah mengganti variabel PROJECT_ID dengan ID project Google Cloud Anda.

export GOOGLE_CLOUD_PROJECT=PROJECT_ID

gcloud auth login
gcloud config set project PROJECT_ID

Mengaktifkan API

Aktifkan Cloud Logging API dan Telemetry API diGoogle Cloud project Anda. Perhatikan secara khusus Telemetry API, telemetry.googleapis.com; dokumen ini mungkin merupakan pertama kalinya Anda menemukan API ini.

Jika API muncul dalam output perintah berikut, berarti API tersebut sudah diaktifkan:

gcloud services list

Jika salah satu API belum diaktifkan, jalankan perintah yang sesuai:

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

Mendapatkan izin untuk menulis log

Untuk mendapatkan izin yang diperlukan untuk menulis log ke Telemetry API dan melihat entri log yang dibuat, minta administrator untuk memberi Anda peran IAM berikut pada pokok Anda:

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Menulis log OTLP menggunakan Telemetry API

Bagian ini menjelaskan cara membuat rekaman log berformat OTLP dan mengirim rekaman ke Telemetry API menggunakan utilitas curl.

Membuat log OTLP

Buat file JSON yang berisi rekaman log berformat OTLP. Tab berikut berisi catatan log yang sangat sederhana dan catatan multi-log yang lebih kompleks. Anda dapat memilih salah satu, atau mengirimkannya secara berurutan.

Log OTLP sederhana 

{
  "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 yang lebih kompleks 

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

Salin konten JSON dari salah satu tab ke dalam file dan simpan file tersebut.

Kedua contoh JSON ini menghasilkan entri log Cloud Logging yang ditulis terhadap jenis resource yang dimonitor gce_instance. Setiap item logRecord dalam array scopedLogs menjadi entri log Cloud Logging terpisah dalam log yang diberi nama untuk nilai kolom eventName dalam rekaman log OTLP. Untuk mengetahui informasi selengkapnya tentang cara log OTLP dipetakan ke entri log Logging, lihat artikel berikut:

Mengirim log ke Telemetry API

Setelah mengganti variabel OTLP_LOG_JSON_FILE dengan nama file yang Anda buat, gunakan perintah curl berikut untuk memposting konten file ke endpoint logging Telemetry API, 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"

Jika Anda membuat beberapa file rekaman log JSON, pastikan untuk mengubah variabel OTLP_LOG_JSON_FILE dalam perintah curl.

Perintah curl menghasilkan urutan pesan, dan jika berhasil, respons kosong ({}). Outputnya akan terlihat seperti berikut:

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

{}

Melihat log OTLP yang di-ingest

Anda dapat melihat entri log yang dihasilkan dari log OTLP dengan menggunakan salah satu alat Cloud Logging, termasuk Logs Explorer dan Observability Analytics. Bagian berikut menjelaskan cara melihat entri log menggunakan hal berikut:

Gunakan gcloud untuk melihat log

Anda dapat mengambil entri log yang baru saja dibuat menggunakan perintah gcloud logging read. Perintah berikut membatasi output ke entri log di log otlp-test-log yang ditulis dalam lima menit terakhir:

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

Entri log yang sesuai dengan log OTLP contoh terlihat seperti berikut:

Entri log sederhana 

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

Entri log yang lebih kompleks 

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

Menggunakan Logs Explorer untuk melihat log

Untuk melihat entri log yang dibuat dari log OTLP Anda di konsol Google Cloud , lakukan hal berikut:

  1. Di konsol Google Cloud , buka Logs Explorer:

    Buka Logs Explorer

    Jika Anda menggunakan kotak penelusuran untuk menemukan halaman ini, pilih hasil yang subjudulnya adalah Logging.

  2. Pilih project Google Cloud tempat Anda mengirim log OTLP.

  3. Gunakan panel Query untuk memasukkan kueri. Contoh dalam dokumen ini ditulis ke log bernama otlp-test-log. Untuk menelusuri entri dalam log ini, masukkan kueri berikut:

    LOG_ID(otlp-test-log)

  4. Klik Run query.

Pembersihan

Jika Anda membuat project baru dan tidak lagi memerlukannya, Anda dapat menghapus project tersebut untuk menghindari timbulnya biaya pada Google Cloud akun Anda.

Langkah berikutnya

Untuk mempelajari Telemetry API lebih lanjut, lihat dokumen berikut:

  • Ringkasan API menjelaskan Telemetry API untuk log, metrik, dan rekaman aktivitas.
  • v1.logs menjelaskan endpoint Telemetry API untuk logging, dan memberikan informasi mendetail tentang cara catatan log OTLP dimasukkan sebagai entri log Cloud Logging.