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

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

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

למה כדאי לעבור

ערכות ה-SDK של OpenTelemetry יוצרות נתוני יומנים, מדדים ומעקב בפורמט שתואם בדרך כלל לקובצי ה-proto שמוגדרים על ידי פרוטוקול OpenTelemetry. עם זאת, יכול להיות שהשדות יומרו מסוג נתונים ספציפי ל-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 (roles/telemetry.tracesWriter) בפרויקט
  • Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) בפרויקט המכסות

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

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

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

  • צפייה ביומנים (roles/logging.viewer)
  • צפייה במעקב (roles/monitoring.viewer)
  • Cloud Trace User (roles/cloudtrace.user)

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

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

מדריך להעברת נתונים (מיגרציה) לצורך הטמעה ידנית

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

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

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

Java

הערה: מומלץ להשתמש במודול OpenTelemetry SDK Autoconfigure כדי להגדיר את ה-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 במייצאים של OTLP

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

Java

באפליקציית Java, מבצעים את הפעולות הבאות:

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

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

2. מעדכנים את קוד האפליקציה כך שישתמש במודול OpenTelemetry SDK Autoconfigure כדי להגדיר את ה-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. מגדירים את נקודת הקצה של הייצוא.

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

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

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

Java

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

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 Autoconfigure ובתוסף Google Cloud Authentication, אתם לא צריכים לבצע שלבים מיוחדים במהלך ההפעלה של האפליקציה. המודול autoconfigure מבצע באופן אוטומטי את השלבים הנדרשים להגדרת ADC.

המשך

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

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

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

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

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:

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, כמו באפליקציית 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 כללית.