مراقبة API باستخدام OpenTelemetry في Go لمنصات SaaS الإنتاجية

المراقبة هي الفرق بين إيجاد سبب حادثة إنتاج في 10 دقائق وقضاء ثلاث ساعات في قراءة ملفات السجلات. الفرق الحقيقي بين المراقبة الجيدة والسيئة لا يظهر في الأوقات العادية. يظهر عند الساعة الثانية صباحاً عندما يكون API الخاص بك بطيئاً لمستأجر واحد فقط وتحتاج لمعرفة السبب.

لماذا المراقبة مختلفة عن مجرد التسجيل؟

التسجيل يجيب على: ماذا حدث؟ المراقبة تجيب على: لماذا حدث وأين؟

سجل منظم يخبرك أن طلباً فشل بخطأ 500. التتبع الموزع يُظهر تسلسل العمليات التي أدت لذلك الفشل: معالج API استدعى قاعدة البيانات، استعلام قاعدة البيانات استغرق 8 ثوان، ذلك الاستعلام أُطلق بواسطة Webhook من معالج دفع خارجي أرسل payload غير عادي.

OpenTelemetry هو المعيار المفتوح لتجهيز الأنظمة الموزعة بأدوات القياس. يُعرّف تنسيقاً مشتركاً للتتبعات والمقاييس والسجلات، مع محولات تصدير لكل بيئة رصد رئيسية: Grafana وDatadog وNew Relic وHoneycomb وJaeger.

إعداد OpenTelemetry في خدمة Go

تهيئة موفر التتبع عند بدء التشغيل:

func initTracer(ctx context.Context, serviceName string) (func(), error) {
    exporter, err := otlptracegrpc.New(ctx,
        otlptracegrpc.WithEndpoint(os.Getenv("OTEL_EXPORTER_ENDPOINT")),
    )
    if err != nil { return nil, err }

    tp := trace.NewTracerProvider(
        trace.WithBatcher(exporter),
        trace.WithSampler(trace.TraceIDRatioBased(0.1)), // 10% عينة
    )
    otel.SetTracerProvider(tp)
    return func() { tp.Shutdown(ctx) }, nil
}

لف خادم HTTP بوسيط OpenTelemetry:

handler := otelhttp.NewHandler(mux, "api-server")

استدعاء الوسيط الواحد هذا يُجهّز كل معالج HTTP بمسار يلتقط الطريقة والمسار وكود الحالة والمدة تلقائياً.

إضافة مسارات للعمليات الحرجة

func (s *Service) GetTenantOrders(ctx context.Context, tenantID string) ([]Order, error) {
    ctx, span := otel.Tracer("order-service").Start(ctx, "GetTenantOrders")
    defer span.End()

    span.SetAttributes(attribute.String("tenant.id", tenantID))

    orders, err := s.db.QueryOrders(ctx, tenantID)
    if err != nil {
        span.RecordError(err)
        span.SetStatus(codes.Error, err.Error())
        return nil, err
    }

    span.SetAttributes(attribute.Int("orders.count", len(orders)))
    return orders, nil
}

لاستعلامات قاعدة البيانات، مشغّل pgx PostgreSQL لديه دعم أصلي لـ OpenTelemetry عبر otelpgx. مع هذا الإعداد، كل استعلام قاعدة بيانات يولد مساراً فرعياً يُظهر نص SQL والمدة وعدد الصفوف المُعادة.

المقاييس: ماذا تقيس؟

التتبعات الموزعة تشرح الطلبات الفردية. المقاييس تخبرك عن صحة النظام عبر الزمن.

الحد الأدنى من المقاييس لتطبيق Go SaaS API:

• مدة طلب HTTP بحسب المسار
• الطلبات النشطة
• مدة استعلام قاعدة البيانات
• عمق طابور المهام

أهم الأبعاد لإضافتها لكل مقياس هي tenant_id والمسار. هذا يجعل من الممكن الإجابة على: هل ارتفاع زمن الاستجابة هذا يأتي من مستأجر واحد أم من الجميع؟

التسجيل المنظم مع ربط التتبع

func LogWithTrace(ctx context.Context, msg string, attrs ...slog.Attr) {
    span := trace.SpanFromContext(ctx)
    sc := span.SpanContext()

    allAttrs := []slog.Attr{
        slog.String("trace_id", sc.TraceID().String()),
        slog.String("span_id", sc.SpanID().String()),
    }
    allAttrs = append(allAttrs, attrs...)
    slog.LogAttrs(ctx, slog.LevelInfo, msg, allAttrs...)
}

عندما يُبلّغ مستأجر عن مشكلة في وقت محدد، يمكنك تصفية السجلات بـ tenant_id ونطاق الوقت، إيجاد الطلب الفاشل، نسخ trace_id، والانتقال مباشرةً للتتبع الموزع.

استراتيجية أخذ العينات

تسجيل وتخزين كل تتبع لتطبيق SaaS الذي يتعامل مع آلاف الطلبات في الدقيقة مكلف. معدل أخذ عينات 10% هو نقطة البداية المعيارية.

أضف قواعد أخذ عينات قائمة على الرأس تُلغي المعدل الافتراضي:

• أخذ عينة دائماً إذا كان كود الحالة 4xx أو 5xx
• أخذ عينة دائماً إذا تجاوزت مدة الطلب ثانيتين
• أخذ عينة من الطلبات الخالية من الأخطاء بمعدل 1% لتقليل تكاليف التخزين

التنبيه على بيانات التتبع

الاستعلامات الأكثر أهمية:

• زمن استجابة p99 بحسب المسار يتجاوز ثانيتين لمدة 5 دقائق متتالية
• معدل الخطأ بحسب المستأجر يتجاوز 5% في آخر 10 دقائق
• مدة استعلام قاعدة البيانات p99 تتجاوز 500ms
• أي مسار مع error = true في خدمة معالج الدفع في آخر 5 دقائق

بالنسبة لمنصات SaaS في الشرق الأوسط التي تتكامل مع بوابات الدفع الإقليمية، مراقبة مسارات معالج الدفع تلتقط أعطال التكامل قبل أن تؤثر على الإيرادات.

الدروس من الإنتاج

أجهّز استعلامات قاعدة البيانات بمعرفات التتبع منذ اليوم الأول. الاستعلام الذي يبدو سريعاً في التطوير وبطيئاً في الإنتاج يُشرحه التتبع، لا السجل.

أضف tenant_id لكل مسار ومقياس. بدونه، أرقام زمن الاستجابة الإجمالية تخفي مشكلات المستأجرين الفردية.

ربط التتبع في السجلات يستحق 10 دقائق من الإعداد. القدرة على الانتقال من سطر سجل إلى التتبع الكامل تقلل وقت التحقيق في الحوادث بالنصف.