ObservabilityOSS
المتطلبات الأساسية
- يجب تثبيت clickhouse-local على جهازك. راجع دليل إعداد clickhouse-local للبدء.
ما الذي ستبنيه
trace span مجموعة من سمات الموارد — وهي بيانات وصفية بتنسيق مفتاح-قيمة تصف الكيان الذي أنتج بيانات telemetry (مثل اسم الخدمة، والمضيف، والمنطقة السحابية، وpod في Kubernetes، وغير ذلك). وتختلف مجموعة المفاتيح بين الخدمات والبيئات، مما يجعل نوع Map في ClickHouse مناسبًا لهذا الاستخدام بطبيعته: فالمفاتيح ديناميكية وخاصّة بالتطبيق، لكن أي صف معيّن لا يحتوي عادةً إلا على عدد قليل منها.
في هذا الدليل السريع، ستستخدم clickhouse-local لتحميل بيانات trace حقيقية من OTel من ملف CSV إلى جدول يحتوي على أعمدة Map(LowCardinality(String), String)، وستتعلّم كيفية الاستعلام عن بيانات Map وتصفيتها وتجميعها وتحسينها.
نزّل بيانات العيّنة
تتضمن مجموعة البيانات 6,120 امتداد تتبّع OTel مُصدَّرًا من تطبيق تجريبي للخدمات المصّغرة. ويتضمن كل صف العمودين
ResourceAttributes وSpanAttributes، ويحتويان على أزواج مفتاح-قيمة ديناميكية على شكل خرائط JSON.
احفظ الملف في دليل يسهل الرجوع إليه، على سبيل المثال ~/data/data-otel-traces.csv.نزّل data-otel-traces.csv (2.9 MB)إليك شكل صف واحد:أنشئ الجدول وحمّل البيانات
شغّل الآن حمّل ملف CSV باستخدام محرّك الجدول تأكد من أنه تم تحميل البيانات:من المفترض أن ترى 6,120 صفًا.
clickhouse-local وأنشئ الجدول التالي بمخطط يتوافق مع ملف CSV.
عمود المفتاح هو ResourceAttributes Map(LowCardinality(String), String) — ويُستخدم LowCardinality مع نوع المفتاح لأن مفاتيح سمات OTel مأخوذة من مجموعة صغيرة نسبيًا ومتكررة.file. عدّل المسار ليتوافق مع المكان الذي حفظت فيه الملف:الاستعلام عن البيانات
الوصول إلى مفتاح محدد — استخدم صيغة الأقواس المربعة لاستخراج قيمة من التصفية حسب قيمة في map — اعثر على جميع spans المرتبطة باسم خدمة محدد:تحقّق مما إذا كان المفتاح موجودًا â لا يحتوي كل افحص جميع المفاتيح الموجودة في كامل مجموعة البيانات — وهذا مفيد لفهم ما الذي تنتجه أدوات الرصد المضمّنة:فكِّك Map إلى صفوف باستخدام ARRAY JOIN — حوِّل كل زوج مفتاح-قيمة إلى صف مستقل، مما يفيد في إنشاء فهرس للسمات أو في تعبئة لوحات المعلومات:رشّح قيم Map باستخدام mapFilter — استخرج فقط السمات المرتبطة بـ Kubernetes من كل Span:اعثر على مقاطع التتبّع الخاصة بالأخطاء وسياق المورد المرتبط بها â اجمع بين مرشحات الأعمدة العادية والوصول إلى
map. إذا لم يكن المفتاح موجودًا في صف معيّن، فستحصل على القيمة الافتراضية لنوع القيمة (سلسلة فارغة من النوع String):span على بيانات Kubernetes الوصفية. استخدم mapContains لمعرفة أيّها يحتوي عليها:map:التجميع عبر خرائط Map باستخدام المبدِّل -Map
يتيح المبدِّل التجميعي استخدم الآن تعمل اللاحقة يمكنك أيضًا دمجه مع مُركِّبات أخرى. على سبيل المثال، يتيح لك لماذا يهم هذا بالنسبة إلى OTel: عندما يكتب OTel Collector تفاصيل رموز الحالة لكل دقيقة في ClickHouse، تتيح لك
-Map في ClickHouse تطبيق أي دالة aggregate على عمود Map بحيث تعمل على كل مفتاح بشكل مستقل. وتكون النتيجة أيضًا Map — مع مُدخل واحد لكل مفتاح، يتضمن القيمة المُجمَّعة. ويكون هذا مفيدًا بشكل خاص مع metrics في OTel، حيث تُخزَّن counters أو gauges كقيم في map.للتوضيح، أنشئ table صغيرًا للـ metrics حيث يسجّل كل row أعداد رموز حالة HTTP بصيغة Map(String, UInt64):sumMap لحساب إجمالي مرات الظهور لكل رمز حالة في كل خدمة:-Map مع أي دالة تجميع، لذا يمكنك استخدام minMap أو maxMap أو avgMap بالقدر نفسه من السهولة:sumMapIf إجراء تجميع شرطي — إذ لا تُجمَع هنا إلا نوافذ الدقائق التي كانت الخدمة تحتوي فيها بالفعل على أخطاء:sumMap تجميعها في إجماليات لكل ساعة أو لكل يوم ضمن استعلام واحد — من دون ARRAY JOIN، ومن دون إلغاء التمحور، ومن دون الحاجة إلى معرفة المجموعة الكاملة للمفاتيح مسبقًا. ويُدرَج تلقائيًا في النتيجة أي مفتاح يظهر في أي صف.حسّن الأداء للمفاتيح التي يُكثر الاستعلام عنها
إذا وجدت نفسك تُجري التصفية باستمرار على المفتاح نفسه في بالنسبة إلى البيانات الموجودة، أجرِ تعبئةً لاحقةً للعمود:الآن يقرأ
map — ويُعد host.name مثالًا شائعًا — فيمكنك استخراجه إلى عمود مُجسَّد. وهذا يجنّبك الفحص الخطي داخل map في كل استعلام:WHERE HostName = 'prod-cart-01' عمودًا مخصصًا واحدًا بدلًا من قراءة بنية Map بالكامل. وهذا هو النمط الموصى به في مخطط OTel في ClickHouse لأي سمة تستعلم عنها بشكل متكرر.النقاط الرئيسية
Map(LowCardinality(String), String)هو النوع الأكثر شيوعًا لسمات OTel — مرن بما يكفي للتعامل مع مجموعات مفاتيح متغيرة، كما يحافظLowCardinalityعلى كفاءة تخزين المفاتيح.- صياغة الأقواس (
map['key']) هي الطريقة الأكثر شيوعًا للوصول إلى القيم، لكن تذكّر أنها تفحص خطيًا — وهذا مناسب للخرائط التي تحتوي على عشرات المفاتيح، لكنه ليس مثاليًا عند وجود المئات. - الأعمدة المُجسَّدة هي الحل العملي هنا: عندما يصبح مفتاح في الخريطة هدفًا شائعًا للتصفية، رقِّه إلى عمود فعلي للوصول المفهرس والعمودي.
mapContains,mapKeys,mapValues,mapFilterوARRAY JOINتوفّر لك مجموعة أدوات قوية لاستكشاف بيانات الخرائط وتحويلها دون مغادرة SQL.- مُركِّب التجميع
-Map(sumMap,avgMap,maxMap, etc.) يجمّع كل مفتاح على نحو مستقل عبر الصفوف — وهو مثالي لتجميع عدّادات مقاييس OTel دون الحاجة إلى معرفة مجموعة المفاتيح مسبقًا. كما يمكن تركيبه مع مُركِّبات أخرى أيضًا (مثلsumMapIf).
