Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

כתיבת יומנים של OTLP אל Telemetry API

במסמך הזה מוסבר איך לשלוח יומנים בפורמט OTLP ישירות לנקודת הקצה של הרישום ביומן של Telemetry (OTLP) API,‏telemetry.googleapis.com, ואיך לצפות ברשומות היומן שהועברו ב-Cloud Logging.

לפני שמתחילים

בקטע הזה מוסבר איך להגדיר את הסביבה לשימוש ב-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 the resourcemanager.projects.create permission. Learn how to grant roles.

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.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

הגדרה של `gcloud`

הכלי gcloud הוא חלק מ-Google Cloud CLI. מידע על התקנה אפשר למצוא במאמר ניהול רכיבי Google Cloud CLI. כדי לראות את הרכיבים של ה-CLI של gcloud שהתקנתם, מריצים את הפקודה הבאה:

gcloud components list

כדי להגדיר את ה-CLI של gcloud לשימוש, מריצים את הפקודות הבאות אחרי שמחליפים את המשתנה PROJECT_ID במזהה של פרויקטGoogle Cloud .

export GOOGLE_CLOUD_PROJECT=PROJECT_ID

gcloud auth login
gcloud config set project PROJECT_ID

הפעלת ממשקי ה-API

מפעילים את Cloud Logging API ואת Telemetry API בGoogle Cloud פרויקט. כדאי לשים לב במיוחד ל-Telemetry API, telemetry.googleapis.comיכול להיות שזו הפעם הראשונה שאתם נתקלים ב-API הזה.

אם ממשקי ה-API מופיעים בפלט של הפקודה הבאה, הם כבר מופעלים:

gcloud services list

אם אחד מממשקי ה-API לא מופעל, מריצים את הפקודה המתאימה:

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

קבלת הרשאה לכתיבת יומנים

כדי לקבל את ההרשאות שדרושות בשביל לכתוב יומנים ל-Telemetry API ולצפות ברשומות היומן שנוצרו, אתם צריכים לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים בפרינציפל:

כלי הצפייה ביומנים (roles/logging.viewer)
Logs Writer (roles/logging.logWriter)

להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

יכול להיות שאפשר לקבל את ההרשאות הנדרשות גם באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש.

כתיבת יומנים בפורמט OTLP באמצעות Telemetry API

בקטע הזה מוסבר איך ליצור רשומה של יומן בפורמט OTLP ולשלוח את הרשומה ל-Telemetry API באמצעות כלי השירות curl.

יצירת יומן OTLP

יוצרים קובץ JSON שמכיל רשומה של יומן בפורמט OTLP. בכרטיסיות הבאות מוצג רשומה פשוטה מאוד ביומן ורשומה מורכבת יותר ביומן עם כמה רשומות. אפשר לבחור אחת מהאפשרויות או לשלוח את שתיהן ברצף.

יומן פשוט של 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. כל logRecord פריט במערך scopedLogs הופך לרשומה נפרדת ביומן של Cloud Logging, ביומן שנקרא על שם הערך של השדה eventName ברשומת היומן של OTLP. למידע נוסף על המיפוי של יומנים בפורמט 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, צריך לשנות את המשתנה OTLP_LOG_JSON_FILE בפקודה curl.

הפקודה 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 שהועברו

אתם יכולים לראות את רשומות היומן שנוצרות מהיומנים של OTLP באמצעות כל אחד מהכלים של Cloud Logging, כולל Logs Explorer ו-Observability Analytics. בקטעים הבאים מוסבר איך לצפות ברשומות ביומן באמצעות:

ה-CLI של gcloud
Logs Explorer

שימוש ב-`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 כדי לראות יומנים

כדי לראות את הרשומות ביומן שנוצרו מיומני OTLP ב Google Cloud מסוף:

במסוף Google Cloud , נכנסים לדף Logs Explorer:
כניסה אל Logs Explorer

אם משתמשים בסרגל החיפוש כדי למצוא את הדף הזה, בוחרים בתוצאה שכותרת המשנה שלה היא Logging.
בוחרים את הפרויקט Google Cloud שאליו שלחתם את יומני ה-OTLP.
משתמשים בחלונית Query כדי להזין שאילתה. הדוגמאות במסמך הזה נכתבות ליומן שנקרא otlp-test-log. כדי לחפש רשומות ביומן הזה, מזינים את השאילתה הבאה:
```
LOG_ID(otlp-test-log)
```
לוחצים על Run query (הפעלת שאילתה).

הסרת המשאבים

אם יצרתם פרויקט חדש ואתם כבר לא צריכים אותו, אתם יכולים למחוק את הפרויקט כדי שלא יחויב לכם תשלום בחשבון Google Cloud .

המאמרים הבאים

מידע נוסף על Telemetry API זמין במסמכים הבאים:

בסקירה הכללית על ה-API מוסבר על Telemetry API ליומנים, למדדים ולעקבות.
‫v1.logs מתאר את נקודת הקצה של Telemetry API לרישום ביומן, ומספק מידע מפורט על האופן שבו רשומות יומן של OTLP מוזנות כרשומות יומן של Cloud Logging.