本文說明如何將 OTLP 記錄直接傳送至 Telemetry (OTLP) API 的記錄端點，以及如何在 Cloud Logging 中查看擷取的記錄項目。telemetry.googleapis.com
事前準備
本節說明如何設定環境，以使用 Telemetry API。
選取或建立 Google Cloud 專案
選擇這個範例的 Google Cloud 專案。如果您還沒有 Google Cloud 專案，請建立一個：
- 登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。
-
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
gcloud 工具是 Google Cloud CLI 的一部分。如要瞭解如何安裝，請參閱「管理 Google Cloud CLI 元件」。如要查看已安裝的 gcloud CLI 元件，請執行下列指令：
gcloud components list
如要設定 gcloud CLI，請將 PROJECT_ID 變數替換成Google Cloud 專案的 ID，然後執行下列指令。
export GOOGLE_CLOUD_PROJECT=PROJECT_ID gcloud auth login gcloud config set project PROJECT_ID
啟用 API
在Google Cloud 專案中啟用 Cloud Logging API 和 Telemetry API。請特別注意 Telemetry API telemetry.googleapis.com，您可能第一次遇到這個 API。
如果下列指令的輸出內容顯示這些 API，表示 API 已啟用：
gcloud services list
如果任一 API 未啟用，請執行對應的指令：
gcloud services enable logging.googleapis.com gcloud services enable telemetry.googleapis.com
取得寫入記錄的權限
如要取得將記錄寫入 Telemetry API 及查看所建立記錄項目所需的權限，請要求系統管理員授予您主體的下列 IAM 角色：
如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。
使用 Telemetry API 寫入 OTLP 記錄
本節說明如何建立 OTLP 格式的記錄檔記錄，並使用 curl 公用程式將記錄傳送至 Telemetry API。
建立 OTLP 記錄
建立包含 OTLP 格式記錄的 JSON 檔案。下列分頁包含非常簡單的記錄，以及較複雜的多重記錄。你可以選擇其中一種，或依序傳送兩種訊息。
簡單的 OTLP 記錄
{
"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." },
}
]
}
]
}
]
}
更複雜的 OTLP 記錄
{
"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}},
]
}
]
}
]
}
]
}
將任一分頁的 JSON 內容複製到檔案中，然後儲存檔案。
這兩個 JSON 範例都會產生 Cloud Logging 記錄項目，並根據 gce_instance 受監控資源類型寫入。scopedLogs 陣列中的每個 logRecord 項目，都會成為 Cloud Logging 中的個別記錄項目，記錄名稱則為 OTLP 記錄中 eventName 欄位的值。如要進一步瞭解如何將 OTLP 記錄對應至 Logging 記錄項目，請參閱下列內容：
將記錄檔傳送至 Telemetry API
將 OTLP_LOG_JSON_FILE 變數替換為您建立的檔案名稱後，請使用下列 curl 指令，將檔案內容發布至 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"
如果您建立多個 JSON 記錄檔，請務必變更 curl 指令中的 OTLP_LOG_JSON_FILE 變數。
curl 指令會產生一連串訊息，如果成功，則會產生空白回應 ({})。輸出內容類似於以下內容：
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
{}
查看擷取的 OTLP 記錄
您可以使用任何 Cloud Logging 工具 (包括 Logs Explorer 和 Observability Analytics)，查看 OTLP 記錄產生的記錄項目。下列各節說明如何使用下列項目查看記錄項目：
使用 gcloud 查看記錄檔
您可以使用 gcloud logging read 指令，擷取剛建立的記錄項目。下列指令會將輸出內容限制為 otlp-test-log 記錄檔中，過去五分鐘內寫入的記錄項目：
gcloud logging read "LOG_ID(otlp-test-log)" --freshness=5m --format=json
與範例 OTLP 記錄對應的記錄項目如下所示：
簡單的記錄項目
[
{
"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"
}
]
更複雜的記錄項目
[
{
"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 Explorer 查看記錄檔
如要在 Google Cloud 控制台中查看從 OTLP 記錄建立的記錄項目，請執行下列操作：
-
前往 Google Cloud 控制台的 「Logs Explorer」頁面：
如果您是使用搜尋列尋找這個頁面，請選取子標題為「Logging」的結果。
- 選取傳送 OTLP 記錄的 Google Cloud 專案。
使用「Query」(查詢) 窗格輸入查詢。本文中的範例會寫入名為
otlp-test-log的記錄檔。如要搜尋這個記錄檔中的項目，請輸入下列查詢：LOG_ID(otlp-test-log)按一下「執行查詢」
清除所用資源
如果您建立新專案，且現在已不再需要該項專案，請刪除專案，以免系統向您的 Google Cloud 帳戶收費。
後續步驟
如要進一步瞭解 Telemetry API，請參閱下列文件：
- API 總覽說明記錄、指標和追蹤記錄的 Telemetry API。
- v1.logs 說明用於記錄的 Telemetry API 端點，並詳細說明如何將 OTLP 記錄記錄擷取為 Cloud Logging 記錄項目。