DQL fieldsMove jsonExtract: التعامل مع سجلات JSON دون الكتابة فوق الحقول الموجودة

DQL fieldsMove jsonExtract: استخرج مفاتيح سجل JSON دون الكتابة فوق حقل موجود، وجمّع حقول k8s في سجل متداخل بخطوات عملية من المرجع الرسمي.
DQL fieldsMove jsonExtract : manipuler des logs JSON sans écraser les champs existants

DQL fieldsMove jsonExtract: هذان الأمران أُعلن عنهما في ملاحظات إصدار SaaS الخاصة بالسبرنت 347 (16 سبتمبر 2026)، ويساعدان على ترتيب سجلات JSON. الأمر jsonExtract يحوّل مفاتيح كائن JSON إلى حقول. والأمر fieldsMove يضع حقول المستوى الأول داخل سجل متداخل. ولا يكتب أي منهما فوق حقل موجود.

المشكلة معروفة في التشغيل. يصل سجل تطبيق فيه حقل content يحمل نص JSON، وفي هذا النص مفتاح loglevel بينما للسجل حقل loglevel أصلًا. مع محلل بسيط يفوز أحدهما بصمت، فتقرأ استعلامات التنبيه القيمة الخطأ. هنا يبقى التعارض ظاهرًا، وأنت تقرر أين تحفظه.

يتبع هذا المقال المرجع الرسمي للغة DQL (صفحتا «DQL extraction and parsing commands» و«DQL selection and modification commands»، قُرئتا في 27 أكتوبر 2026) وملاحظات السبرنت 347. ينطبق على Dynatrace SaaS (Grail وDQL) وليس على Managed. توضيح للأمانة: لم تنفذ span.observer أيًّا من هذه الاستعلامات. الأمثلة المأخوذة من المرجع منسوخة كما هي، والنتائج المعروضة هي ما تذكره الوثائق.

DQL fieldsMove jsonExtract: ما تقوله ملاحظات السبرنت 347

  • fieldsMove: ينقل حقول المستوى الأول المطابقة لنمط include (باستثناء المطابقة لـ exclude) إلى حقل جديد يحتوي سجلًا متداخلًا، ويزيلها من المستوى الأول. إنه المقابل للأمر fieldsFlatten.
  • jsonExtract: يحلل نص JSON ويضع مفاتيح المستوى الأول للكائن في حقول السجل. تذكر الملاحظات أنه لا يكتب فوق حقل موجود أبدًا، وأن المفاتيح المتعارضة يمكن جمعها في حقل مخصص.
  • يكمل الأمران عائلة أوامر fields (fieldsKeep وfieldsRemove وfieldsRename). يضيف الإصدار نفسه دوالَّ للتعامل مع السجلات (recordField وrecordFields وrecordFromFields وrecordKeys وrecordValues) ولا يفصّلها هذا المقال.

صيغة fieldsMove

صيغة المرجع هي:

fieldsMove fieldName [, include: {pattern [, ...]}] [, exclude: {pattern [, ...]}]

يلزم تحديد واحد على الأقل من المعاملين include وexclude. تمنع هذه القاعدة نقل كل الحقول عن طريق الخطأ. الوسيط الأول هو اسم الحقل الجديد الذي سيستقبل السجل.

هذا أول مثال في المرجع: كل حقل يبدأ اسمه بـ k8s. ينتقل إلى حقل اسمه k8s. ويبقى الحقلان event وstatus في الجذر.

data record(
  event = "failed to find product",
  status = "NONE",
  k8s.namespace.name = "unguard",
  k8s.pod.name = "unguard-user-simulator-28334535-tqqxt",
  k8s.pod.uid = "d3e93267-e7f9-4a2d-b5df-dc2ac226a7ce"
)
| fieldsMove k8s, include: {"k8s.*"}
استعلام DQL fieldsMove k8s مع include k8s.* على سجل تجريبي، والنتيجة التي يذكرها المرجع: event و status في الجذر وثلاثة حقول k8s داخل سجل متداخل
Source : docs.dynatrace.com

المثال الثاني في المرجع يضيف exclude: {k8s.namespace.name}: يبقى الحقل k8s.namespace.name في الجذر ويدخل الحقلان الآخران في k8s. يفيد ذلك عندما يكون الحقل مرشحًا أو بعدًا في لوحاتك ويجب أن يبقى في المتناول.

| fieldsMove k8s, include: {"k8s.*"}, exclude: {k8s.namespace.name}

صيغة jsonExtract

jsonExtract input [, conflicts]
  • input (إلزامي): تعبير نصي يحتوي كائن JSON.
  • conflicts (اختياري): اسم الحقل الذي تُحفظ فيه المفاتيح المتعارضة. من دونه تُهمل المفاتيح المتعارضة ولا يُنشأ حقل إضافي.

مع conflicts يحتوي الحقل سجلًا فارغًا إذا لم يحدث أي تعارض. وإذا كرر كائن JSON مفتاحًا فتُحفظ قيمة واحدة فقط دون ضمان لأي منها.

الأنواع تتبع JSON: الرقم إلى long أو double، والمنطقي إلى boolean، والنص إلى string، وnull إلى null، والمصفوفة إلى array، والكائن إلى record.

خطوات عملية: استخراج JSON دون خسارة شيء

الخطوة 1 — رؤية تعارض المفاتيح

يستخدم مثال المرجع سجلًا فيه loglevel = "WARN" أصلًا، بينما يحتوي JSON في content على "loglevel":"ERROR":

data record(timestamp = now(),
            content = """{"loggerName":"Log4JGenerator", "threadId":33, "loglevel":"ERROR"}""",
            loglevel = "WARN",
            log.source = "/var/log/messages")
| jsonExtract content, conflicts: collisions
استعلام DQL jsonExtract content مع conflicts collisions، والنتيجة التي يذكرها المرجع: يبقى loglevel بقيمة WARN، ويصبح loggerName و threadId حقولًا، ويحتوي collisions على loglevel ERROR
Source : docs.dynatrace.com

النتيجة التي يصفها المرجع: يحتفظ loglevel بالقيمة WARN، ويظهر loggerName وthreadId كحقلين، ويحتوي collisions على loglevel: ERROR. القيمة الأصلية سليمة وقيمة JSON تبقى متاحة.

الخطوة 2 — تطبيق jsonExtract على سجلات حقيقية

في Grail يجب أن تكون كل حقول التدفق معروفة عند تخطيط الاستعلام. ليس للسجلات مخطط ثابت، لذلك يضع المرجع الأمر fields قبل jsonExtract. هذا مثاله:

fetch logs
| filter startsWith(content, "{")
| fields timestamp, content
| jsonExtract content

يحتفظ المرشح بالأسطر التي يبدأ محتواها بقوس معقوف. ثم يحدد fields ما نبقيه، ويضيف jsonExtract مفاتيح JSON.

الخطوة 3 — ترتيب حقول Kubernetes

مثال آخر من المرجع على السجلات:

fetch logs
| fieldsMove k8s, include: {"k8s.*"}
استعلامان DQL من المرجع على السجلات: jsonExtract content بعد filter مع startsWith، و fieldsMove k8s مع include k8s.*
Source : docs.dynatrace.com

يبقى المستوى الأول مقروءًا، وتنتهي سمات Kubernetes داخل سجل k8s.

الخطوة 4 — ربط الأمرين

مثال كُتب للتوضيح ولم تنفذه span.observer. يجمع الأوامر السابقة؛ صيغة كل أمر مأخوذة من المرجع، أما التسلسل فمن عندنا ويحتاج إلى تحقق في بيئتك:

fetch logs
| filter startsWith(content, "{")
| fields timestamp, content, k8s.namespace.name, k8s.pod.name
| jsonExtract content, conflicts: collisions
| fieldsMove k8s, include: {"k8s.*"}

بعد fields لا يحتوي التدفق إلا الحقول المذكورة. وإذا حمل مفتاح في JSON اسم حقل محتفظ به، تذهب قيمة JSON إلى collisions.

كيف تتحقق أن الأمر يعمل

  1. شغّل أمثلة data record(...) أولًا: لا تعتمد على أي بيانات من بيئتك. قارن مع نتائج المرجع.
  2. على السجلات افتح الحقل collisions: السجل الفارغ يعني عدم وجود تعارض.
  3. تحقق من الأنواع: الرقم القادم من JSON يجب أن يكون رقميًا لا نصًا.
  4. أعد قراءة صفحة مرجع jsonExtract قبل استخدامه في استعلام إنتاجي، لأن توفر الأمر قد يختلف بحسب السياق (استعلام DQL أو معالج DQL في OpenPipeline).

أفضل الممارسات

  • حدد دائمًا حقل conflicts أثناء الاستكشاف: التعارض المهمل بيانات ضائعة.
  • رشّح أولًا (startsWith(content, "{")) كي لا تحلل أسطرًا ليست JSON.
  • أبقِ في الجذر الحقول التي تستخدمها مرشحاتك وSLO عبر exclude.
  • من ناحية الموثوقية، تنبيه يقرأ loglevel خاطئًا يطيل MTTR: عامل التعارضات كإشارة.

للمتابعة راجع https://span.observer/ar/advanced-dql-lookup-join-parse-ar/ (parse وlookup وjoin)، وhttps://span.observer/ar/dql-commands-filter-summarize-timeseries-ar/ للأوامر الأساسية، وhttps://span.observer/ar/dql-smartscape-ar/ للطوبولوجيا، وhttps://span.observer/ar/log-patterns-analysis-ar/ لتحليل السجلات.

روابط داخلية: DQL المتقدم، أوامر DQL، DQL Smartscape، تحليل أنماط السجلات.

الأسئلة الشائعة

هل يكتب jsonExtract فوق حقل موجود؟

لا. بحسب المرجع لا تُحذف الحقول الموجودة ولا يُكتب فوقها. المفاتيح المتعارضة تُهمل أو تُحفظ في الحقل الذي يحدده conflicts.

هل يمكن تشغيل fieldsMove دون include أو exclude؟

لا. يلزم أحد المعاملين على الأقل لتجنب نقل كل الحقول بالخطأ.

ما علاقته بـ fieldsFlatten؟

fieldsMove يجمع الحقول في سجل متداخل، و fieldsFlatten يفعل العكس فيرفع الحقول المتداخلة إلى الجذر، بحسب المرجع.

الخلاصة

يجعل fieldsMove و jsonExtract سجلات JSON أسهل قراءة دون فقدان بيانات. جرّب أمثلة data record أولًا ثم كيّفها مع سجلاتك.

المصادر: ملاحظات إصدار SaaS للسبرنت 347 ومرجع DQL للاستخراج والتحليل.

span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC. Dynatrace علامة تجارية لشركة Dynatrace LLC. ميزات SaaS تتطور بسرعة، فتحقق من توفرها في بيئتك وفي الوثائق الرسمية.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
Service backtrace Dynatrace : enquêter plus vite avec traces en superposition et chaînes d'appels Smartscape

Dynatrace Service backtrace: تحقيق أسرع بالتتبّعات الجانبية وسلاسل استدعاء Smartscape

Next Post
Import STIX/TAXII et Recorded Future dans Dynatrace : rapports de menace et IoC

STIX/TAXII Dynatrace وRecorded Future: استيراد تقارير التهديدات ومؤشرات الاختراق

Related Posts