القياس عن بُعد إلى Google Cloud

تعمل ميزة gcp في adk-telemetry على تصدير التتبعات مباشرةً إلى Google Cloud Observability (Cloud Trace)، وتكتب سجلات JSON منظّمة يحللها Cloud Logging بشكل أصلي — بما في ذلك مستوى الخطورة والرسالة وربط التتبع.

تمكين الميزة

[dependencies]
adk-telemetry = { version = "2.1.0", features = ["gcp"] }

أو من خلال الحزمة الشاملة (تُعد gcp-telemetry أيضًا جزءًا من الميزة الوصفية gemini-agent-platform):

[dependencies]
adk-rust = { version = "2.1.0", features = ["minimal", "gcp-telemetry"] }

التصدير المباشر إلى Google Cloud

تصدّر init_with_gcp الامتدادات إلى https://telemetry.googleapis.com عبر gRPC، مع مصادقة كل طلب باستخدام رمز Bearer موقّع من بيانات اعتماد التطبيق الافتراضية (ADC)، بالإضافة إلى ترويسة x-goog-user-project. تعيد مهمة تعمل في الخلفية إصدار الرمز كل خمس دقائق، ولذلك تواصل الوكلاء طويلة التشغيل التصدير حتى بعد انتهاء صلاحية الرمز.

use adk_telemetry::init_with_gcp;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Requires GOOGLE_CLOUD_PROJECT and Application Default Credentials.
    init_with_gcp("my-agent").await?;

    // Your agent code here

    adk_telemetry::shutdown_telemetry();
    Ok(())
}

المتطلبات:

ملاحظة: يصدّر هذا المسار التتبعات فقط. وجّه المقاييس عبر الوكيل الجانبي للمجمّع أدناه.

اكتشاف موارد GCP

يستمد init_with_gcp سمات موارد OpenTelemetry من متغيرات البيئة التي يعيّنها النظام الأساسي في الحاويات المنشورة:

GOOGLE_CLOUD_AGENT_ENGINE_ID هو معرّف المحرك الرقمي المجرّد الذي يعيّنه Vertex AI Agent Engine في الحاويات المنشورة. gcp.agent_engine هي قيمة cloud.platform الأساسية من الاصطلاحات الدلالية لـ OpenTelemetry (أُضيفت في المصدر الأساسي في أكتوبر 2025).

يتوفر الاكتشاف نفسه بشكل مستقل لإنشاء مسار المعالجة الخاص بك:

use adk_telemetry::gcp_resource_attributes;

let attributes = gcp_resource_attributes("my-agent");

تسجيل JSON المنظّم لـ Cloud Logging

يكتب init_json_logging كائن JSON واحدًا في كل سطر إلى stdout، بحيث يحلّل Cloud Logging حقول الخطورة والتتبّع بدلًا من عرض حمولات نصية مبهمة. يثبّت init_with_gcp التنسيق نفسه تلقائيًا.

use adk_telemetry::init_json_logging;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    init_json_logging()?;

    tracing::info!(user.id = "u1", "request handled");
    Ok(())
}

الحقول المُصدرة:

تتطلب حقول ترابط التتبّع طبقة OpenTelemetry في نفس المشترك وGOOGLE_CLOUD_PROJECT — إذ يوفر init_with_gcp كليهما، مما يجعل إدخالات السجل تظهر مضمنةً في لوحة Cloud Trace.

البديل: OTLP إلى Collector جانبي

عندما لا يتوفر الوصول المباشر إلى API — أو عندما تحتاج أيضًا إلى المقاييس — شغّل Collector ‏OpenTelemetry كخدمة جانبية ووجّه مُصدّر OTLP القياسي إليه:

use adk_telemetry::init_with_otlp;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    init_with_otlp("my-agent", "http://localhost:4317")?;

    // Your agent code here

    adk_telemetry::shutdown_telemetry();
    Ok(())
}

تهيئة Collector لإعادة التوجيه إلى Google Cloud ‏(otel-collector-config.yaml، باستخدام googlecloud exporter من توزيعة contrib):

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

processors:
  batch:
    send_batch_size: 200
    timeout: 5s
  resourcedetection:
    detectors: [env, gcp]

exporters:
  googlecloud:
    project: my-project

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [resourcedetection, batch]
      exporters: [googlecloud]
    metrics:
      receivers: [otlp]
      processors: [resourcedetection, batch]
      exporters: [googlecloud]

شغّله محليًا للتطوير:

docker run --rm -p 4317:4317 \
  -v ./otel-collector-config.yaml:/etc/otelcol-contrib/config.yaml \
  -v ~/.config/gcloud:/root/.config/gcloud \
  otel/opentelemetry-collector-contrib:latest

اختيار المسار

ذو صلة

• القياس عن بُعد - إعداد القياس عن بُعد الأساسي ومساعدات الامتداد
• النشر - إعداد القياس عن بُعد في بيئة الإنتاج