كيف تتابع استخدام API وسجلات التدقيق في Taskfolk

‏سلّمت مفتاح API لأحد الوكلاء الأسبوع الماضي. والآن يبدو شيء ما في غير محله داخل مشروع WEB. تذكرة لم تلمسها انتقلت من Backlog إلى Done، بلا تعليق وبلا سبب واضح. قبل أن تتهم أحدًا، إنسانًا كان أو آلة، تريد أن تعرف ما الذي كان يفعله هذا المفتاح فعلًا: كم عدد الطلبات التي يرسلها، وهل يخطئ، وهل غيّر أحدهم Webhook دون أن تنتبه. لهذا الغرض وُجد تبويبا Usage وAudit في وحدة المطوّر. إتقان إدارة استخدام API وسجل التدقيق يعتمد أساسًا على معرفة أيّ من هذين التبويبين يجيب عن أيّ سؤال، وأيّهما لن يجيب أبدًا.

إليك الخلاصة قبل التفصيل. يخبرك Usage بحجم الحركة التي يتلقاها API في مساحة عملك وكم منها يفشل. ويخبرك Audit من الذي أنشأ أو أبطل أو غيّر المفاتيح وWebhooks وعملاء OAuth، ومتى وقع شذوذ. لا أحد منهما يخبرك أن «الوكيل نقل WEB-12 إلى Done». هذه الحقيقة تعيش في مكان ثالث: سجل النشاط الخاص بالتذكرة نفسها. أبقِ هذه السطوح الثلاثة واضحة في ذهنك، وتتوقف عن البحث في التبويب الخطأ في اللحظة التي تكون فيها متوترًا.

اثبت على أمر واحد منذ البداية: كلا التبويبين مبني على ClickHouse ويعمل بأفضل جهد. هذا يمنحك وقت تشغيل ثابتًا ويكلّفك جزءًا يسيرًا من الاكتمال. سأعود إلى هذه الفاتورة لاحقًا.

ما الذي يغطّيه فعلًا عرض إدارة استخدام API وسجل التدقيق

سؤالان، ولكلٍّ منهما موطنه.

يجيب Usage عن الحجم والصحة. كم طلبًا وصل هذا الأسبوع؟ ما نسبة ما أخفق منها؟ أيّ نقاط النهاية تتعرض للضغط، وكم هو قبيح الذيل البطيء؟ إن كنت قد ربطت تكاملًا للتو، فهذا هو المكان الذي تتأكد فيه من أنه يتصرف كما يجب: عدد طلبات ثابت، أخطاء تكاد تكون معدومة، وزمن استجابة لا يقفز فجأة.

يجيب Audit عن دورة الحياة. من الذي سكّ هذا المفتاح؟ من الذي أبطل ذاك؟ من الذي غيّر حد معدل مفتاح في الثانية صباحًا؟ هل سُجّل عميل OAuth لا تعرفه؟ هل أطلق كاشف الشذوذ إنذاره لأن مفتاحًا بدأ فجأة يحذف أشياء بالجملة؟ كل واحد من هذه أحداث منفصل له Actor وKind وحمولة JSON.

الفخّ: يفتح الناس Audit متوقعين أن يروا «الوكيل نقل WEB-12 إلى Done»، وهو ليس هناك. لم يكن ليكون هناك أصلًا. يسجّل تبويب Audit أحداث دورة حياة مفاتيح API وWebhook وOAuth، إضافة إلى حالات الشذوذ. وهو لا يسجّل تغييرات حقول التذاكر. تلك تعيش في سجل النشاط غير القابل للتعديل على صفحة تفاصيل كل تذكرة. فالنموذج الذهني الحقيقي هو ثلاثة سطوح، لا اثنان:

flowchart TD
    Q[What do you want to know?] --> T[How much traffic, how healthy]
    Q --> L[Who touched keys, webhooks, OAuth]
    Q --> W[What changed on an issue]
    T --> U[Usage tab]
    L --> A[Audit tab]
    W --> F[Issue Activity feed]

‏Usage للحركة والأخطاء. Audit لدورة حياة بيانات الاعتماد والتكاملات. وسجل النشاط في التذكرة لما فعله الوكيل فعلًا.

افتح وحدة المطوّر (ومن يُسمح له بالدخول)

توجد الوحدة على /w/[workspace]/knowledge/developer. ضع فيها معرّف مساحة عملك (slug) لتصل إلى لوحة تصف نفسها بوضوح: «API keys, skills, webhooks, and usage for this workspace». إنها تقع تحت مساحة العمل، لا تحت مشروع واحد، فكل ما هنا يشمل مساحة العمل كلها.

الآن الجزء الذي يوقع الناس في الحيرة. لوحة المطوّر بأكملها محكومة بصلاحية workspace.edit_settings. وعمليًا هذا يعني أن دوري owner وadmin وحدهما يدخلان. إن كنت member أو viewer ولصقت هذا الرابط، فالخادم لا يعطيك عرضًا مبسّطًا ولا حالة فارغة. بل يعيد توجيهك إلى صفحة مساحة العمل الرئيسية.

لا يوجد عرض للاستخدام للقراءة فقط لزملاء الفريق العاديين. لذا حين يقول مطوّر في فريقك «لا أستطيع رؤية استخدام API»، فهذا ليس خللًا. هذا هو نموذج الصلاحيات. ارفع دوره، أو استخرج له الأرقام بنفسك.

بمجرد دخولك، تنقلك التبويبات في الأعلى بين Usage وAudit. الشريط نفسه يحمل Keys، حيث يعيش عنصر التحكم بحد المعدل، وهو حيث سأرسلك لاحقًا. التبويب مدرج في الرابط، لذا فإن ?tab=usage و?tab=audit قابلان للحفظ في المفضلة والمشاركة مع أيّ شخص يملك صلاحية admin هو الآخر.

إن لم تكن قد أنشأت مفتاحًا أو استدعيت نقطة نهاية بعد، فإن كيفية استخدام REST API يغطي هذه الأرضية أولًا ويتكامل بشكل طبيعي مع هذا المقال.

اقرأ تبويب Usage: بطاقات الإحصاء والمدى الزمني

ابدأ باختيار نافذتك الزمنية. ثلاثة أزرار في الأعلى: Last 7d وLast 30d وLast 90d. يرتدي الزر النشط لون الإشارة الأصفر، فتعرف دائمًا أيّ مدى تنظر إليه. اضغط مدى مختلفًا فيعيد تشغيل التجميع على ClickHouse، عارضًا تلميح «Loading…» صغيرًا أثناء تنفيذ الاستعلام. طابق النافذة مع السؤال. تصحّح شيئًا حدث بالأمس؟ 7d. تراقب اتجاهًا بطيئًا؟ 90d.

تحت أزرار المدى أربع بطاقات إحصاء. اقرأها من اليسار إلى اليمين.

• ‏Requests هو إجمالي عدد الاستدعاءات في النافذة.
• ‏Errors هو عدد ما فشل منها. تتحول هذه البطاقة إلى اللون الوردي لحظة تجاوزها الصفر، فبطاقة Errors الوردية إشارتك إلى أن شيئًا ما ليس على ما يرام.
• ‏Error rate يعبّر عن ذلك كنسبة مئوية بمنزلتين عشريتين. وهو الرقم الذي تريد فعلًا تتبعه عبر الزمن، لأن أعداد الأخطاء الخام تتضخم مع الحركة بينما المعدل لا يفعل.
• ‏Peak p95 رقم زمن استجابة بالميلي ثانية.

يستحق Peak p95 قراءة ثانية، لأن إساءة فهمه سهلة. إنه ليس p95 واحدًا محسوبًا عبر النافذة كلها. إنه القيمة القصوى لزمن استجابة p95 لكل يوم عبر أيام النافذة. فإذا استقرت ستة أيام عند 120ms وقفز يوم سيّئ واحد إلى 900ms، فإن Peak p95 يقرأ 900ms. هذا مقصود. فهو يُبرز أسوأ أيامك بدل أن يترك متوسطًا سلسًا يدفنه. حين يبدو مرتفعًا، اذهب وابحث عن ذلك اليوم.

قراءة ملموسة. أنت تفحص الوكيل الذي سلّمته مفتاحًا على WEB. تختار Last 7d وترى Requests بقيمة 4,120 وErrors بقيمة 0 وError rate بقيمة 0.00% وPeak p95 بقيمة 180ms. هذا تكامل حسن السلوك. حجم ثابت، لا شيء يفشل، زمن استجابة محكم. الآن تخيّل Errors مستقرًا باللون الوردي عند 47 وPeak p95 يقرأ 2,400ms. يوم مختلف. عندها تنتقل مباشرة إلى المخططات لتكتشف أيّ يوم وأيّ نقطة نهاية.

اقرأ مخططات الاستخدام الثلاثة

تحت البطاقات ثلاثة مخططات. تحوّل معًا «هناك خطأ ما» إلى «إليك ما الخطأ».

‏Requests over time مخطط مساحي مملوء باللون الأصفر. يعرض المحور السيني تواريخ MM-DD، ويستخدم المحور الصادي الترميز المضغوط (k للآلاف وM للملايين)، ويمنحك التمرير فوقه تلميحًا حقيقيًا بالعدد الدقيق لذلك اليوم. وهناك أيضًا شارة صفراء صغيرة تقرأ «{n} days» تخبرك كم يومًا أعاد بيانات فعلًا.

هذه الشارة أنفع مما تبدو. إن اخترت Last 30d لكن الشارة تقول «6 days»، فإن مفتاحك لم يكن نشطًا إلا لستة أيام، والامتداد المسطح قبل ذلك ليس معناه «انخفضت الحركة». معناه «لم يكن هناك شيء بعد».

‏Error rate over time هو الشكل نفسه باللون الوردي، بمحور صادي بالنسبة المئوية، محسوبًا لكل يوم على أنه الأخطاء مقسومة على الطلبات. الخط المسطح على القاع هو ما يبدو عليه الوضع الصحي. أما النتوء في يوم بعينه فهو ختمك الزمني.

‏Top endpoints هو تفصيل بأشرطة أفقية باللون السماوي، حتى عشر نقاط نهاية مرتبة حسب حجم الطلبات. يعرض كل شريط عدد طلبات نقطة النهاية بصيغة مضغوطة، وحين تكون لتلك النقطة أخطاء، يُلحق النسبة المئوية للأخطاء بلاحقة «err»، فقد تقرأ 1.2k · 3.4% err. تظهر نقاط النهاية التي تعذّر تسميتها على هيئة «(unknown)». وإن كانت النافذة فارغة، فتقرأ «No endpoint activity in this window».

إليك كيف تستخدم الثلاثة معًا. ارتفاع في مخطط معدل الأخطاء في تاريخ 07-12 مثلًا يعطيك اليوم. تنظر إلى Top endpoints لترى أيّ شريط يحمل نسبة أخطاء. حين يتطابق الارتفاع مع نقطة نهاية واحدة تُظهر «err»، فذلك دليلك القاطع. صار لديك الآن اليوم ونقطة النهاية، ويمكنك أن تذهب لتقرأ ذلك المُعالِج أو مسار كود الوكيل الذي يستدعيه.

أمر يوقع الناس في الحيرة: استجابات 429 تُحتسب هنا كأخطاء. إن كان وكيلك يصطدم بحد معدل، فسيظهر ذلك كمعدل أخطاء مرتفع، مطويًّا مع الإخفاقات الحقيقية بدل أن يُفصل وحده. فإن ارتفع معدل الأخطاء لكن نقاط النهاية تبدو سليمة ولا شيء يرمي خطأ، فاشتبه في حد المعدل واذهب لفحص السقف.

حين يكون تبويب Usage فارغًا (وما الذي لن يعرضه)

حالتا الفراغ والخطأ صادقتان. معرفتهما يوفّر عليك أن تقرر أن التبويب معطّل.

• «No API usage yet» مع سطر «Once your API keys start making requests, usage charts will appear here» هي الحالة الطبيعية لمفتاح جديد لم يستدعِه أحد. ليست خطأ. لم يحدث شيء.
• «Could not load usage data. Try again shortly.» تعني أن استعلام ClickHouse نفسه فشل. تعثّر مخزن التحليلات، لا أنه ليس لديك حركة. انتظر لحظة وأعد التحميل.

الآن الحدود الحقيقية، حتى لا تبحث عن أشياء غير موجودة. يقرأ تبويب Usage جدولًا مُجمّعًا مسبقًا، papi.api_usage_daily، فكل شيء لكل يوم. لا يوجد عرض بالساعة، ولا تفصيل لكل طلب، ولا تغذية مباشرة لحظية. إن احتجت أن تعرف بالضبط أيّ طلب فشل عند 14:32، فهذا التبويب لن يعطيك ذلك. توجد صفوف خام لكل طلب في الخلفية، لكنها ليست على هذا التبويب.

وأما ما يفاجئ الناس أكثر: يعرض تبويب Usage دائمًا مساحة العمل بأكملها. لا يوجد تصفية لكل مفتاح في الواجهة. فإن تشارك وكيلان مساحة عمل واحدة، فحركتهما مجموعة هنا. لا تقضِ عشر دقائق تبحث عن قائمة منسدلة غير موجودة.

لعزل مفتاح واحد، استخدم نقطة نهاية الاستخدام لكل مفتاح بدلًا من ذلك. تحتاج إلى مفتاح بنطاق api_keys:read، وتأخذ from وto كتواريخ ISO (الافتراضي: آخر 30 يومًا، بحد أقصى 90)، وتعيد سلسلة لكل يوم:

curl -s "https://taskfolk.ai/api/v1/workspaces/acme/api-keys/KEY_ID/usage?from=2026-07-01&to=2026-07-15" \
  -H "Authorization: Bearer tfk_live_YOUR_KEY"

const res = await fetch(
  "https://taskfolk.ai/api/v1/workspaces/acme/api-keys/KEY_ID/usage?from=2026-07-01&to=2026-07-15",
  { headers: { Authorization: "Bearer tfk_live_YOUR_KEY" } },
);
const { data } = await res.json();
console.log(data.totals);

import requests

res = requests.get(
    "https://taskfolk.ai/api/v1/workspaces/acme/api-keys/KEY_ID/usage",
    params={"from": "2026-07-01", "to": "2026-07-15"},
    headers={"Authorization": "Bearer tfk_live_YOUR_KEY"},
)
print(res.json()["data"]["totals"])

الاستجابة نقطة واحدة لكل يوم إضافة إلى الإجماليات، مع زمن استجابة p50/p95/p99 لكل يوم:

{
  "data": {
    "key_id": "0197f3a1-2b4c-7d5e-8f90-1a2b3c4d5e6f",
    "from": "2026-07-01",
    "to": "2026-07-15",
    "granularity": "day",
    "series": [
      { "date": "2026-07-01", "requests": 512, "errors": 0, "p50_ms": 45, "p95_ms": 140, "p99_ms": 320 }
    ],
    "totals": { "requests": 4120, "errors": 0, "p95_ms": 180 }
  }
}

هذه، أو أن تمنح كل وكيل مساحة عمل خاصة به، هي طريقة فصل حركة وكيل عن آخر.

حقّق في أحداث دورة الحياة على تبويب Audit

انتقل إلى Audit فيتغير الشكل تمامًا. أنت الآن تقرأ جدولًا مرتّبًا زمنيًا عكسيًا، الأحدث أولًا، بأربعة أعمدة: Time وActor وKind وPayload.

في الأعلى شرائح تصفية: All وapi_key.* وwebhook.* وoauth.* وanomaly.detected. اضغط واحدة فيعيد الاستعلام؛ وتضيء الشريحة النشطة باللون الأصفر. هذه أداتك الرئيسية لقطع الضجيج. تحقّق في شيء يخص المفاتيح؟ اضغط api_key.* فيتنحّى الباقي.

تحتاج قراءة الأعمدة إلى لحظة لتتعلمها. Actor مختصر. يعرض «user» إضافة إلى أول ثمانية أحرف من المعرّف حين يكون الفاعل إنسانًا، و«key» إضافة إلى أول ثمانية أحرف حين يكون مفتاح API آخر هو الفاعل، أو شرطة بسيطة حين لا ينطبق أيّ منهما (بعض الأحداث الصادرة عن النظام بلا فاعل). Kind شارة ملوّنة لتتمكن من المسح البصري حسب النوع: وردي للشذوذ، سماوي لـ webhook، بنفسجي لـ oauth، أصفر لـ api_key. يعرض Payload نحو أول 80 حرفًا من JSON الخام. يكفي لالتقاط الفكرة، لا القصة كاملة.

في الأسفل، ينقلك Load more عبر صفحات الأحداث الأقدم بترقيم صفحات بالمؤشر، خمسون صفًا لكل صفحة، مرتكزًا على الطابع الزمني لآخر صف. يقرأ «Loading…» أثناء الجلب. لا يوجد منتقي تواريخ ولا بحث نصّي حر هنا، فـ Load more إضافة إلى شرائح التصفية هي طقم التنقل بأكمله. إن لم تكن هناك أحداث، ترى «No audit events yet» مع «API key, webhook, and OAuth lifecycle events will appear here as they happen». وعند فشل في الخلفية، «Could not load audit events».

مثال عملي. عد إلى تلك النقلة غير المتوقعة على WEB. تشتبه في أن مفتاحًا أُبطل أو غُيّر حينها. اضغط api_key.*. يضيق الجدول ليقتصر على دورة حياة المفاتيح. امسح عمود Time إلى اليوم الصحيح، اقرأ Actor لترى هل فعل ذلك مستخدم أم مفتاح آخر، وافحص شارة Kind لمعرفة هل كان إبطالًا أم تغيير إعدادات أم تغيير حد معدل. أقل من دقيقة، وتعرف من لمس ماذا.

الصفوف الحديثة نفسها تظهر أيضًا كقائمة قصيرة على تبويب Overview في وحدة المطوّر، لمحة سريعة عن «recent developer activity». إنها أول بضعة صفوف من الاستعلام نفسه، مفيدة حين تريد جسّ النبض دون فتح الجدول الكامل.

افتح صفًا لرؤية تفاصيل الحدث الكاملة

معاينة الـ 80 حرفًا مجرد إغراء. اضغط أيّ صف فتفتح نافذة منبثقة، عنوانها نوع الحدث، تعرض كل شيء.

داخل نافذة «Audit event» تحصل على Time، وشارة Kind مرة أخرى، وActor معروضًا كمعرّف كامل (مسبوق بـ user: أو key:)، وTarget (المعرّف الكامل للهدف، أو شرطة إن لم يكن للحدث هدف)، والحمولة Payload كاملة كـ JSON منسّق ومُزاح بمسافات بادئة. هنا تقرأ السياق الحقيقي بدل التخمين من سطر مبتور.

هذه النافذة هي المكان الوحيد الذي تعيش فيه بعض المعلومات. خذ حالة شذوذ. على الجدول تقرأ مجرد «anomaly.detected» بشارة وردية، لأن كل شذوذ مخزّن تحت هذا النوع الواحد. أما النوع المحدد، سواء أكان delete_surge أم multi_ip_key_use أم unauthorized_ip_spike، فهو داخل الحمولة، لا في النوع. الطريقة الوحيدة للتمييز بين شذوذ وآخر هي فتح الصف وقراءة JSON. والأمر نفسه لتغيير webhook أو منح OAuth: النوع يعطيك الفئة، والحمولة تعطيك التفاصيل.

تحفّظ صادق واحد. المعرّفات هنا هي UUID خام. يعرض الجدول أول ثمانية أحرف، وتعرض النافذة المعرّف الكامل مسبوقًا بـ user: أو key:، لكن لا واحد منهما يُترجَم إلى اسم أو بريد إلكتروني. فتقرأ user:9f3a1c2d... وعليك أن تطابقه بنفسك مع قائمة أعضائك أو مفاتيحك لتعرف صاحبه. دقيق، لكنه ليس ودودًا.

ما الذي لا يسجّله تبويب Audit

اقرأ هذا القسم على مهل، لأن الخطأ فيه يرسلك للبحث في المكان الخطأ في أسوأ لحظة.

إليك المجموعة الدقيقة من الأنواع التي يصدرها تبويب Audit، وهي المجموعة الكاملة:

• api_key.created, api_key.revoked, api_key.rate_limit_changed, api_key.settings_changed
• oauth_client.registered, oauth_client.revoked, oauth_grant.issued, oauth_token.minted, oauth_token.revoked
• anomaly.detected

شريحة التصفية webhook.* محجوزة لأحداث دورة حياة webhook المستقبلية؛ وهي حاليًا لا تعيد شيئًا، لأن تلك الأحداث لا تُصدَر بعد. تلك هي القائمة بأكملها. بيانات الاعتماد والتكاملات. لاحظ ما هو غائب: تعديلات التذاكر، والتعليقات، وتغييرات الحالة، ونقلات اللوحة، ودعوات الأعضاء، وتغييرات الأدوار. لا شيء من ذلك مسجّل هنا. رغم الاسم، تبويب Audit ليس «سجل تدقيق لكل عملية كتابة».

فأين تعيش تلك الأشياء إذن؟ في مكانين آخرين.

تغييرات المنتج على مستوى التذكرة (تغيير المُسند إليه، ونقلة حالة، وتعديل وصف، سواء فعلها إنسان في الواجهة أو وكيل عبر API) تُسجَّل في سجل النشاط غير القابل للتعديل الخاص بتلك التذكرة على صفحة تفاصيلها. ذلك هو السطح الذي سيخبرك فعلًا أن «الوكيل نقل WEB-12 إلى Done». إن كنت تدقّق ما فعله وكيل بعملك، فذلك هو السجل الذي تريده. هناك مقال كامل عن ترسيخ هذه العادة في احتفظ بسجل تدقيق لتغييرات وكلاء الذكاء الاصطناعي.

أما التغييرات على مستوى مساحة العمل ومستوى الأعضاء (إضافة عضو، تغيير دور، تهيئة SSO، مزامنة SCIM) فتذهب إلى جدول MariaDB منفصل اسمه audit_log غير معروض في أيّ مكان في تبويب Audit هذا في وحدة المطوّر. مخزن مختلف، سطح مختلف، غير معروض هنا. لا تخلط بين الثلاثة. تبويب Audit في وحدة المطوّر ضيّق عن قصد: إنه دفتر بيانات الاعتماد والتكاملات، لا أكثر.

وأما فاتورة «أفضل جهد» التي وعدت بها. كتابات التدقيق تُرسَل وتُنسى. فإن كان ClickHouse معطّلًا أو بطيئًا في اللحظة التي يُبطل فيها مفتاح، فالإبطال ينجح مع ذلك، لكن سطر التدقيق قد يُسقَط بصمت. حدث التغيير؛ وسِجلّه قد لا يحدث. عامل سجل التدقيق كسجل جيد جدًا، لا كضمان قانوني للاكتمال. لأيّ شيء تحتاج إثباته، لا تتّكئ على سطر واحد قد يسقط إن ساء الحظ.

اضبط حد معدل لكل مفتاح (وكيف يبدو التطبيق)

هذا العنصر ليس على Usage ولا Audit. إنه يعيش على تبويب Keys، ويستحق المشوار، لأن حدّ المعدل غالبًا هو الجواب عن «لماذا يرتفع معدل أخطائي».

على تبويب Keys، يعرض كل مفتاح سقفه في عمود Rate limit، فيقرأ إما «N/min» أو «Workspace default». لتغييره، استخدم «Edit rate limit»، الذي يفتح حقلًا معنونًا «Requests per minute». اتركه فارغًا فيعود المفتاح إلى «Workspace default». اضبط رقمًا فيصبح ذلك سقف المفتاح الخاص.

التطبيق حقيقي ومن جانب الخادم. يشغّل Taskfolk مُحدِّدًا بنافذة منزلقة لكل مفتاح، وحين لا يكون للمفتاح سقف صريح فالافتراضي 600 طلبًا في الدقيقة. تحمل كل استجابة من /api/v1 الترويسات القياسية، X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset (طابع زمني unix)، فيستطيع عميل مكتوب جيدًا أن يراقب ميزانيته ويتراجع قبل أن يُرفض. حين يتجاوز مفتاح الحد، يبدو الرفض هكذا:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1752662400
Retry-After: 18

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Slow down and retry shortly.",
    "details": { "retry_after_ms": 17400 }
  }
}

العميل المهذّب يقرأ Retry-After، وينتظر، ويحاول مجددًا:

sequenceDiagram
    participant Agent
    participant API as Taskfolk API
    Agent->>API: request with Bearer key
    API-->>Agent: 200 plus rate limit headers
    Note over Agent,API: Remaining hits 0 within the minute
    Agent->>API: next request
    API-->>Agent: 429 rate_limited plus Retry After
    Agent->>Agent: wait the Retry After seconds
    Agent->>API: retry
    API-->>Agent: 200

أمران يربطان هذا بالتبويبين الآخرين. تغيير سقف مفتاح يصدر حدث تدقيق api_key.rate_limit_changed، فيظهر التغيير على تبويب Audit (صفِّ على api_key.* فتجده). وكما ذكرت، رفض 429 يُحتسب أخطاءً على تبويب Usage. لا تُرسم كسلسلة خنق منفصلة. فالوكيل المحدود بحد معدل يُقرأ كمعدل أخطاء مرتفع. إن كان معدل أخطاء Usage مرتفعًا لكن مُعالجاتك سليمة، فارفع السقف قليلًا أو أصلح إيقاع طلبات الوكيل، ثم راقب المعدل يستقر.

إن كنت تشكّل سلوك الوكيل على نطاق أوسع، فإن كيفية ضبط صلاحيات حقول الوكيل يغطي تقييد ما يستطيع مفتاح كتابته، وهو يتكامل جيدًا مع تحديد سرعة كتابته.

روتين عملي لمراقبة نشاط API لوكيلٍ ما

حوّله إلى عادة فتتوقف السطوح الثلاثة عن الشعور كشاشات متناثرة.

أسبوعيًا، افتح Usage على Last 7d. ألقِ نظرة على البطاقات الأربع. هل معدل الأخطاء يزحف صعودًا أسبوعًا بعد أسبوع؟ هل تبدّل مزيج نقاط النهاية، بأن تصدّرت نقطة نهاية جديدة فجأة مخطط الأشرطة لم يكن لهذا الوكيل شأن باستدعائها؟ خمس دقائق، وتلتقط الانحراف قبل أن يصير حادثة.

بعد أيّ تغيير على مفتاح أو webhook، أو في اللحظة التي يقع فيها شذوذ، افتح Audit. صفِّ على الشريحة المناسبة. تأكد أن التغيير كان منك، أو ممن توقعت، لا مفاجأة. إن كان شذوذًا، فافتح الصف واقرأ الحمولة لتعرف هل كان delete_surge أم مشكلة multi-ip، لأن النوع وحده لن يقول.

وحين تحتاج سجل العمل الفعلي، الشيء الذي بدأ هذا التمرين كله، فاذهب إلى التذكرة. افتح WEB-12، انزل إلى سجل النشاط الخاص بها، واقرأ السطر الحقيقي: نقلها الوكيل من In Review إلى Done في وقت محدد. لم يمتلك Usage ذلك قط. ولم يمتلكه Audit قط. سجل التذكرة نفسه وحده يمتلكه.

هذا هو النموذج بأكمله. Usage لمعرفة الكمّ والصحة. Audit لمعرفة من لمس بيانات الاعتماد والتكاملات. سجل نشاط التذكرة لما تغيّر في عملك. ثلاثة أسئلة، ثلاثة مواطن. بمجرد أن تعرف أيّها أيّ، تتوقف عن إضاعة الوقت في الخطأ منها.

افتح وحدة المطوّر الآن وافحص المفتاح الواحد الذي يهمّك أكثر من غيره.

إن كنت تربط وكيلًا بـ Taskfolk لأول مرة، فإن كيفية تثبيت Taskfolk كمهارة وكيل هو رفيق سير عمل المراقبة هذا.