تتبعات

تلتقط مسارات Trackio طلب المستخدم، واستجابة المساعد، والعمليات التي أنتجت هذه الاستجابة. افتح صفحة Traces في لوحة التحكم للبحث في الطلبات، وفحص عمليات النموذج والأدوات، وعرض إجماليات زمن الاستجابة، والرموز، والتكلفة، والحالة.

تسجيل محادثة

مرر Trace إلى trackio.log() مع رسائل بأسلوب OpenAI:

import trackio

trackio.init(project="research-agent")
trackio.log(
    {
        "trace": trackio.Trace(
            messages=[
                {"role": "user", "content": "Find agent training datasets."},
                {"role": "assistant", "content": "Here are three datasets..."},
            ],
            metadata={"session_id": "session-123", "environment": "production"},
        )
    }
)
trackio.finish()

يمكن أن تتضمن الرسائل tool_calls ونتائج tool. عندما لا يحتوي التتبع على نطاقات صريحة، يقترن لوحة التحكم بين تلك الاستدعاءات والنتائج لتشكيل عمليات أداة لتسهيل الفحص.

إضافة نطاقات التنفيذ

استخدم spans عندما تحتاج إلى قياسات زمنية، أو تسلسل هرمي، أو استخدام النموذج، أو التكلفة، أو حالة العملية. كل span هو قاموس. الحقول الدنيا هي id وname وkind:

trackio.Trace(
    messages=messages,
    spans=[
        {
            "id": "research",
            "name": "answer-research-question",
            "kind": "span",
            "start_time": "2026-08-19T12:00:00Z",
            "end_time": "2026-08-19T12:00:03Z",
            "status": "success",
        },
        {
            "id": "generation-1",
            "parent_id": "research",
            "name": "provider-request",
            "kind": "generation",
            "start_time": "2026-08-19T12:00:00Z",
            "end_time": "2026-08-19T12:00:01.2Z",
            "model": "my-model",
            "input": {"messages": messages},
            "output": {"text": "I will search for datasets."},
            "usage": {"input_tokens": 8439, "output_tokens": 188},
            "cost_usd": 0.0042,
            "status": "success",
        },
        {
            "id": "tool-1",
            "parent_id": "research",
            "name": "hf search",
            "kind": "tool",
            "start_time": "2026-08-19T12:00:01.3Z",
            "end_time": "2026-08-19T12:00:02Z",
            "input": {"query": "agent training datasets"},
            "output": {"datasets": ["example/dataset"]},
            "status": "success",
        },
    ],
)

حقول المدى المدعومة:

زمن التأخير في التتبع هو الوقت الفعلي من بداية أقدم نطاق إلى نهاية أحدث نطاق؛ وإذا لم يحمل أي نطاق end_time، يُستخدم بدلاً من ذلك أطول duration_ms فردي. تُجمع إجماليات الرموز والتكاليف من القيم على النطاقات الفردية، لذا يجب أن تصف usage وcost_usd العملية المحلية وليس إجمالي الوالد — فالوالد الذي يكرر إجماليات أبنائه سيؤدي إلى حساب مزدوج. لا يحافظ Trackio على كتالوج تسعير للنماذج؛ يجب أن يوفر القياس التكلفة الفعلية.

يُبلَّغ عن مقطع (span) بأنه فشل عندما يكون status الخاص به error أو failed، أو عندما يحمل error. بالنسبة للمقاطع المشتقة من الرسائل، يحدد نتيجة الأداة فشل عملية ما عندما تضبط الرسالة is_error أو error أو حالة خطأ status؛ ولا تحمل نتائج الأدوات بنمط OpenAI أي إشارة نجاح، لذا تُترك تلك العمليات دون حالة بدلاً من افتراض نجاحها.

فحص التتبعات من سطر الأوامر

ليس لوحة التحكم هي الطريقة الوحيدة لقراءة التتبعات. يعمل سطر الأوامر مع البيانات المحلية، أو مع مساحة باستخدام --space:

trackio list traces --project research-agent
trackio list traces --project research-agent --search "rate limit"
trackio get trace --project research-agent --trace-id <id>
trackio get trace-summary --project research-agent

trackio get trace يطبع شجرة التنفيذ مع زمن الاستجابة لكل نطاق، والنموذج، والرموز، والتكلفة، والأخطاء. trackio get trace-summary يجمع كل نطاق حسب اسم العملية ويبلغ عن عدد الاستدعاءات، والأخطاء، ومتوسط زمن الاستجابة وأسوأ حالة، واستخدام الرموز، والتكلفة — وهو مفيد للعثور على العملية التي تستهلك معظم التكلفة أو تفشل أكثر من غيرها. وكلاهما يقبل --json.

بالنسبة لغير ذلك، spans هو عمود بصيغة JSON، لذا يعمل json_each مع trackio query project:

trackio query project --project research-agent --sql "
SELECT json_extract(s.value, '\$.name') AS operation,
       SUM(COALESCE(json_extract(s.value, '\$.usage.input_tokens'), 0)) AS input_tokens
FROM traces, json_each(traces.spans) AS s
GROUP BY operation ORDER BY input_tokens DESC"

عرض التتبعات على Hugging Face Hub

يُكتب كل أثر مسجَّل أيضًا كملف جلسة وكيل .jsonl، بالصيغة التي يعرض بها عارض آثار الوكلاء في Hub. عند تشغيل Trackio على Space، يُركَّب الدلو في /data، لذا تُحفظ هذه الملفات في الدلو تحت traces/{project}/{run}/{trace_id}.jsonl — افتح ملفًا واحدًا من متصفح ملفات الدلو للتنقل عبر المحادثة، واستدعاءات أدواتها، ونتائجها.

تصدر Trackio تنسيق جلسات Pi (الإصدار 3)، وهو ما يدعمه Hub بشكل أصلي. كما يوثّق Hub تنسيقًا بسيطًا لتتبع الجلسات (Session Trace Simple Format)، لكن الملفات المكتوبة وفق ذلك المواصفة لا تُعرض حاليًا بواسطة العارض.

ملفات الجلسة هي ناتج عرض فقط، وليست المصدر الموثوق به أبدًا. تبقى جدول traces هو المرجع الرسمي، وكل ما هو موجود على هذه الصفحة — البحث، شجرة المسارات، trace-summary، SQL المباشر — يُقرأ منه. ما تحمله ملف الجلسة هو المحادثة الخطية، المُثراء من المسارات بالتفاصيل التي يمكن للمشاهد عرضها:

يُقرن استخدام الرموز (Token usage) بجولة المساعد التي أنتجته بدلاً من تكراره في كل جولة، حتى لا يقوم العارض بالعد المزدوج. أما التسلسل الهرمي للمقاطع (Span hierarchy)، وduration_ms، وmetadata لكل مقطع، ونوع المقاطع غير المتعلقة بالأدوات kind، فلا مكان لها في هذا التنسيق وتبقى في SQLite.

تقع ملفات الجلسة بجانب بادئة trackio/ بدلاً من داخلها، لذا فإن أوامر سطر الأوامر trackio التي تُزامن الدلو نزولاً لا تسحب نسخة ثانية من كل تتبّع. اضبط TRACKIO_TRACE_SESSIONS_DIR لكتابتها في مكان آخر.

بيانات وصفية على مستوى التتبع

تُعدّ المقاطع (Spans) المصدر المفضّل للحصول على بيانات زمن الاستجابة والتكلفة والحالة. عندما لا يحتوي التتبع (Trace) على مقاطع، أو عندما تُغفل مقاطعه هذه القيم، فإن لوحة التحكم تلجأ إلى مفاتيح metadata هذه:

بحث

تبحث عملية التتبع في محتوى الرسالة، وبيانات التتبع الوصفية، وفي كل من id، name، kind، model، status، error، وmetadata الخاصة بكل نطاق. لا يتم فهرسة حمولات input وoutput الخاصة بالنطاقات: فهي تُكرر المحادثة بأكملها بشكل روتيني مع كل عملية توليد، لذا فإن فهرستها ستضاعف حجم التتبع المخزّن مقابل قيمة بحث ضئيلة.

تُخزَّن قيم الوسائط المتداخلة في Trackio الموجودة في الرسائل أو البيانات الوصفية أو مدخلات المدى أو مخرجات المدى إلى جانب التتبع، وتُعرض الصور بشكل مضمّن في أداة الفحص.