OpenTelemetry Go: الدليل الكامل للتتبع الموزع

1. ما هو OpenTelemetry Go ولماذا تحتاجه؟

OpenTelemetry هي مجموعة من واجهات برمجة التطبيقات (API)، ومجموعات تطوير البرمجيات (SDK)، والأدوات المصممة لإنشاء وإدارة بيانات القياس عن بُعد مثل التتبعات (traces) والمقاييس (metrics) والسجلات (logs). مكتبة opentelemetry-go هي التطبيق الرسمي لمعيار OpenTelemetry للغة Go. توفر للمطورين طريقة موحدة ومستقلة عن البائعين لتجهيز تطبيقاتهم لجمع بيانات القياس عن بُعد، والتي يمكن إرسالها بعد ذلك إلى أنظمة خلفية مختلفة مثل Jaeger و Zipkin و Prometheus و Grafana Tempo و Datadog وغيرها الكثير.

لماذا تحتاجها؟ في البنى التحتية الحديثة القائمة على الخدمات المصغرة (microservices)، غالبًا ما يمر طلب المستخدم عبر عشرات الخدمات المختلفة. عند حدوث مشكلة (مثل بطء الطلب أو فشله)، يصعب جدًا بدون التتبع الموزع (distributed tracing) تحديد الخدمة التي تسببت في عنق الزجاجة أو مصدر العطل. يتيح لك OpenTelemetry تتبع مسار الطلب عبر النظام بأكمله، ورؤية وقت تنفيذ كل خطوة، وربطها في تتبع واحد (trace) يتكون من أجزاء تسمى سبانات (spans). يمنح هذا المطورين ومهندسي الموثوقية (SRE) أداة قوية لتصحيح الأخطاء والمراقبة وتحسين الأداء.

الميزة الرئيسية لـ OpenTelemetry مقارنة بالحلول الأخرى (مثل المكتبات القديمة OpenTracing أو OpenCensus) هي عموميتها وتوحيد معاييرها. تكتب الكود مرة واحدة باستخدام واجهة برمجة تطبيقات موحدة، ويمكنك تغيير النظام الخلفي لتخزين البيانات وعرضها دون تغيير كود التطبيق. هذا يجعل opentelemetry-go ليس مجرد مكتبة، بل أساسًا لبناء نظام قابل للمراقبة (observable) بلغة Go.

2. التثبيت

لتثبيت مكتبة opentelemetry-go ومكوناتها الأساسية، استخدم مدير الحزم القياسي للغة Go. ستحتاج إلى تثبيت حزمة API الرئيسية، وSDK للتتبع، ومُصدر (exporter) (مثل إخراج وحدة التحكم أو Jaeger).

# تثبيت API الرئيسي
go get go.opentelemetry.io/otel

# تثبيت SDK للتتبع
go get go.opentelemetry.io/otel/sdk

# تثبيت المُصدر للإخراج إلى وحدة التحكم (للتصحيح)
go get go.opentelemetry.io/otel/exporters/stdout/stdouttrace

# تثبيت ناشر سياق HTTP (للتكامل مع HTTP)
go get go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp

# تثبيت المُصدر لـ Jaeger (للإنتاج)
go get go.opentelemetry.io/otel/exporters/jaeger

بعد تنفيذ هذه الأوامر، ستتم إضافة جميع التبعيات الضرورية إلى ملف go.mod الخاص بك.

3. البداية السريعة — مثال عملي بسيط

يوضح هذا المثال كيفية إنشاء تتبع بسيط مع سبان واحد وإخراجه إلى وحدة التحكم. إنها نقطة انطلاق ممتازة لفهم المفاهيم الأساسية.

package main

import (
	"context"
	"fmt"
	"log"

	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/attribute"
	"go.opentelemetry.io/otel/exporters/stdout/stdouttrace"
	"go.opentelemetry.io/otel/sdk/resource"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
	semconv "go.opentelemetry.io/otel/semconv/v1.17.0"
	"go.opentelemetry.io/otel/trace"
)

func main() {
	// 1. إنشاء مُصدر للإخراج إلى وحدة التحكم
	exporter, err := stdouttrace.New(
		stdouttrace.WithPrettyPrint(),
	)
	if err != nil {
		log.Fatal(err)
	}

	// 2. إنشاء TracerProvider مع المُصدر والمورد
	tp := sdktrace.NewTracerProvider(
		sdktrace.WithBatcher(exporter),
		sdktrace.WithResource(resource.NewWithAttributes(
			semconv.SchemaURL,
			semconv.ServiceNameKey.String("my-service"),
		)),
	)
	defer func() {
		if err := tp.Shutdown(context.Background()); err != nil {
			log.Fatal(err)
		}
	}()

	// 3. تعيين TracerProvider العام
	otel.SetTracerProvider(tp)

	// 4. الحصول على Tracer
	tracer := otel.Tracer("my-tracer")

	// 5. إنشاء سبان
	ctx, span :=