refinery
v2.8.4
للحصول على قائمة مفصلة بطلبات السحب المرتبطة المدمجة في كل إصدار ، راجع changelog.md. لمزيد من المعلومات القابلة للقراءة حول التغييرات الحديثة ، يرجى الاطلاع على release_notes.md.
مصفاة هي وكيل أخذ العينات القائم على الذيل ويعمل على مستوى تتبع كامل. تفحص المصفاة آثار كاملة وتطبق بذكاء قرارات أخذ العينات على كل أثر. تحدد هذه القرارات ما إذا كان سيتم الاحتفاظ أو إسقاط بيانات التتبع في البيانات التي تم أخذ عينات منها إلى قرص العسل.
يتيح لك نموذج أخذ العينات القائم على الذيل فحص تتبع كامل في وقت واحد واتخاذ قرار بالعينة بناءً على محتوياته. على سبيل المثال ، قد تحتوي بياناتك على نطاق جذر يحتوي على رمز حالة HTTP لخدمته لطلب ، وآخر يحتوي على معلومات حول ما إذا كانت البيانات قد تم تقديمها من ذاكرة التخزين المؤقت. باستخدام المصفاة ، يمكنك اختيار الاحتفاظ فقط بالآثار التي تحتوي على رمز الحالة 500 وتم تقديمه أيضًا من ذاكرة التخزين المؤقت.
تدعم مصفاة عدة أنواع من أخذ عينات الذيل:
http.status_code ، يمكنك تضمين في بيانات العينة:2xx4xx5xxتتيح لك المصفاة الجمع بين جميع التقنيات المذكورة أعلاه لتحقيق سلوك أخذ العينات المطلوب.
تم تصميم المصفاة للجلوس داخل البنية التحتية حيث يمكن لجميع الآثار الوصول إليها. يمكن أن تعمل المصفاة بذاتها أو نشرها في مجموعة من عمليات مصفاة أو أكثر يمكن الوصول إليها عبر موازن تحميل منفصل.
يجب أن تكون عمليات المصفاة قادرة على التواصل مع بعضها البعض لتركيز آثار على خوادم واحدة.
ضمن تطبيقك (أو غيرها من مصادر أحداث قرص العسل) ، يمكنك تكوين API Host ليكون http(s)://load-balancer/ . يبقى كل شيء آخر كما هو ، مثل مفتاح API واسم مجموعة البيانات وما إلى ذلك منذ كل ما يعيش مع العميل الأصلي.
يجب أن يكون لكل مثيل مصفاة الحد الأدنى من:
linux/amd64 أو linux/arm64في كثير من الحالات ، تحتاج المصفاة فقط إلى عقدة واحدة. إذا كنت تعاني من حجم كبير من حركة المرور ، فقد تحتاج إلى توسيع نطاقها إلى عقد متعددة ، ومن المحتمل أن تحتاج إلى مثيل Redis صغير للتعامل مع التحجيم.
نوصي بزيادة مقدار ذاكرة الوصول العشوائي وعدد النوى بعد الإعداد الأولي الخاص بك. يمكن استخدام RAM و CPU إضافية عن طريق زيادة قيم التكوين ؛ على وجه الخصوص ، تعتبر CacheCapacity قيمة تكوين مهمة. يوفر نظام Stress Relief الخاص بمصفاة مؤشراً جيداً على مدى عمل المصفاة الصعبة ، وعندما يتم الاحتجاج به ، يقوم بتسجيلات ( reason ) لقيمة تكوين المصفاة التي يجب زيادة الضغط عليها. استخدم وثائق التحجيم واستكشاف الأخطاء وإصلاحها لمعرفة المزيد.
تتوفر مصفاة كرسومات هيلم في مستودع هيلم هيلم.
يمكنك تثبيت المصفاة مع الأمر التالي ، والذي يستخدم ملف القيم الافتراضية:
helm repo add honeycomb https://honeycombio.github.io/helm-charts
helm install refinery honeycomb/refineryبدلاً من ذلك ، قم بتزويد ملف القيم المخصصة الخاصة بك:
helm install refinery honeycomb/refinery --values /path/to/refinery-values.yaml Where /path/to/refinery-values.yaml هو مسار الملف.
عند العمل في مجموعة ، تتوقع المصفاة جمع جميع المسافات في أثر على مثيل واحد حتى يتمكن من اتخاذ قرار تتبع. نظرًا لأن كل فترة تصل بشكل مستقل ، يجب أن تكون كل حالة مصفاة قادرة على التواصل مع جميع أقرانها من أجل توزيع الآثار على المثيل الصحيح.
يمكن إدارة هذا الاتصال بطريقتين: من خلال قائمة صريحة من الأقران في ملف التكوين ، أو باستخدام التسجيل الذاتي عبر ذاكرة التخزين المؤقت Redis المشتركة. يجب أن تفضل التركيبات استخدام redis. حتى في عمليات التثبيت الكبيرة ، يكون الحمل على خادم Redis خفيفًا تمامًا ، حيث يقدم كل مثيل سوى بعض الطلبات في الدقيقة. عادة ما يكون مثيل redis واحد مع وحدة المعالجة المركزية الكسرية كافية.
يتم التحكم في التكوين بواسطة ملف تكوين المصفاة ، والذي يشار إليه عمومًا باسم config.yaml للتكوين العام rules.yaml لتكوين أخذ العينات. يمكن تحميل هذه الملفات من نظام ملفات يمكن الوصول إليها ، أو محمّلها بطلب GET غير مصادق من عنوان URL.
تعرف على المزيد حول config.yaml وجميع المعلمات التي تتحكم في تشغيل مصفاة المصفاة في وثائق تكوين المصفاة الخاصة بنا.
تعرف على المزيد حول rules.yaml وتكوين أخذ العينات في وثائق أساليب أخذ عينات المصفاة لدينا.
إنه صحيح لتحديد أكثر من مصدر تكوين واحد. على سبيل المثال ، سيكون من الممكن أن يكون لديك ملف تكوين مشترك ، بالإضافة إلى ملف منفصل يحتوي على مفاتيح فقط. في سطر الأوامر ، حدد ملفات متعددة عن طريق تكرار مفتاح سطر الأوامر. في متغيرات البيئة ، فصل مواقع تكوين متعددة مع فواصل.
المصفاة هو تطبيق سطر أوامر على طراز Linux نموذجي ، ويدعم العديد من مفاتيح سطر الأوامر.
ستقوم refinery -h -بطباعة نصوص نصية ممتدة لإدراج جميع خيارات سطر الأوامر ومتغيرات البيئة المدعومة.
تدعم المصفاة متغيرات البيئة الرئيسية التالية ؛ يرجى الاطلاع على مساعدة سطر الأوامر أو الوثائق عبر الإنترنت للقائمة الكاملة. تتبع مفاتيح سطر الأوامر الأسبقية على تكوين الملفات ، وتتحلى متغيرات البيئة الأسبقية على كليهما.
| متغير البيئة | حقل التكوين |
|---|---|
REFINERY_GRPC_LISTEN_ADDRESS | GRPCListenAddr |
REFINERY_REDIS_HOST | PeerManagement.RedisHost |
REFINERY_REDIS_USERNAME | PeerManagement.RedisUsername |
REFINERY_REDIS_PASSWORD | PeerManagement.RedisPassword |
REFINERY_HONEYCOMB_API_KEY | HoneycombLogger.LoggerAPIKey |
REFINERY_HONEYCOMB_METRICS_API_KEY | LegacyMetrics.APIKey |
REFINERY_HONEYCOMB_API_KEY | LegacyMetrics.APIKey |
REFINERY_QUERY_AUTH_TOKEN | QueryAuthToken |
ملاحظة: REFINERY_HONEYCOMB_METRICS_API_KEY تتبع الأسبقية على REFINERY_HONEYCOMB_API_KEY لتكوين LegacyMetrics.APIKey .
يتطلب إرسال البيانات إلى قرص العسل إرفاق مفتاح API بالقياس عن بعد. من أجل جعل إدارة القياس عن بعد أسهل ، تدعم مصفاة خيارات ReceiveKeys و SendKey ، إلى جانب AcceptOnlyListedKeys و SendKeyMode . في مجموعات مختلفة ، لديهم الكثير من القوة التعبيرية. يرجى الاطلاع على وثائق التكوين للحصول على تفاصيل حول كيفية تعيين هذه المعلمات.
فيما يلي بداية سريعة لسيناريوهات محددة:
SendKey على مفتاح قرص العسل الصالحSendKeyMode على allSendKey على مفتاح قرص العسل الصالحSendKeyMode على nonblankReceiveKeys على قائمة الاستثناءاتSendKey على مفتاح قرص العسل الصالحSendKeyMode على unlistedSendKey على مفتاح قرص العسل الصالحSendKeyMode على missingonlyReceiveKeysAcceptOnlyListedKeys إلى trueSendKey على مفتاح قرص العسل الصالحSendKeyMode على listedonlyAcceptOnlyListedKeys إلى falseReceiveKeys على المفاتيح التي يجب استبدالهاSendKey على مفتاح قرص العسل الصالحSendKeyMode على listedonly + note + + عند استخدام Beetleines مع مفتاح API الكلاسيكي لإرسال البيانات إلى مصفاة ، تأكد من أن SendKey هو أيضًا مفتاح كلاسيكي ، وليس مفتاحًا للبيئة والخدمة (E&S).
عند البدء في المصفاة أو عند تحديث قواعد أخذ العينات ، قد يكون من المفيد التحقق من أن القواعد تعمل كما هو متوقع قبل البدء في إسقاط حركة المرور. للقيام بذلك ، استخدم وضع التشغيل الجاف في المصفاة.
تمكين وضع التشغيل الجاف عن طريق إضافة DryRun = true في ملف التكوين الخاص بك ( config.yaml ). بعد ذلك ، استخدم Builder Query في واجهة المستخدم Honeycomb لتشغيل الاستعلامات للتحقق من نتائجك والتحقق من أن القواعد تعمل على النحو المقصود.
عند تمكين وضع الجفاف الجاف ، سيبقى Metric trace_send_kept زيادة لكل أثر ، وسيظل المقياس لـ trace_send_dropped 0 ، مما يعكس أننا نرسل جميع الآثار إلى قرص العسل.
تستخدم المصفاة قوائم قوائم محددة ومؤسسات دائرية لإدارة آثار تخصيص ، لذلك حتى في ظل استخدام الذاكرة ذات الحجم الكبير ، يجب ألا يتوسع بشكل كبير. ومع ذلك ، بالنظر إلى أن الآثار يتم تخزينها في المخزن المؤقت الدائري ، عندما تتجاوز إنتاجية الآثار حجم المخزن المؤقت ، ستبدأ الأمور في الخطأ. إذا كان لديك إحصائيات تم تكوينها ، فسيتم زيادة عداد collect_cache_buffer_overrun في كل مرة يحدث هذا. ستكون أعراض ذلك هي أن الآثار ستتوقف عن التراكم معًا ، وبدلاً من ذلك ، سيتم التعامل مع الممتدات التي يجب أن تكون جزءًا من نفس التتبع على أنها آثار منفصلة. سيتم إرسال جميع الآثار (وأخذ عينات) ، ولكن سيتم اتخاذ بعض قرارات أخذ العينات على البيانات غير المكتملة. حجم المخزن المؤقت الدائري هو خيار تكوين يسمى CacheCapacity . لاختيار قيمة جيدة ، يجب أن تفكر في إنتاجية الآثار (على سبيل المثال ، بدأت الآثار / الثانية) وضرب ذلك بحد أقصى مدة تتبع (مثل 3 ثوان) ، ثم اضرب ذلك من خلال بعض المخزن المؤقت الكبير (ربما 10x) . هذا التقدير سوف يعطي غرفة جيدة.
إن تحديد عدد الآلات اللازمة في المجموعة ليس علمًا دقيقًا ، ويتأثر بشكل أفضل بمشاهدة التجاوزات العازلة. ولكن للحصول على استدلال تقريبي ، احسب على جهاز واحد باستخدام حوالي 2 جيجابايت من الذاكرة للتعامل مع 5000 أحداث واردة وتتبع 500 آثار ثانية ثانية في الثانية (لكل أثر كامل يدوم أقل من ثانية ومتوسط 10 تمتد لكل أثر) .
تقدم المصفاة آلية تسمى Stress Relief التي تحسن الاستقرار تحت الحمل الثقيل. مقياس stress_level هو مقياس اصطناعي على مقياس من 0 إلى 100 تم إنشاؤه من عدة مقاييس مصفاة تتعلق بأحجام قائمة الانتظار واستخدام الذاكرة. تحت التشغيل العادي ، يجب أن تكون قيمتها عادة في الأرقام الفردية. أثناء رشقات الحركة ذات الزيارات العالية ، قد تتسلل مستويات التوتر ثم تنخفض مرة أخرى مع انخفاض حجم الصوت. مع اقتراب 100 ، من المرجح أن تبدأ المصفاة في الفشل وربما تعطل.
Stress Relief هو نظام يمكنه مراقبة مقياس stress_level وحمل السقوط عندما يصبح الإجهاد خطرًا على الاستقرار. بمجرد الوصول إلى ActivationLevel ، سيصبح وضع Stress Relief نشطًا. في هذه الحالة. ستقوم المصفاة بتقسيم كل فترة بناءً على TraceID دون الحاجة إلى تخزين بقية التتبع أو تقييم شروط القاعدة. سيبقى Stress Relief نشطًا حتى ينخفض الإجهاد إلى أسفل DeactivationLevel المحدد في التكوين.
إعدادات تخفيف التوتر هي:
Mode - الإعداد للإشارة إلى كيفية استخدام Stress Relief . لا تشير never إلى أن Stress Relief لن يتم تنشيطه. monitor تعني أن Stress Relief سوف يتم تنشيطه عندما يتم ActivationLevel وإلغاء تنشيطه عند الوصول إليه. يعني always أن وضع Stress Relief سيشارك بشكل مستمر. الوضع always مخصص للاستخدام في حالات الطوارئ.ActivationLevel - عندما يرتفع مستوى الإجهاد فوق هذه العتبة ، ستقوم المصفاة بتنشيط Stress Relief .DeactivationLevel - عندما ينخفض مستوى الإجهاد تحت هذه العتبة ، سوف تقوم المصفاة بإلغاء Stress Relief .SamplingRate - المعدل الذي يكون فيه عينات المصفاة أثناء Stress Relief نشطًا. يعد stress_level حاليًا أفضل وكيل للحمل الكلي على المصفاة. حتى إذا لم يكن Stress Relief نشطًا ، إذا كان stress_level يتجاوز 50 في كثير من الأحيان ، فهو مؤشر جيد على أن المصفاة تحتاج إلى مزيد من الموارد - المزيد من وحدات المعالجة المركزية ، أو المزيد من الذاكرة ، أو المزيد من العقد. من ناحية أخرى ، إذا كان stress_level لا يذهب إلى أرقام مزدوجة ، فمن المحتمل أن يكون المصفاة مبالغًا فيه.
تنبعث المصفاة عددًا من المقاييس لإعطاء بعض المؤشرات حول صحة العملية. يجب إرسال هذه المقاييس إلى قرص العسل ، عادةً مع القياس عن بُعد المفتوح ، ويمكن أيضًا أن تتعرض لبروميثيوس. تلك المثيرة للاهتمام التي يجب مشاهدتها هي:
[incoming|peer]_router_* : كم عدد الأحداث (لا توجد معلومات تتبع) مقابل فترات (تحتوي على معلومات تتبع) ، وكم عدد الأحداث المرسلة إلى أقرانها؟collect_cache_buffer_overrun : يجب أن يظل هذا صفرًا ؛ تشير القيمة الإيجابية إلى الحاجة إلى نمو حجم المخزن المؤقت التتبع الدائري للمصفاة (عبر التكوين CacheCapacity ).process_uptime_seconds : يسجل وقت تشغيل كل عملية ؛ ابحث عن إعادة التشغيل غير المتوقعة كمفتاح تجاه قيود الذاكرة. مستوى التسجيل الافتراضي warn هادئ إلى حد ما. ينبعث مستوى debug الكثير من البيانات التي لا يمكن استخدامها في الإنتاج ، ولكنها تحتوي على معلومات ممتازة في بيئة ما قبل الإنتاج ، بما في ذلك معلومات القرار النزرة. info في مكان ما بين. سيساعد تحديد مستوى التسجيل على debug أثناء التكوين الأولي في فهم ما هو العمل وما هو غير ذلك ، ولكن عندما تزداد أحجام المرور error يجب ضبطها على warn أو حتى. قد يتم إرسال السجلات إلى stdout أو إلى قرص العسل.
تقوم المصفاة بالتحقق من صحة تكوينها عند بدء التشغيل أو عند إعادة تحميل التكوين ، وينبعث من التشخيص لأي مشاكل. عند بدء التشغيل ، سترفض البدء ؛ عند إعادة التحميل ، لن يغير التكوين الحالي.
تحقق من التكوين المحمّل باستخدام إحدى نقاط النهاية /query من سطر الأوامر على خادم يمكنه الوصول إلى مضيف مصفاة.
يتم حماية نقاط النهاية /query ويمكن تمكينها من خلال تحديد QueryAuthToken في ملف التكوين أو تحديد REFINERY_QUERY_AUTH_TOKEN في البيئة. يجب أن تتضمن جميع الطلبات إلى أي نقطة نهاية /query رأس X-Honeycomb-Refinery-Query على قيمة الرمز المميز المحدد.
بالنسبة للتكوينات المستندة إلى الملفات (النوع الوحيد المدعوم حاليًا) ، تتطابق قيمة hash للقيمة التي تم إنشاؤها بواسطة الأمر md5sum لملف التكوين المحدد.
لكل هذه الأوامر:
$REFINERY_HOST يجب أن يكون عنوان URL لمصفاةك.$FORMAT واحد من yaml أو toml أو json .$DATASET هي اسم مجموعة البيانات التي تريد التحقق منها.لاسترداد تكوين القواعد بأكملها:
curl --include --get $REFINERY_HOST/query/allrules/$FORMAT --header "x-honeycomb-refinery-query: my-local-token"
لاسترداد مجموعة القاعدة التي تستخدمها المصفاة لمجموعة البيانات المحددة ، والتي سيتم إرجاعها كخريطة لنوع العينات إلى مجموعة القواعد الخاصة به:
curl --include --get $REFINERY_HOST/query/rules/$FORMAT/$DATASET --header "x-honeycomb-refinery-query: my-local-token"
لاسترداد المعلومات حول التكوينات المستخدمة حاليًا ، بما في ذلك الطابع الزمني عندما تم تحميل التكوين آخر:
curl --include --get $REFINERY_HOST/query/configmetadata --header "x-honeycomb-refinery-query: my-local-token"
يمكن أن ترسل المصفاة القياس عن بُعد تتضمن معلومات يمكن أن تساعد في تصحيح قرارات أخذ العينات التي يتم اتخاذها. لتمكين ، في ملف التكوين ، قم بتعيين AddRuleReasonToTrace إلى true . سيؤدي ذلك إلى اتباع آثار يتم إرسالها إلى قرص العسل لتشمل meta.refinery.reason .
لم يتم بعد المصفاة آثارًا عازلة أو قرارات أخذ العينات إلى القرص. عندما تقوم بإعادة تشغيل العملية ، سيتم مسح جميع آثار الرحلة (تم إرسالها في المنبع إلى قرص العسل) ، لكنك ستفقد سجل القرارات السابقة. عندما تبدأ النسخ الاحتياطي ، ستبدأ بقائمة نظيفة.
داخل كل دليل ، تكون الواجهة تصدير التبعية في الملف بنفس اسم الدليل ثم (بالنسبة للجزء الأكبر) كل من الملفات الأخرى هي تطبيقات بديلة لتلك الواجهة. على سبيل المثال ، في logger ، يحتوي /logger/logger.go على تعريف الواجهة ويحتوي logger/honeycomb.go على تنفيذ واجهة logger التي سترسل سجلات إلى قرص العسل.
تقوم main.go بإعداد التطبيق ويتخذ خيارات حول إصدارات تطبيقات التبعية التي يجب استخدامها (على سبيل المثال أي Logger ، الذي يتم أخذ عينات منه ، وما إلى ذلك) ، يبدأ كل شيء ثم يطلق App .
app/app.go هي نقطة التحكم الرئيسية. عندما تنتهي وظيفة Start ، يتم إيقاف البرنامج. إنه يطلق اثنين من Router الذي يستمع للأحداث الواردة.
route/route.go يستمع على الشبكة لحركة المرور الواردة. هناك نوعان من أجهزة التوجيه ويتعاملان مع أنواع مختلفة من حركة المرور الواردة: الأحداث القادمة من العالم الخارجي (جهاز التوجيه incoming ) والأحداث القادمة من عضو آخر في مجموعة المصفاة (حركة peer ). بمجرد حصوله على حدث ، فإنه يقرر أين يجب أن يذهب بعد ذلك: هل هذا الطلب الوارد حدث (أو مجموعة من الأحداث) ، وإذا كان الأمر كذلك ، فهل يحتوي على معرف تتبع؟ كل ما ليس حدثًا أو حدثًا لا يحتوي على معرف تتبع يتم تسليمه على الفور إلى transmission ليتم إعادة توجيهه إلى قرص العسل. إذا كان حدثًا يحتوي على معرف تتبع ، فإن جهاز التوجيه يستخرج معرف التتبع ثم يستخدم sharder لتحديد أي عضو في مجموعة المصفاة يجب أن يتعامل مع هذا التتبع. إذا كان نظيرًا ، فسيتم إرسال هذا الحدث إلى هذا الأقران. إذا كان الأمر نحن ، فسيتم تحويل الحدث إلى تمثيل داخلي وسلمه إلى collector لتجميع الامتدادات في آثار.
collect/collect.go في المرة الأولى التي يتم فيها رؤية معرف التتبع ، يبدأ جامع مؤقتًا. إذا كانت فترة الجذر ، وهي فترة مع معرف تتبع ولا معرف الوالدين ، تصل قبل انتهاء الموقت ، فإن التتبع يعتبر كاملًا. يتم إرسال التتبع وإلغاء المؤقت. في حالة انتهاء الموقت قبل وصول الجذر ، سيتم إرسال التتبع سواء أكمل أم لا. قبل الإرسال مباشرة ، يطلب جامع sampler معدل عينة وما إذا كان للحفاظ على التتبع أم لا. يطيع المجمع قرار أخذ العينات هذا ويسجله (يتم تطبيق السجل على أي فترات قد تأتي كجزء من التتبع بعد اتخاذ القرار). بعد اتخاذ قرار أخذ العينات ، إذا تم الاحتفاظ بالتتبع ، يتم تمريره إلى transmission للإرسال الفعلي.
transmit/transmit.go هو غلاف حول تفاعلات HTTP مع API Honeycomb. إنه يتعامل مع الأحداث الجوية معًا ويرسلها في اتجاه المنبع.
logger metrics هي إدارة السجلات والمقاييس التي تنتجها المصفاة نفسها.
يحتوي sampler على خوارزميات لحساب معدلات العينة بناءً على الآثار المقدمة.
يحدد sharder أي نظير في تكوين مصفاة مجمعة من المفترض أن يتعامل مع تتبع فردي.
تحتوي types على بعض التعريفات التي يتم استخدامها لتسليم البيانات بين الحزم.
