Menulis log OTLP ke Telemetry API

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

Sebelum memulai

Bagian ini menjelaskan cara menyiapkan lingkungan untuk menggunakan Telemetry API.

Memilih atau membuat Google Cloud project

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

  1. Login keakun Anda. Google Cloud 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.

Menyiapkan 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 Google Cloud project 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 di Google Cloud project Anda. Perhatikan Telemetry API, telemetry.googleapis.com; dokumen ini mungkin adalah 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 tidak 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 principal 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 catatan log berformat OTLP dan mengirim catatan tersebut ke Telemetry API menggunakan utilitas curl.

Membuat log OTLP

Buat file JSON yang berisi catatan log berformat OTLP. Tab berikut berisi catatan log yang sangat sederhana dan catatan multi-log yang lebih kompleks. Anda dapat memilih salah satu atau mengirim keduanya 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, lalu simpan file tersebut.

Kedua contoh JSON ini menghasilkan entri log Cloud Logging yang ditulis terhadap jenis resource yanggce_instance dimonitor. Setiap item logRecord dalam array scopedLogs menjadi entri log Cloud Logging terpisah dalam log yang diberi nama sesuai nilai kolom eventName dalam catatan log OTLP. Untuk mengetahui informasi selengkapnya tentang cara log OTLP dipetakan ke entri log Logging, lihat hal 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 catatan 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 dimasukkan

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

Menggunakan 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 dalam 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 contoh log OTLP akan 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 di Google Cloud konsol, lakukan hal berikut:

  1. Di Google Cloud konsol, buka halaman Logs Explorer:

    Buka Logs Explorer

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

  2. Pilih Google Cloud project 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 biaya yang dikenakan ke Google Cloud akun Anda.

Langkah berikutnya

Untuk mempelajari Telemetry API lebih lanjut, lihat dokumen berikut:

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