מעבר מ-Trace exporter לנקודת הקצה של OTLP

אתם יכולים להעביר אפליקציות Java,‏ Go,‏ Python ו-Node.js עם אינסטרומנטציה ידנית מ Google Cloud כלי לייצוא נתוני מעקב אל כלי לייצוא OTLP של OpenTelemetry בתהליך. הכלי לייצוא OTLP שולח נתוני מעקב ישירות אל Telemetry (OTLP) API בפרויקט Google Cloud באמצעות פרוטוקולי ייצוא נתמכים (gRPC או http/protobuf).

ההגדרה הזו מייצאת רק נתוני מעקב, והיא חלה רק על כלי ייצוא שפועלים בתהליך. אם האפליקציה שלכם משתמשת ב-OpenTelemetry Collector, תוכלו לעיין בדוגמאות לאינסטרומנטציה מבוססת-Collector וב-Google-Built OpenTelemetry Collector.

למה כדאי לבצע את ההעברה

‫OpenTelemetry SDKs יוצרות נתוני יומן, מדדים ומעקב בפורמט שתואם בדרך כלל לקובצי ה-proto שמוגדרים על ידי OpenTelemetry Protocol. עם זאת, יכול להיות ששדות יומרו מסוג נתונים ספציפי ל-OpenTelemetry לסוג נתונים של JSON לפני האחסון.

כשמייצאים נתונים מ Google Cloud פרויקט באמצעות כלי לייצוא Google Cloud , הכלי מבצע את הפעולות הבאות:

1. הנתונים שנרשמו מומרים מפורמט OTLP לפורמט קנייני שמוגדר על ידי Cloud Logging API,‏ Cloud Monitoring API או Cloud Trace API.
2. הנתונים שעברו טרנספורמציה נשלחים ל-API המתאים, ואז נשמרים ב Google Cloud פרויקט.

לגבי נתוני מעקב, מומלץ להעביר את האפליקציה לשימוש ב-Telemetry (OTLP) API כדי לייצא נתונים, כי הייצוא הזה לא דורש טרנספורמציה של נתונים. יכול להיות שחלק מהנתונים יאבדו במהלך המרת הנתונים. לדוגמה, יכול להיות שבפורמט הקנייני יש מגבלות נמוכות יותר לשדות מסוימים, או שחלק מהשדות של OTLP לא ממופים לשדה בפורמט הקנייני.

דוגמיות זמינות

אפליקציות לדוגמה שמוזכרות בדף הזה זמינות ב-GitHub. רוב האפליקציות מוגדרות לייצא נתוני מעקב באמצעות gRPC, כלומר הן שולחות נתונים בפורמט protobuf בפורמט gRPC דרך חיבורי HTTP/2. יש גם קוד לדוגמה לאפליקציות שמוגדרות לייצא נתוני מעקב כנתונים מקודדים ב-protobuf דרך חיבורי HTTP:

• אפליקציית Java

  אפליקציית הדוגמה מוגדרת לייצא עקבות כנתונים מקודדים ב-protobuf דרך חיבורי HTTP. אם אתם מעדיפים להשתמש ב-gRPC, תוכלו להשתמש במכשיר המדידה בדוגמה הזו. עם זאת, צריך לשנות את מאפייני המערכת שמשמשים את מודול ההגדרה האוטומטית. באפליקציה לדוגמה מצוין מייצא http/protobuf. כדי להשתמש ב-gRPC, משנים את ההגדרה הזו ל-grpc.

  מומלץ להשתמש במודול OpenTelemetry SDK Autoconfigure כדי להגדיר את ה-SDK באפליקציות Java, כמו באפליקציית הדוגמה.

• אפליקציית Go שמשתמשת ב-gRPC ואפליקציית Go שמשתמשת ב-HTTP

  יש שני מאגרי Go. באחד המאגרים, אפליקציית הדוגמה משתמשת ב-gRPC. הדוגמה במאגר השני משתמשת בנתונים שמקודדים ב-protobuf דרך חיבורי HTTP.

• מאגר Python

  מאגר המידע הזה מכיל שתי דוגמאות, אחת ל-gRPC ואחת שמשתמשת בנתונים שמקודדים ב-protobuf דרך חיבורי HTTP.

• אפליקציית Node.js

  מאגר המידע הזה מכיל שתי דוגמאות, אחת ל-gRPC ואחת שמשתמשת בנתונים שמקודדים ב-protobuf דרך חיבורי HTTP.

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

לפני שמעבירים את האפליקציה לשליחת נתוני מעקב לנקודת הקצה של OTLP, צריך להפעיל את Telemetry API ולוודא שהוקצו לכם התפקידים הנדרשים ב-IAM (הפלטפורמה לניהול זהויות והרשאות גישה). יכול להיות שתצטרכו גם להעניק תפקידי IAM לחשבון שירות.

הפעלת החיוב ו-Telemetry API

נכנסים לחשבון 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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

הגדרת ההרשאות

• כדי לוודא שלחשבון השירות שהאפליקציה שלכם משתמשת בו יש את ההרשאות הנדרשות לכתיבת נתוני יומן, מדדים ומעקב, צריך לבקש מהאדמין להקצות לחשבון השירות שהאפליקציה שלכם משתמשת בו את תפקידי ה-IAM הבאים:

  חשוב: צריך להקצות את התפקידים האלה לחשבון השירות שבו האפליקציה משתמשת, ולא לחשבון המשתמש. אם לא מקצים את התפקידים לחשבון המשתמש הנכון, יכול להיות שיופיעו שגיאות הרשאה.
  • כתיבה ביומן (roles/logging.logWriter) בפרויקט
  • כותב מדדי מעקב (roles/monitoring.metricWriter) בפרויקט
  • ‫Cloud Telemetry Traces Writer (roles/telemetry.tracesWriter) בפרויקט
  • Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) on your quota project

  במאמר הגדרת פרויקט לצורכי מכסה מוסבר איך מגדירים פרויקט לצורכי מכסה.

  מידע נוסף על Application Default Credentials (ADC) זמין במאמרים הסבר על השימוש ב-Application Default Credentials והגדרת Application Default Credentials (ADC) בסביבת פיתוח מקומית.

• כדי לקבל את ההרשאות שדרושות להצגת נתוני היומן, המדדים והמעקב, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים בפרויקט:

  • כלי הצפייה ביומנים (roles/logging.viewer)
  • צפייה ב-Monitoring (roles/monitoring.viewer)
  • משתמש Cloud Trace (roles/cloudtrace.user)

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

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

מדריך להעברה של מכשור ידני

בקטע הזה מוסבר איך לשנות את האפליקציה כך שתשלח את נתוני המעקב לפרויקט Google Cloud באמצעות Telemetry API. אי אפשר לשלוח נתוני מדדים או נתוני יומן לנקודת הקצה הזו.

הוספת יחסי תלות

השלב הראשון הוא להוסיף לאפליקציה יחסי תלות עבור כלי הייצוא של עקבות OTLP של OpenTelemetry. בוחרים את גרסאות התלות שמתאימות לאפליקציה ולמערכת ה-build.

Java

הערה: מומלץ להשתמש במודול ההגדרה האוטומטית של OpenTelemetry SDK כדי להגדיר את ה-SDK. אפליקציית הדוגמה משתמשת במודול הזה.

באפליקציית Java, מוסיפים את התלויות הבאות לסקריפט build.gradle:

implementation("io.opentelemetry:opentelemetry-exporter-otlp:1.62.0")
implementation("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure:1.62.0")

המשך

בקטע הזה מוסבר אילו שינויים צריך לבצע בתלות כשמשתמשים ב-gRPC לייצוא. אם אתם משתמשים בנתונים שמקודדים ב-protobuf דרך חיבורי HTTP לייצוא, צריך לכלול את חבילת otlptracehttp כתלות. מידע נוסף זמין במאמר אפליקציית Go שמשתמשת ב-HTTP.

אם האפליקציה שלכם ב-Go משתמשת ב-gRPC לייצוא, צריך לעדכן את הקובץ go.mod כך שיכלול את התלות הבאה:

require (
	// ...
	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.44.0
)

Python

בקטע הזה מוסבר על השינויים שצריך לבצע בתלות כשמשתמשים ב-gRPC לייצוא. אם אתם משתמשים בנתונים שמקודדים ב-protobuf דרך חיבורי HTTP לייצוא, אתם צריכים לכלול את חבילת opentelemetry-exporter-otlp-proto-http כדרישה. מידע נוסף מופיע במאגר Python.

כדי לייצא נתונים מאפליקציית Python שמשתמשת ב-gRPC, צריך להתקין את התלות הבאה או לעדכן את הקובץ requirements.txt:

opentelemetry-exporter-otlp-proto-grpc==1.42.1
grpcio==1.80.0

Node.js

בקטע הזה מוסבר אילו שינויים צריך לבצע בתלות כשמשתמשים ב-gRPC לייצוא. אם אתם משתמשים בנתונים שמקודדים ב-protobuf דרך חיבורי HTTP לייצוא, צריך לכלול את חבילת @opentelemetry/exporter-trace-otlp-proto כתלות. מידע נוסף זמין במאמר בנושא אפליקציית Node.js.

כדי לייצא נתוני מעקב מאפליקציית Node.js באמצעות gRPC, מוסיפים את התלות הבאה:

"@opentelemetry/exporter-trace-otlp-grpc": "0.221.0",
"@grpc/grpc-js": "1.14.4"

החלפת השימוש ב Google Cloud exporters ב-OTLP exporters

מעדכנים את קוד האפליקציה כך שערכת OpenTelemetry SDK מוגדרת להשתמש במייצאים של OpenTelemetry OTLP במקום במייצא Google Cloud של נתוני מעקב. השינויים הנדרשים הם ספציפיים לשפה.

Java

באפליקציית Java:

1. מוסיפים את הצהרות הייבוא הבאות:

   import io.opentelemetry.sdk.OpenTelemetrySdk;
   import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdk;

2. מעדכנים את קוד האפליקציה כדי להשתמש במודול ההגדרה האוטומטית של OpenTelemetry SDK להגדרת ה-SDK:

   public static void main(String[] args) {
     // Configure the OpenTelemetry pipeline with Auto configuration
     openTelemetrySdk = AutoConfiguredOpenTelemetrySdk.initialize().getOpenTelemetrySdk();
   
     // ...
   }

3. מגדירים את מאפייני המערכת שמשמשים את מודול ההגדרה האוטומטית בזמן הריצה. המודול הזה משתמש במאפיינים האלה כדי להפעיל את ה-SDK. אפשר גם להשתמש במשתני סביבה במקום במאפייני מערכת. מידע נוסף זמין במאמר משתני סביבה ומאפייני מערכת.

   אפליקציית הדוגמה מגדירה את מאפייני המערכת בסקריפט build.gradle:

   // You can switch the desired protocol here by changing `otel.exporter.otlp.protocol`.
   def autoconf_config = [
   	'-Dotel.exporter.otlp.endpoint=https://telemetry.googleapis.com',
   	'-Dotel.traces.exporter=otlp',
   	'-Dotel.logs.exporter=none',
   	'-Dotel.metrics.exporter=none',
   	'-Dotel.service.name=otlptrace-example',
   	'-Dotel.exporter.otlp.protocol=http/protobuf',
   	'-Dotel.java.global-autoconfigure.enabled=true',
   ]

   כמו כן, מעבירים את ההגדרה כארגומנטים של JVM:

   application {
   	mainClassName = 'com.google.cloud.opentelemetry.samples.otlptrace.OTLPTraceExample'
   	// Pass the config as JVM arguments to the Java application
   	applicationDefaultJvmArgs = autoconf_config
   }

   אם אתם מעדיפים לייצא נתוני מעקב באמצעות gRPC, אתם צריכים להגדיר את פרוטוקול OTLP ל-grpc במקום ל-http/protobuf.

המשך

בקטע הזה מוסבר אילו שינויים צריך לבצע כשמשתמשים ב-gRPC לייצוא. אם אתם משתמשים בנתונים שמקודדים ב-protobuf דרך חיבורי HTTP לייצוא, אתם צריכים לייבא את חבילת otlptracehttp ולהגדיר את כלי הייצוא עם האפשרויות המתאימות. מידע נוסף זמין במאמר בנושא אפליקציית Go שמשתמשת ב-HTTP.

אם אתם מייצאים נתונים מאפליקציית Go באמצעות gRPC, צריך להוסיף את הצהרות הייבוא הבאות:

import (
	"context"
	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"

	// ...
)

בנוסף, מעדכנים את קוד האתחול כדי להגדיר את TraceProvider באמצעות כלי הייצוא של gRPC:

// Initializes OpenTelemetry with OTLP exporters
ctx := context.Background()

// Configure gRPC client with Google Application Default Credentials
creds, err := oauth.NewApplicationDefault(ctx)
if err != nil {
	panic(err)
}

// set OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=<project_id>"
// set endpoint with OTEL_EXPORTER_OTLP_ENDPOINT=https://<endpoint>
// set OTEL_EXPORTER_OTLP_HEADERS="x-goog-user-project=<project_id>"
// Configure exporter to use the credentials
exporter, err := otlptracegrpc.New(ctx, otlptracegrpc.WithDialOption(grpc.WithPerRPCCredentials(creds)))
if err != nil {
	panic(err)
}

tp := sdktrace.NewTracerProvider(
	// For this example code we use sdktrace.AlwaysSample sampler to sample all traces.
	// In a production application, use sdktrace.TraceIDRatioBased with a desired probability.
	sdktrace.WithSampler(sdktrace.AlwaysSample()),
	sdktrace.WithBatcher(exporter))

otel.SetTracerProvider(tp)

Python

בקטע הזה מוסבר אילו שינויים צריך לבצע כשמשתמשים ב-gRPC לייצוא. אם אתם משתמשים בנתונים שמקודדים ב-protobuf דרך חיבורי HTTP לייצוא, אתם צריכים לייבא מחבילת opentelemetry.exporter.otlp.proto.http ולהגדיר את כלי הייצוא עם האפשרויות המתאימות. מידע נוסף מופיע במאגר Python.

כדי לייצא אפליקציית Python שמשתמשת ב-gRPC, מוסיפים את ההצהרות הבאות על ייבוא:

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
    OTLPSpanExporter,
)

בנוסף, מעדכנים את קוד האתחול כדי להגדיר את TraceProvider באמצעות כלי הייצוא של gRPC:

# Initialize OpenTelemetry with OTLP exporters
# channel_creds: configure Application Default Credentials
trace_provider = TracerProvider(resource=resource)
processor = BatchSpanProcessor(
    OTLPSpanExporter(
        credentials=channel_creds,
        endpoint="https://telemetry.googleapis.com:443/v1/traces",
    )
)
trace_provider.add_span_processor(processor)
trace.set_tracer_provider(trace_provider)
tracer = trace.get_tracer("my.tracer.name")

Node.js

בקטע הזה מוסבר אילו שינויים צריך לבצע כשמשתמשים ב-gRPC לייצוא. אם אתם משתמשים בנתונים שמקודדים ב-protobuf דרך חיבורי HTTP לייצוא, אתם צריכים לייבא את חבילת @opentelemetry/exporter-trace-otlp-proto. מידע נוסף זמין במאמר בנושא אפליקציית Node.js.

באפליקציית Node.js שמשתמשת ב-gRPC לייצוא, מוסיפים את ההצהרות הבאות על ייבוא:

import {OTLPTraceExporter} from '@opentelemetry/exporter-trace-otlp-grpc';

בנוסף, מעדכנים את קוד האתחול כדי להגדיר את TraceProvider באמצעות כלי הייצוא של gRPC:

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    credentials: credentials.combineChannelCredentials(
      credentials.createSsl(),
      credentials.createFromGoogleCredential({
        async getRequestHeaders(
          url?: string,
        ): Promise<{[index: string]: string}> {
          const rawHeaders = await authenticatedClient.getRequestHeaders(url);
          return Object.fromEntries(rawHeaders.entries());
        },
      }),
    ),
  }),
});
sdk.start();

הגדרת אימות

בעקבות השינויים הקודמים בהגדרת OpenTelemetry SDK, האפליקציה שלכם מוגדרת לייצא עקבות באמצעות מייצאים של OpenTelemetry OTLP, באמצעות gRPC או HTTP. לאחר מכן, צריך להגדיר את כלי הייצוא כך שישלחו את העקבות האלה אל Google Cloud הפרויקט שלכם.

כדי להגדיר אימות:

1. הגדרת כותרות אימות לקריאות לייצוא.
2. הגדרת מאפייני המשאב הנדרשים של OpenTelemetry וכותרות OTLP.
3. מגדירים את נקודת הקצה של הכלי לייצוא.

בקטע הזה מפורט כל אחד מהשלבים האלה.

הגדרת כותרות אימות לקריאות לייצוא

כדי להגדיר את כלי הייצוא באמצעות Google Cloud Application Default Credentials ‏ (ADC), צריך להוסיף ספריית אימות של Google שספציפית לשפה.

Java

אם אתם משתמשים באפליקציית Java במודול ההגדרה האוטומטית של OpenTelemetry SDK, מומלץ להשתמש גם בתוסף האימות של Google Cloud.

implementation("io.opentelemetry.contrib:opentelemetry-gcp-auth-extension:1.56.0-alpha")

המשך

אם האפליקציה שלכם ב-Go משתמשת ב-gRPC לייצוא, צריך לעדכן את הקובץ go.mod כך שיכלול את התלות הבאה:

// When using gRPC based OTLP exporter, the auth is built in.
google.golang.org/grpc v1.82.1

באפליקציית Go שמשתמשת ב-HTTP לייצוא, מעדכנים את הקובץ go.mod כך שיכלול את התלות הבאה:

// When using http based OTLP exporter, use explicit auth library
golang.org/x/oauth2 v0.36.0

Python

באפליקציית Python, מוסיפים את יחסי התלות הבאים לקובץ requirements.txt:

# Google Auth Library
google-auth==2.53.0

Node.js

באפליקציית Node.js, מוסיפים את יחסי התלות הבאים:

"google-auth-library": "10.5.0"

לאחר מכן, מעדכנים את קוד האפליקציה שבונה את כלי הייצוא של טווח OTLP כך שיוסיף את אסימוני ההרשאה שאוחזרו מהספרייה לכותרות. השלב הזה הוא ספציפי לשפה, אבל ההטמעה דומה בכל השפות.

Java

אם יש לכם אפליקציית Java שמשתמשת במודול ההגדרה האוטומטית של OpenTelemetry SDK ובתוסף האימות של Google Cloud, לא צריך לבצע פעולות מיוחדות במהלך האתחול של האפליקציה. מודול ההגדרה האוטומטית מבצע אוטומטית את השלבים שנדרשים להגדרת ADC.

המשך

בקטע הזה מוסבר אילו שינויים צריך לבצע כשמשתמשים ב-gRPC לייצוא. אם אתם משתמשים בנתונים שמקודדים ב-protobuf דרך חיבורי HTTP לייצוא, אתם צריכים לייבא את חבילת otlptracehttp ולהגדיר את כלי הייצוא כאובייקט otlptracehttp. מידע נוסף זמין במאמר בנושא אפליקציית Go שמשתמשת ב-HTTP.

אם אתם מייצאים נתונים מאפליקציית Go שמשתמשת ב-gRPC, צריך להוסיף את הצהרות הייבוא הבאות:

"google.golang.org/grpc"
"google.golang.org/grpc/credentials/oauth"

בנוסף, צריך לעדכן את קוד האתחול כדי להגדיר ADC לפני שיוצרים מופע של gRPC exporter:

// Initializes OpenTelemetry with OTLP exporters
ctx := context.Background()

// Configure gRPC client with Google Application Default Credentials
creds, err := oauth.NewApplicationDefault(ctx)
if err != nil {
	panic(err)
}

// set OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=<project_id>"
// set endpoint with OTEL_EXPORTER_OTLP_ENDPOINT=https://<endpoint>
// set OTEL_EXPORTER_OTLP_HEADERS="x-goog-user-project=<project_id>"
// Configure exporter to use the credentials
exporter, err := otlptracegrpc.New(ctx, otlptracegrpc.WithDialOption(grpc.WithPerRPCCredentials(creds)))
if err != nil {
	panic(err)
}

tp := sdktrace.NewTracerProvider(
	// For this example code we use sdktrace.AlwaysSample sampler to sample all traces.
	// In a production application, use sdktrace.TraceIDRatioBased with a desired probability.
	sdktrace.WithSampler(sdktrace.AlwaysSample()),
	sdktrace.WithBatcher(exporter))

otel.SetTracerProvider(tp)

Python

בקטע הזה מוסבר אילו שינויים צריך לבצע כשמשתמשים ב-gRPC לייצוא. אם אתם משתמשים בנתונים שמקודדים ב-protobuf דרך חיבורי HTTP לייצוא, אתם צריכים להשתמש בפרטי הכניסה שמוגדרים כברירת מחדל. צריך גם להעביר את פרטי הכניסה האלה כשיוצרים מופע של BatchSpanProcessor. מידע נוסף מופיע במאגר Python.

כדי לייצא אפליקציית Python שמשתמשת ב-gRPC, מוסיפים את ההצהרות הבאות על ייבוא:

import google.auth
import google.auth.transport.grpc
import google.auth.transport.requests
import grpc
from google.auth.transport.grpc import AuthMetadataPlugin

בנוסף, צריך לעדכן את קוד האתחול כדי להגדיר ADC לפני שיוצרים מופע של gRPC exporter:

credentials, _ = google.auth.default()
request = google.auth.transport.requests.Request()
resource = Resource.create(attributes={SERVICE_NAME: "otlp-gcp-grpc-sample"})

auth_metadata_plugin = AuthMetadataPlugin(credentials=credentials, request=request)
channel_creds = grpc.composite_channel_credentials(
    grpc.ssl_channel_credentials(),
    grpc.metadata_call_credentials(auth_metadata_plugin),
)

Node.js

בקטע הזה מוסבר אילו שינויים צריך לבצע כשמשתמשים ב-gRPC לייצוא. אם אתם משתמשים בנתונים שמקודדים ב-protobuf דרך חיבורי HTTP לייצוא, השינויים שאתם צריכים לבצע שונים מעט מאלה שמתוארים כאן. מידע נוסף מופיע בקובץ app-http-proto-export.ts שכלול באפליקציית Node.js.

באפליקציית Node.js שמשתמשת ב-gRPC לייצוא, מוסיפים את הייבוא הבא:

import {AuthClient, GoogleAuth} from 'google-auth-library';
import {credentials} from '@grpc/grpc-js';

בנוסף, צריך לעדכן את קוד האתחול כדי להגדיר ADC לפני שיוצרים מופע של gRPC exporter:

async function getAuthenticatedClient(): Promise<AuthClient> {
  const auth: GoogleAuth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/cloud-platform',
  });
  return await auth.getClient();
}

// Express App that exports traces via gRPC with protobuf
async function main() {
  const authenticatedClient: AuthClient = await getAuthenticatedClient();

  // ...
}

הגדרת מאפייני המשאב הנדרשים של OpenTelemetry

מוסיפים למשתנה הסביבה OTEL_RESOURCE_ATTRIBUTES את צמד הערכים (מפתח וערך) שמציין את הפרויקט. למפתח, צריך להשתמש ב-gcp.project_id. כערך, משתמשים במזהה של Google Cloud הפרויקט.

דוגמה:

export OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=PROJECT_ID"

אם אתם משתמשים ב-Java ומגדירים את האפליקציה לשימוש ב-Google Cloud Authentication Extension, כמו באפליקציית Java לדוגמה, אתם לא צריכים להגדיר את מזהה הפרויקט כחלק ממאפייני המשאב של OpenTelemetry. עם זאת, הגדרת המאפיין הזה לא מזיקה.

מידע נוסף על משתני סביבה של OpenTelemetry זמין במאמר הגדרה כללית של SDK.

הגדרת מזהה הפרויקט לצורכי מכסה

פרויקט המכסה הוא הפרויקט ב- Google Cloud שבו מתבצע מעקב אחר השימוש שלכם בבקשות API. מכיוון ש-Telemetry API הוא API מבוסס-לקוח, שיטת האימות קובעת אם פרויקט המכסה מזוהה באופן אוטומטי. לדוגמה, לא צריך לציין את פרויקט המכסה כשמשתמשים בחשבון שירות לצורך אימות. עם זאת, צריך לציין את פרויקט המכסה כשמשתמשים בפרטי כניסה של משתמש לאימות.

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

לדוגמה, ב-Go אפשר להגדיר את פרויקט המכסה כך:

export GOOGLE_CLOUD_QUOTA_PROJECT="QUOTA_PROJECT_ID"

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

הערה: אל תעדכנו את משתנה הסביבה OTEL_EXPORTER_OTLP_HEADERS עם צמד מפתח/ערך שמשתמש במפתח x-goog-user-project. ההגדרה הזו עלולה לגרום לכפילויות בערכים בבקשה, ולגרום לכך שפקודות ה-API ייכשלו.

הגדרת נקודת הקצה של הכלי לייצוא

מגדירים את הערך של משתנה הסביבה OTEL_EXPORTER_OTLP_ENDPOINT לנקודת הקצה של OTLP עבור Google Cloud.

דוגמה:

export OTEL_EXPORTER_OTLP_ENDPOINT=https://telemetry.googleapis.com

אם אתם משתמשים ב-Java ובמודול ההגדרה האוטומטית, אתם יכולים להגדיר את נקודת הקצה של רכיב הייצוא באמצעות מאפייני מערכת, כמו באפליקציית Java לדוגמה. לא צריך להגדיר את משתנה הסביבה של כלי הייצוא בשביל התצורה הזו.

מידע נוסף על משתני סביבה של OpenTelemetry זמין במאמר הגדרה כללית של SDK.