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

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

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

אם האפליקציה שלכם מסתמכת על OpenTelemetry Collector כדי לשלוח נתוני מעקב לפרויקט Google Cloud , המאמר הזה לא רלוונטי:

• דוגמאות לאינסטרומנטציה מופיעות במאמר דוגמאות לאינסטרומנטציה שמבוססת על Collector.
• מידע על כלי איסוף זמין במאמר Google-Built OpenTelemetry Collector.

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

ערכות OpenTelemetry SDK יוצרות נתוני יומן, מדדים ועקבות בפורמט שתואם בדרך כלל לקובצי הפרוטו שמוגדרים על ידי OpenTelemetry Line 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 over HTTP/2. יש גם קוד לדוגמה לאפליקציות שמוגדרות לייצא נתוני מעקב כנתונים מקודדים ב-protobuf דרך חיבורי HTTP:

• אפליקציית Java

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

  מומלץ להשתמש במודול ההגדרה האוטומטית של OpenTelemetry SDK כדי להגדיר את ה-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.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. 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.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

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

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

  חשוב: צריך להקצות את התפקידים האלה לחשבון השירות שבו האפליקציה משתמשת, ולא לחשבון המשתמש שלכם. אם לא תקצו את התפקידים לחשבון המשתמש הנכון, יכול להיות שתקבלו שגיאות הרשאה.
  • כתיבה ביומן (roles/logging.logWriter) בפרויקט
  • כותב מדדים של Monitoring (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.218.0",
"@grpc/grpc-js": "1.14.4"

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

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

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(authenticatedClient),
    ),
  }),
});
sdk.start();

הגדרת אימות

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

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

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

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

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

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

Java

אם אתם משתמשים במודול ההגדרה האוטומטית של OpenTelemetry SDK באפליקציית Java, מומלץ להשתמש גם בתוסף האימות של 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.81.1

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

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

Python

באפליקציית Python, מוסיפים את ההצהרות הבאות על ייבוא:

# Google Auth Library
google-auth==2.53.0

Node.js

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

"google-auth-library": "9.15.1"

לאחר מכן, מעדכנים את קוד האפליקציה שבונה את כלי הייצוא של טווח 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 לדוגמה. לא צריך להגדיר את משתנה הסביבה של ה-exporter בשביל התצורה הזו.

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