Skip to main content
All quickstarts
ObservabilityOSS

المتطلبات الأساسية

ما الذي ستبنيه

في OpenTelemetry، يحمل كل trace span مجموعة من سمات الموارد — وهي بيانات وصفية بتنسيق مفتاح-قيمة تصف الكيان الذي أنتج بيانات telemetry (مثل اسم الخدمة، والمضيف، والمنطقة السحابية، وpod في Kubernetes، وغير ذلك). وتختلف مجموعة المفاتيح بين الخدمات والبيئات، مما يجعل نوع Map في ClickHouse مناسبًا لهذا الاستخدام بطبيعته: فالمفاتيح ديناميكية وخاصّة بالتطبيق، لكن أي صف معيّن لا يحتوي عادةً إلا على عدد قليل منها. في هذا الدليل السريع، ستستخدم clickhouse-local لتحميل بيانات trace حقيقية من OTel من ملف CSV إلى جدول يحتوي على أعمدة Map(LowCardinality(String), String)، وستتعلّم كيفية الاستعلام عن بيانات Map وتصفيتها وتجميعها وتحسينها.
1

نزّل بيانات العيّنة

تتضمن مجموعة البيانات 6,120 امتداد تتبّع OTel مُصدَّرًا من تطبيق تجريبي للخدمات المصّغرة. ويتضمن كل صف العمودين ResourceAttributes وSpanAttributes، ويحتويان على أزواج مفتاح-قيمة ديناميكية على شكل خرائط JSON. احفظ الملف في دليل يسهل الرجوع إليه، على سبيل المثال ~/data/data-otel-traces.csv.نزّل data-otel-traces.csv (2.9 MB)إليك شكل صف واحد:
2

أنشئ الجدول وحمّل البيانات

شغّل clickhouse-local وأنشئ الجدول التالي بمخطط يتوافق مع ملف CSV. عمود المفتاح هو ResourceAttributes Map(LowCardinality(String), String) — ويُستخدم LowCardinality مع نوع المفتاح لأن مفاتيح سمات OTel مأخوذة من مجموعة صغيرة نسبيًا ومتكررة.
الآن حمّل ملف CSV باستخدام محرّك الجدول file. عدّل المسار ليتوافق مع المكان الذي حفظت فيه الملف:
تأكد من أنه تم تحميل البيانات:
من المفترض أن ترى 6,120 صفًا.
3

الاستعلام عن البيانات

الوصول إلى مفتاح محدد — استخدم صيغة الأقواس المربعة لاستخراج قيمة من map. إذا لم يكن المفتاح موجودًا في صف معيّن، فستحصل على القيمة الافتراضية لنوع القيمة (سلسلة فارغة من النوع String):
التصفية حسب قيمة في map — اعثر على جميع spans المرتبطة باسم خدمة محدد:
تحقّق مما إذا كان المفتاح موجودًا — لا يحتوي كل span على بيانات Kubernetes الوصفية. استخدم mapContains لمعرفة أيّها يحتوي عليها:
افحص جميع المفاتيح الموجودة في كامل مجموعة البيانات — وهذا مفيد لفهم ما الذي تنتجه أدوات الرصد المضمّنة:
فكِّك Map إلى صفوف باستخدام ARRAY JOIN — حوِّل كل زوج مفتاح-قيمة إلى صف مستقل، مما يفيد في إنشاء فهرس للسمات أو في تعبئة لوحات المعلومات:
رشّح قيم Map باستخدام mapFilter — استخرج فقط السمات المرتبطة بـ Kubernetes من كل Span:
اعثر على مقاطع التتبّع الخاصة بالأخطاء وسياق المورد المرتبط بها — اجمع بين مرشحات الأعمدة العادية والوصول إلى map:
4

التجميع عبر خرائط Map باستخدام المبدِّل -Map

يتيح المبدِّل التجميعي -Map في ClickHouse تطبيق أي دالة aggregate على عمود Map بحيث تعمل على كل مفتاح بشكل مستقل. وتكون النتيجة أيضًا Map — مع مُدخل واحد لكل مفتاح، يتضمن القيمة المُجمَّعة. ويكون هذا مفيدًا بشكل خاص مع metrics في OTel، حيث تُخزَّن counters أو gauges كقيم في map.للتوضيح، أنشئ table صغيرًا للـ metrics حيث يسجّل كل row أعداد رموز حالة HTTP بصيغة Map(String, UInt64):
استخدم الآن sumMap لحساب إجمالي مرات الظهور لكل رمز حالة في كل خدمة:
تعمل اللاحقة -Map مع أي دالة تجميع، لذا يمكنك استخدام minMap أو maxMap أو avgMap بالقدر نفسه من السهولة:
يمكنك أيضًا دمجه مع مُركِّبات أخرى. على سبيل المثال، يتيح لك sumMapIf إجراء تجميع شرطي — إذ لا تُجمَع هنا إلا نوافذ الدقائق التي كانت الخدمة تحتوي فيها بالفعل على أخطاء:
لماذا يهم هذا بالنسبة إلى OTel: عندما يكتب OTel Collector تفاصيل رموز الحالة لكل دقيقة في ClickHouse، تتيح لك sumMap تجميعها في إجماليات لكل ساعة أو لكل يوم ضمن استعلام واحد — من دون ARRAY JOIN، ومن دون إلغاء التمحور، ومن دون الحاجة إلى معرفة المجموعة الكاملة للمفاتيح مسبقًا. ويُدرَج تلقائيًا في النتيجة أي مفتاح يظهر في أي صف.
5

حسّن الأداء للمفاتيح التي يُكثر الاستعلام عنها

إذا وجدت نفسك تُجري التصفية باستمرار على المفتاح نفسه في 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).

الخطوات التالية

اطّلع بعد ذلك على أدلة البدء السريع التالية: أو تعمّق أكثر بالرجوع إلى الوثائق المرجعية:
ClickHouse Academy — Master ClickHouse with expert-designed training for every skill level

Check out the ClickHouse academy for on-demand and live training

آخر تعديل في ٢٨ أغسطس ٢٠٢٦