BuilderIO/agent-native / packages/core/docs
agent-native-docs
UnverifiedHow to look up version-matched Agent-Native framework docs and source in node_modules. Use before coding against @agent-native/core APIs or advanced features.
content/locales/ar-SA/observability.mdx
View on GitHub---
title: "قابلية الملاحظة"
description: "تتبعات الوكيل، وعمليات التقييم، والتعليقات، وتجارب A/B، ولوحة التحكم المضمنة - كل ذلك بدون أي تكوين."
---
# إمكانية ملاحظة الوكيل
يحصل كل تطبيق أصلي للوكيل على إمكانية المراقبة خارج الصندوق. تعمل عمليات التتبع والتقييمات التلقائية وتعليقات المستخدمين وتجارب A/B بدون تكوين - حيث تظل جميع البيانات موجودة في قاعدة بيانات SQL الخاصة بالتطبيق.
تغطي هذه الصفحة مقاييس *جودة*الوكيل: التتبعات والتكلفة والتقييمات والتعليقات المخزنة في قاعدة بياناتك. بالنسبة لتحليلات _product_ (أحداث تطبيقك التي تتدفق إلى PostHog/Mixpanel/Amplitude)، راجع [Tracking](/docs/tracking).
## ثلاثة أشياء تسمى "التقييمات"/"قابلية الملاحظة" — ما الذي أريده؟ {#which}
من السهل الخلط بين هذه الصفحات الثلاث. اختر السؤال الذي تطرحه:
| الصفحة | السؤال الذي يجيب عليه | عند تشغيله | قلق |
| ---------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------------- | -------------- |
| **تقييمات إمكانية الملاحظة** (هذه الصفحة، علامة التبويب _Evals_) | "كيف كان أداء عمليات الإنتاج الحقيقية؟" | سلبي، بعد كل جولة (عينة القاضي LLM) | الجودة |
| **[CI Eval Gate](/docs/evals)** (`*.eval.ts`) | "هل يفعل الوكيل الشيء الصحيح بشأن هذا الإدخال الثابت؟" | بوابة CI/نشر نشطة وحتمية | الجودة |
| **[Observational Memory](/docs/observational-memory)** | "هل يظل هذا الخيط الطويل رخيصًا وداخل النافذة؟" | ضغط الخلفية على المواضيع الطويلة | التكلفة/السياق |
تسجل كل من إمكانية المراقبة وبوابة تقييم CI _الجودة_ ولكن من طرفين متعاكسين - تسجيل سلبي لاحق لحركة المرور الحقيقية مقابل عمليات فحص النجاح/الفشل النشطة على المدخلات الثابتة. ذاكرة الملاحظة لا علاقة لها بالجودة؛ يتعلق الأمر بتكلفة الرمز المميز وضغط نافذة السياق. رقِّ أثر إنتاج مكتمل إلى حالة `*.eval.ts` (لوحة **Promote to eval** أو `promote-trace-eval` أو `agent-native eval promote <runId> --write evals/from-trace.eval.ts`). انظر [من أثر إنتاج](/docs/evals#from-trace).
## ما يتم التقاطه تلقائيًا {#captured}
عندما يرسل المستخدم رسالة، يسجل الإطار تلقائيًا:
- **استخدام الرمز المميز** — الإدخال والإخراج وذاكرة التخزين المؤقت للقراءة والكتابة في ذاكرة التخزين المؤقت
- **التكلفة** — يتم حسابها من أعداد الرموز المميزة وتسعير النماذج
- **زمن الوصول** — إجمالي المدة والوقت لكل استدعاء للأداة
- **استدعاءات الأداة** — التي تم استدعاء actions، وحالة النجاح/الخطأ، والمدة
- **التقييمات التلقائية** — يتم حساب 5 نقاط جودة بعد كل جولة
لا يلزم إجراء تغييرات على التعليمات البرمجية. يتم ربط الأجهزة بـ `production-agent.ts` بشفافية.
<Diagram id="doc-block-17pwj3a" title={"كل شوط يغذي الحلقة"} summary={"ينتج عن تشغيل وكيل واحد تتبعًا ونتائج تلقائية وخطافًا للتعليقات - يتم تخزين كل ذلك في SQL الخاص بالتطبيق ويظهر على لوحة المعلومات. تقوم التجارب بتقسيم حركة المرور عبر متغيرات التكوين."}>
```html
<div class="obs-loop">
<div class="diagram-node">
تشغيل الوكيل<br /><small class="diagram-muted">production-agent.ts</small>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-panel center">
<span class="diagram-pill accent">يلتقط تلقائيا</span
><small class="diagram-muted"
>tokens · cost · latency · tool calls</small
>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-col">
<div class="diagram-box">Traces & spans</div>
<div class="diagram-box">Evals (5 scorers + LLM judge)</div>
<div class="diagram-box">Feedback & frustration index</div>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-node ok">
Dashboard<br /><small class="diagram-muted"
>scoped to the signed-in user</small
>
</div>
</div>
```
```css
.obs-loop {
display: flex;
align-items: center;
gap: 14px;
flex-wrap: wrap;
}
.obs-loop .diagram-col {
display: flex;
flex-direction: column;
gap: 8px;
}
.obs-loop .diagram-arrow {
font-size: 22px;
line-height: 1;
}
.obs-loop .center {
display: flex;
flex-direction: column;
align-items: center;
gap: 4px;
}
```
</Diagram>
## لوحة التحكم {#dashboard}
أضف لوحة التحكم إلى أي قالب بمسار واحد:
```tsx
// app/routes/observability.tsx
import { ObservabilityDashboard } from "@agent-native/toolkit/app/observability";
export default function ObservabilityPage() {
return (
<div className="min-h-screen bg-background p-6">
<ObservabilityDashboard />
</div>
);
}
```
يتم تحديد نطاق كافة البيانات للمستخدم الذي قام بتسجيل الدخول؛ لا يوجد عرض إداري عبر المستخدمين اليوم.
تحتوي لوحة التحكم على 6 علامات تبويب:
| علامة التبويب | ما يعرضه |
| -------------------- | ----------------------------------------------------------------------------------------------- |
| **نظرة عامة** | المقاييس الرئيسية - التشغيل، والتكلفة، ووقت الاستجابة، ومعدل نجاح الأداة، والرضا، ودرجة التقييم |
| **المحادثات** | تتبع القائمة مع الانتقال إلى النطاقات الفردية (agent_run، llm_call، tool_call) |
| **التقييمات** | نتائج التقييم الآلي حسب المعايير والاتجاهات مع مرور الوقت |
| **التجارب** | قائمة اختبار A/B مع شارات الحالة، ونتائج متغيرة مع فواصل الثقة |
| **التعليقات** | إبداء الإعجاب لأعلى/لأسفل، تصنيف الفئات، درجات الإحباط |
| **المراجعة البشرية** | مراجعة الطلب والإجابة، وتسجيل الملاحظات، وإعداد مسودة لتحديث التعليمات |
### تفاصيل المحادثات {#conversations}
تعرض علامة تبويب المحادثات عمليات التشغيل المسجلة. اختر عملية لعرض النطاقات، ثم وسّع أي نطاق لرؤية مدخلات الأدوات ومخرجاتها وأخطائها وبياناتها الوصفية التي تم التقاطها. استخدم **فتح المحادثة الكاملة** للانتقال إلى سلسلة الدردشة المرتبطة.
يكون التقاط وسيطات الأدوات ونتائجها وأجسام الأخطاء الكاملة متوقفًا افتراضيًا. فعّل `captureToolArgs` لحفظ الوسيطات و`captureToolResults` لحفظ النتائج وأجسام الأخطاء الكاملة في إعدادات `observability`. تُنقّح الحقول الحساسة قبل التخزين. وتحتفظ الأداة الفاشلة دائمًا بالسطر الأول المحدود الطول من خطئها، مع تنقيح بيانات الاعتماد وعناوين البريد الإلكتروني والمعرّفات الطويلة غير الشفافة، بحيث تبقى الإخفاقات قابلة للتشخيص حتى عند إيقاف `captureToolResults`.
يكون التقاط المطالبات متوقفًا افتراضيًا. عيّن `capturePrompts: true` في إعدادات `observability`، أو اضبط `AGENT_NATIVE_OBSERVABILITY_CAPTURE_PROMPTS=true`، لحفظ مدخلات ومخرجات كل نطاق `llm_call` في هذه التفاصيل. لا تُضمّن مطالبة النظام، وتُنقّح الحقول الحساسة المنظمة، ويُحدّ كل جانب من المحتوى إلى 128 كيلوبايت. لا تُحدّث النطاقات السابقة بأثر رجعي.
### المراجعة البشرية {#review}
تُظهر علامة تبويب المراجعة البشرية طلب كل عملية تشغيل وإجابتها، وتتيح تسجيل الملاحظات وإعداد مسودة لتحديث التعليمات كي يراجعها شخص. حفظ المسودة لا يغيّر التعليمات تلقائيًا.
## تعليقات المستخدم {#feedback}
### تعليقات صريحة
تظهر أزرار إبهام لأعلى/لأسفل مضمنة في كل رسالة وكيل في الدردشة UI. يؤدي الإبهام لأسفل إلى فتح نافذة منبثقة للفئة (غير دقيقة، غير مفيدة، أداة خاطئة، بطيئة جدًا). يتم توصيل هذا إلى `AssistantChat.tsx` تلقائيًا.
### تعليقات ضمنية (مؤشر الإحباط)
يحسب إطار العمل مؤشر الإحباط (0-100) من إشارات المحادثة:
| إشارة | الوزن | ما يكتشفه |
| -------------------- | ----- | -------------------------------------- |
| إعادة الصياغة | 30% | يكرر المستخدم رسائل مشابهة |
| إعادة محاولة الأنماط | 20% | "حاول مرة أخرى"، "لا، هذا خطأ" |
| الهجر | 20% | تنتهي الجلسة بعد وقت قصير من الاستجابة |
| المشاعر | 15% | أنماط اللغة السلبية |
| اتجاه الطول | 15% | تناقص طول الرسالة |
تفسير النتيجة: 0-20 = صحي، 20-40 = احتكاك، 40-60 = غير راض، 60+ = جلسة معطلة.
### التعليقات في PostHog {#posthog-feedback}
كل تعليق — الإبهام أو الفئة أو النص الحر — يُرسل حدث `$ai_feedback`. أما عرض التعليقات في تحليلات LLM لدى PostHog فيقرأ حدث `survey sent` بدلاً من ذلك، لذا اضبط `POSTHOG_AI_FEEDBACK_SURVEY_ID` على الاستطلاع الذي ينشئه PostHog من تبويب **Feedback** في أي تتبّع. هذا المعرّف وحده هو كل ما يلزم من إعداد، وبدونه لا يُرسل أي حدث استطلاع.
يجيب تصويت الإبهام عن السؤال الأول في الاستطلاع برقم الخيار في PostHog (`1` لأعلى، `2` لأسفل)، بينما يجيب النص الحر بعد الإبهام لأسفل عن سؤال المتابعة، فلا يقع النص أبدًا في موضع التقييم. ويحمل الاثنان معرّف إرسال واحدًا لكل رسالة مُقيَّمة، وهو ما يجعل PostHog يدمجهما في إجابة واحدة، ويظل الإبهام لأسفل غير مكتمل حتى تصل متابعته.
## التقييمات الآلية {#evals}
يتم تشغيل خمسة مسجلين محددين بعد كل تشغيل للعميل:
| المعايير | ما يقيسه | نطاق النتائج |
| ------------------- | --------------------------------------------------------- | ------------ |
| `tool_success_rate` | % من استدعاءات الأداة بدون أخطاء | 0-1 |
| `step_efficiency` | يعاقب تكرارات LLM المفرطة لعمليات التشغيل باستخدام الأداة | 0-1 |
| `latency_score` | تمت التسوية مقابل 10 ثوانٍ/خط الأساس للأداة | 0-1 |
| `cost_efficiency` | تمت التسوية مقابل خط الأساس للتكلفة | 0-1 |
| `error_recovery` | هل تعافى الوكيل من أخطاء الأداة؟ | 0 أو 1 |
### LLM-كقاضي (اختياري)
تمكين التقييم المستند إلى LLM لعينات من خلال إعداد `evalSampleRate`:
```ts
// server/plugins/config.ts
import { defineAppConfig } from "@agent-native/core/server";
export default defineAppConfig({
observability: {
enabled: true,
evalSampleRate: 0.05, // 5%
},
});
```
تستخدم المعايير المخصصة قواعد اللغة الطبيعية:
```ts
const criteria = {
name: "helpfulness",
description: "Was the response helpful and complete?",
rubric: "0.0 = unhelpful, 0.5 = partially helpful, 1.0 = fully resolved",
};
```
## تجارب أ/ب {#experiments}
اختبر نماذج مختلفة، أو درجات حرارة، أو تكوينات وكيل:
```ts
// Create via API
POST /_agent-native/observability/experiments
{
"name": "model-a-vs-b",
"variants": [
{ "id": "control", "weight": 50, "config": { "model": "<your-model-id>" } },
{ "id": "treatment", "weight": 50, "config": { "model": "<other-model-id>" } }
],
"metrics": ["cost", "latency", "satisfaction"]
}
// Start the experiment
PUT /_agent-native/observability/experiments/:id
{ "status": "running" }
```
استخدم معرفات الطراز الحقيقية التي يقبلها محركك بدلاً من `<your-model-id>` / `<other-model-id>` (تتغير أسماء الطرازات كثيرًا - تحقق من الموفر/المحرك الخاص بك لمعرفة المعرفات الحالية). تعمل حلقة الوكيل تلقائيًا على حل متغير المستخدم وتطبيق تجاوز التكوين. تستخدم المهمة تجزئة متسقة — يحصل المستخدم نفسه دائمًا على نفس المتغير.
<Diagram id="doc-block-1vqpr2h" title={"تعيين متغير التجزئة المتسق"} summary={"يقوم كل مستخدم بالتجزئة إلى متغير ثابت، وتطبق الحلقة تجاوز تكوين هذا المتغير، ويتم عرض النتائج لكل متغير مع فواصل الثقة."}>
```html
<div class="exp">
<div class="diagram-node">
معرف المستخدم<br /><small class="diagram-muted">تجزئة متسقة</small>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-col">
<div class="diagram-card">
<span class="diagram-pill">control · 50%</span
><small class="diagram-muted">تجاوز التكوين أ</small>
</div>
<div class="diagram-card">
<span class="diagram-pill accent">treatment · 50%</span
><small class="diagram-muted">تجاوز التكوين ب</small>
</div>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-box">
النتائج لكل متغير<br /><small class="diagram-muted"
>cost · latency · satisfaction</small
>
</div>
</div>
```
```css
.exp {
display: flex;
align-items: center;
gap: 14px;
flex-wrap: wrap;
}
.exp .diagram-col {
display: flex;
flex-direction: column;
gap: 8px;
}
.exp .diagram-card {
display: flex;
flex-direction: column;
gap: 2px;
padding: 8px 12px;
}
.exp .diagram-arrow {
font-size: 22px;
line-height: 1;
}
```
</Diagram>
## التكوين {#config}
يتم الضبط من مكوّن إضافي للخادم باستخدام `defineAppConfig()`. لكل حقل أيضًا اسم مستعار لمتغير بيئة النشر — راجع مرجع التكوين المُعلَن.
```ts
// server/plugins/config.ts
import { defineAppConfig } from "@agent-native/core/server";
export default defineAppConfig({
observability: {
enabled: true, // Master switch
capturePrompts: false, // Store prompt content in traces
captureToolArgs: false, // Store action input arguments
captureToolResults: false, // Store action results
evalSampleRate: 0, // 0-1, fraction of runs to LLM-judge
},
});
```
<Callout id="doc-block-1xvsimn" tone="info">
يتم **تنقيح المحتوى افتراضيًا**: تُخزَّن أعداد الرموز والتكاليف والتوقيت، وكذلك السطر الأول المحدود الطول من خطأ الأداة الفاشلة مع تنقيح بيانات الاعتماد وعناوين البريد الإلكتروني والمعرّفات الطويلة غير الشفافة. تبقى المطالبات ومدخلات الأدوات ونتائجها وأجسام الأخطاء الكاملة متوقفة ما لم تُفعَّل `capturePrompts` و`captureToolArgs` و`captureToolResults`. فعّلها فقط عندما تحتاج إلى محتوى المطالبات أو الوسيطات لأغراض التصحيح.
</Callout>
## نقاط نهاية API {#api}
جميعها مثبتة تلقائيًا في `/_agent-native/observability/`:
| الطريقة | المسار | الغرض |
| ------- | -------------------------- | ----------------------------------- |
| GET | `/` | نظرة عامة على الإحصائيات |
| GET | `/traces` | سرد ملخصات التتبع |
| GET | `/traces/:runId` | تتبع التفاصيل (الملخص + الامتدادات) |
| GET | `/traces/:runId/evals` | تقييمات التشغيل |
| POST | `/traces/:runId/promote` | ترقية تشغيل مكتمل إلى تقييم CI |
| POST | `/feedback` | إرسال تعليقات |
| GET | `/feedback` | إدراج التعليقات |
| GET | `/feedback/stats` | تجميع التعليقات |
| GET | `/satisfaction` | نتائج الرضا |
| GET | `/evals/stats` | إحصائيات التقييم |
| POST | `/experiments` | إنشاء تجربة |
| GET | `/experiments` | سرد التجارب |
| GET | `/experiments/:id` | الحصول على تفاصيل التجربة |
| PUT | `/experiments/:id` | تحديث التجربة |
| POST | `/experiments/:id/results` | حساب النتائج |
| GET | `/experiments/:id/results` | الحصول على النتائج |
تدعم جميع نقاط النهاية `?since=N` (الطابع الزمني مللي ثانية) ومعلمات الاستعلام `?limit=N`.
## التصدير إلى منصات خارجية {#export}
أرسل التتبعات إلى Langfuse أو Datadog أو Grafana أو أي واجهة خلفية متوافقة مع OTel عن طريق تسجيل موفّر OpenTelemetry في تطبيقك — راجع [امتدادات OpenTelemetry](#otel) أدناه.
لا يشحن النواة أي مُصدِّر ولا تحتفظ بأي نقطة نهاية تصدير أو رمز مميز، لذا فإن بيانات اعتماد الواجهة الخلفية توجد في إعداد الموفّر لديك (وفي الخزنة)، وليس في تكوين إطار العمل.
## امتدادات القياس عن بعد المفتوحة {#otel}
تصدر حلقة الوكيل **امتدادات OpenTelemetry المباشرة** لكل تشغيل واستدعاء نموذج واستدعاء أداة — بحيث يرى المضيف الذي يقوم بالفعل بتشغيل مجمع OTel نشاط الوكيل جنبًا إلى جنب مع بقية آثاره الموزعة.
هذه الطبقة **اختيارية ولا يمكن تشغيلها افتراضيًا**:
- `@opentelemetry/api` هي **تبعية اختيارية**. إذا لم يتم تثبيته، فإن المساعدين يتدهورون إلى عدم إجراء عمليات صامتة - لا يوجد شيء هنا على الإطلاق يدخل في حلقة الوكيل.
- حتى عندما تكون حزمة واجهة برمجة التطبيقات \_ موجودة، فإنها تشحن أداة تتبع افتراضية بدون تشغيل. تصبح الامتدادات حقيقية فقط بمجرد قيام **المضيف بتسجيل `TracerProvider`** (عبر `@opentelemetry/sdk-node` أو ما شابه ذلك). لا يعتمد إطار العمل عمدًا **لا** على حزم SDK/المصدرين الثقيلة أو يقوم بتسجيل الموفر نفسه - يتم الاشتراك في الأجهزة من خلال تطبيق التضمين.
لذا فإن التكلفة عند عدم توصيل OTel هي بضع قراءات للخصائص المخزنة مؤقتًا لكل مكالمة. لتشغيله، قم بتثبيت حزمة API بالإضافة إلى SDK الخاص بك وقم بتسجيل المزود عند بدء تشغيل الخادم بنفس الطريقة التي تفعلها مع أي خدمة Node أخرى.
تصدر حلقة الوكيل ثلاثة أنواع من الامتداد:
| امتداد | متى | السمات |
| --------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------- |
| `invoke_agent` | مرة واحدة لكل وكيل | `gen_ai.provider.name`, `agent.run_id`, `gen_ai.conversation.id`, `agent.user_id`, `gen_ai.request.model` |
| `execute_tool {tool}` | مرة واحدة لكل استدعاء إجراء | `gen_ai.tool.name`، بالإضافة إلى حالة النجاح/الخطأ |
| `chat {model}` | لكل مكالمة نموذجية | `gen_ai.provider.name`, التوقيت + حالة موافق/خطأ |
تم الانتهاء من الامتدادات بحالة OK/ERROR وتسجيل رسالة ثابتة مشتقة من الرمز عند الفشل. يتم تقليم قيم السمات الصفرية/الحارسة حتى لا تزدحم الامتدادات بالضوضاء. تعتبر طبقة OTel هذه إضافة بحتة إلى جداول `agent_trace_spans` / `agent_trace_summaries` الداخلية التي تعمل على تشغيل لوحة المعلومات أعلاه - وكلاهما يتم إنتاجهما من نفس أحداث التشغيل.
### المقاييس {#otel-metrics}
يسجّل Core أيضًا المقاييس بمجرد أن يسجّل المضيف موفّر مقاييس (meter provider) باستخدام `registerObservabilityProvider()` من `@agent-native/core/server`. تُسجَّل المقاييس لكل طلب وكل تشغيل، دون أخذ عينات:
| الأداة | السمات |
| ------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `http.server.request.duration` | `http.request.method`, `http.response.status_code`, `http.route`, `error.type` |
| `agent_native.http.server.handoff.duration` | `http.request.method`, `http.response.status_code`, `http.route`, `error.type` |
| `gen_ai.client.operation.duration` | `gen_ai.operation.name`, `gen_ai.provider.name`, `gen_ai.request.model`, `error.type` |
| `gen_ai.client.token.usage` | `gen_ai.operation.name`, `gen_ai.provider.name`, `gen_ai.request.model`, `gen_ai.token.type` |
| `agent_native.agent.runs` | `status`, `terminal_reason`, `gen_ai.provider.name`, `gen_ai.request.model` |
| `agent_native.tool.calls` | `gen_ai.tool.name`, `error.type` |
| `agent_native.telemetry.flush_failures` | `error.type`, `agent_native.telemetry.signal` |
يحمل `agent_native.http.server.handoff.duration` السمات والفئات نفسها التي يحملها `http.server.request.duration`، لكنه ينتهي عندما يعيد خطاف الاستجابة الاستجابة إلى بيئة التشغيل بدلًا من بداية الخطاف. عندما تبتعد مئيناته عن مئينات `http.server.request.duration`، فهذا يعني أن استجابات مكتملة تُحتجز، مثلًا بسبب تفريغ القياس عن بُعد داخل الطلب. الفارق مؤشر وليس مدة انتظار طلب بعينه، لأن المئينين قد يأتيان من طلبات مختلفة. من دون `waitUntil`، تسجّل النواة العيّنة بعد ذلك التفريغ، فتصل إلى الواجهة الخلفية مع التفريغ التالي.
في المقاييس، تكون `gen_ai.tool.name` اسم إجراء من إجراءات إطار العمل أو `other`، وتكون `gen_ai.request.model` معرّف النموذج فقط عندما يدرجه المحرك ضمن النماذج المدعومة، وإلا فهي `_OTHER`. لذلك لا يمكن للأدوات التي يعرّفها التطبيق ولا لمعرّفات النماذج التي يمرّرها المستدعي إنشاء سلاسل غير محدودة؛ وتحتفظ الامتدادات (spans) بالقيم الدقيقة.
قيمة `error.type` لاستدعاء نموذج فاشل في `gen_ai.client.operation.duration` هي حالة HTTP التي أعادها المزوّد عندما يُعيد الاستدعاء 4xx أو 5xx (`http_429`، `http_529`)، وإلا فهي `rate_limit` أو `context_overflow` أو `provider_error` أو `no_model_connected` عندما يسمّي رمز خطأ المحرك إحداها، وإلا فهي `_OTHER`. كل إعادة محاولة هي استدعاء مستقل له `error.type` الخاص به، لذلك فإن التشغيل الذي يعيد محاولة طلب مقيّد عدة مرات يسجّل عدة استدعاءات `http_429` حتى لو انتهى بنجاح.
تُضبط `http.route` على كل طلب وتأتي من مجموعة مغلقة: قالب مسار نقطة نهاية في إطار العمل (`/_agent-native/auth/session`، `/_agent-native/agent-chat/runs/:runId/events`)، أو القالب الذي يعلنه الإجراء، أو مسار ملف Nitro الخاص بالتطبيق (`/api/clips/:id`)، أو فئة. الفئات هي `/_agent-native/*` و`/mcp/*` و`/.well-known/*` للمسار غير المدرج ضمن هذه النطاقات، و`/api/*` لأي مسار API آخر، و`static` لطلبات الملفات، و`page` لأي طلب `GET` أو `HEAD` آخر، و`other`. لا يُسجَّل مسار الطلب الخام أبدًا. ويحمل الامتداد `http.server` القيمة نفسها.
## ربط واجهة خلفية لـ OpenTelemetry {#otel-provider}
لا يتضمن Core أي SDK أو مُصدِّر (exporter) لـ OpenTelemetry. يبني التطبيق موفّري SDK الخاصين به ويسلّمهم إلى Core باستخدام `registerObservabilityProvider()` من `@agent-native/core/server`. بعد ذلك يُصدر Core [الامتدادات](#otel) و[المقاييس](#otel-metrics) المذكورة أعلاه عبرهم، ويرسلها مُصدِّر التطبيق إلى أي واجهة خلفية تدعم OTLP.
### `registerObservabilityProvider()` {#register-observability-provider}
تأخذ `registerObservabilityProvider()` كائنًا واحدًا يحتوي على حقلين اختياريين:
- **tracerProvider**: كائن يحتوي على `getTracer(name, version?)`. يأخذ Core المتتبِّع منه. وبدونه تستخدم الامتدادات المتتبِّع العام من `@opentelemetry/api`.
- **meterProvider**: كائن يحتوي على `getMeter(name, version?)`. لا تُسجَّل المقاييس إلا عند تسجيل موفّر مقاييس. ليس لها بديل عام، لذا بدونه لا يفعل أي مقياس شيئًا.
يمكن لأي من الموفّرين أيضًا تنفيذ `forceFlush()`، التي يستدعيها Core بعد كل استجابة (راجع [التفريغ في البيئات بدون خادم](#otel-flush)). يطابق `BasicTracerProvider` و`MeterProvider` من الـ SDK هذه الأشكال بالفعل.
```ts
function registerObservabilityProvider(
provider: ObservabilityProvider,
): () => void;
interface ObservabilityProvider {
tracerProvider?: ObservabilityTracerProvider;
meterProvider?: ObservabilityMeterProvider;
}
interface ObservabilityTracerProvider {
getTracer(name: string, version?: string): unknown;
forceFlush?(): Promise<void>;
}
interface ObservabilityMeterProvider {
getMeter(name: string, version?: string): unknown;
forceFlush?(): Promise<void>;
}
```
يستبدل الاستدعاء اللاحق الموفّر السابق. تُلغي الدالة المُعادة تسجيل الموفّر إذا كان لا يزال هو المسجَّل. تحتاج الامتدادات أيضًا إلى تثبيت `@opentelemetry/api` في التطبيق. وبدونه يوقف Core التتبّع ويسجّل تحذيرًا واحدًا.
### التفريغ في البيئات بدون خادم {#otel-flush}
تتجمّد الدوال بدون خادم (serverless) بين الاستدعاءات، لذا قد لا يعمل مؤقّت التصدير في الـ SDK أبدًا. عندما ينفّذ موفّر مسجَّل `forceFlush()`، يستدعيها Core من خطّاف الاستجابة بعد كل طلب وينتظر اكتمالها. يتسابق كل تفريغ مع مهلة مشتركة واحدة مدتها ثانيتان، لذا لا يؤخّر القياس عن بعد أي استجابة أكثر من ذلك. عندما توفّر المنصة `waitUntil` (Cloudflare، أو سياق استدعاء Netlify)، يسلّم Core التفريغ إليها ويرسل الاستجابة أولًا بدلًا من الانتظار.
تستدعي النواة `forceFlush()` لموفّر المقاييس مرة واحدة على الأكثر كل 10 ثوانٍ لكل عملية، وتتخطاه في الطلبات الواقعة بينها. كل تصدير للمقاييس يعيد إرسال كل السلاسل التي تحملها العملية، لذا يمنع ذلك حجم الرفع من النمو مع معدّل الطلبات. لا تضيع النقاط المتخطّاة: يحملها التصدير التالي، ما لم تتوقف النسخة عن خدمة أي طلب آخر. أما موفّر التتبّع فيُفرَّغ مع كل طلب.
عندما يفشل التفريغ أو تنتهي مهلته، يتوقف Core عن انتظاره ويضيف 1 إلى `agent_native.telemetry.flush_failures`، الذي يصدّره التفريغ التالي. يستمر التصدير الذي انتهت مهلته في العمل وقد يصل رغم ذلك، ما لم يجمّد وقت التشغيل العملية أولًا. تكون قيمة `error.type` للفشل هي `timeout`، أو `suspended` عندما يجمّد وقت التشغيل العملية في منتصف التفريغ، أو اسم الخطأ. ولأن المُجمِّع الذي تستمر مهلته في الانتهاء لا يستلم هذا العدّاد أبدًا، يكتب Core أيضًا سطرًا واحدًا `agent-native.telemetry_flush_failed` في سجل الدالة لكل إشارة ونوع خطأ في كل عملية.
على خادم طويل التشغيل، يعني التفريغ بعد كل استجابة عملية تصدير لكل طلب. سجّل الموفّرين هناك بدون `forceFlush()` واترك مؤقّتات الـ SDK نفسها تتولى التصدير. تميّز `isServerlessRuntime()` من `@agent-native/core/server` بين الحالتين. وتكون قيمتها true على Netlify وVercel وAWS Lambda وCloudflare.
### مثال: OTLP عبر HTTP {#otel-example}
تربط إضافة الخادم هذه حزمة OpenTelemetry JS SDK بـ Core. ثبّت حزم الـ SDK أولًا:
```bash
pnpm add @opentelemetry/api @opentelemetry/context-async-hooks @opentelemetry/exporter-metrics-otlp-proto @opentelemetry/exporter-trace-otlp-proto @opentelemetry/resources @opentelemetry/sdk-metrics @opentelemetry/sdk-trace-base
```
```ts filename="server/plugins/otel.ts"
import { randomUUID } from "node:crypto";
import {
defineNitroPlugin,
isServerlessRuntime,
registerObservabilityProvider,
} from "@agent-native/core/server";
import { context } from "@opentelemetry/api";
import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks";
import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-proto";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
import {
defaultResource,
detectResources,
envDetector,
resourceFromAttributes,
} from "@opentelemetry/resources";
import {
MeterProvider,
PeriodicExportingMetricReader,
} from "@opentelemetry/sdk-metrics";
import {
BasicTracerProvider,
BatchSpanProcessor,
} from "@opentelemetry/sdk-trace-base";
export default defineNitroPlugin(() => {
if (!process.env.OTEL_EXPORTER_OTLP_ENDPOINT) return;
// Metric counters are cumulative and restart with each process, so each
// process needs its own series.
const resource = defaultResource()
.merge(resourceFromAttributes({ "service.instance.id": randomUUID() }))
.merge(detectResources({ detectors: [envDetector] }));
const meterProvider = new MeterProvider({
resource,
readers: [
new PeriodicExportingMetricReader({
exporter: new OTLPMetricExporter(),
exportIntervalMillis: 60_000,
}),
],
});
context.setGlobalContextManager(
new AsyncLocalStorageContextManager().enable(),
);
const tracerProvider = new BasicTracerProvider({
resource,
spanProcessors: [new BatchSpanProcessor(new OTLPTraceExporter())],
});
if (isServerlessRuntime()) {
registerObservabilityProvider({ meterProvider, tracerProvider });
return;
}
// Without forceFlush(), core leaves exporting to the SDK's own timers.
registerObservabilityProvider({
meterProvider: {
getMeter: (name, version) => meterProvider.getMeter(name, version),
},
tracerProvider: {
getTracer: (name, version) => tracerProvider.getTracer(name, version),
},
});
});
```
لا تفعل الإضافة شيئًا حتى يتم تعيين `OTEL_EXPORTER_OTLP_ENDPOINT`. ويقرأ الـ SDK بقية إعداداته من متغيرات البيئة القياسية لـ OpenTelemetry:
| المتغير | التأثير |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | عنوان URL الأساسي لمستقبِل OTLP. تضيف المُصدِّرات `/v1/traces` و`/v1/metrics`. |
| `OTEL_EXPORTER_OTLP_HEADERS` | ترويسات تُرسل مع كل عملية تصدير، مثل `Authorization=Bearer%20<token>` |
| `OTEL_SERVICE_NAME` | `service.name` على كل امتداد ومقياس |
| `OTEL_RESOURCE_ATTRIBUTES` | سمات موارد إضافية، مثل `deployment.environment.name=production` |
| `OTEL_TRACES_SAMPLER` / `OTEL_TRACES_SAMPLER_ARG` | أخذ عينات التتبّع، مثل `parentbased_traceidratio` و`0.1`. لا تُؤخذ عينات من المقاييس أبدًا. |
ترسل مُصدِّرات `-proto` بروتوكول OTLP عبر HTTP بصيغة protobuf، لذا وجّه نقطة النهاية إلى منفذ HTTP الخاص بالمستقبِل (4318 افتراضيًا)، وليس إلى منفذ gRPC. لا تحمل الامتدادات أي نص للمطالبات أو الردود. تنطبق إعدادات `capture*` في [التكوين](#config) على تتبّعات SQL وعلى PostHog، وليس على OTLP.
يحتوي المجلد [`packages/otel`](https://github.com/BuilderIO/agent-native/tree/main/packages/otel) في المستودع على نسخة أكمل من هذه الإضافة، مع نقاط نهاية لكل إشارة والتحقق من المُصدِّر. وهي غير منشورة على npm، لذا ابدأ من الإضافة أعلاه بدلًا من تثبيتها.
## الإبلاغ عن الأخطاء (Sentry) {#sentry}
يتم الإبلاغ عن الأخطاء من جانب الخادم التي تهرب من معالجات التوجيه Nitro إلى Sentry عند تكوين DSN. بدونها، لا توجد عمليات لـ SDK بصمت، لذلك من الآمن ترك env vars بدون ضبط في dev. يمكن أن تنتقل أحداث المتصفح والخادم إلى نفس مشروع Sentry؛ قم بتقسيمها إلى مشاريع منفصلة فقط عندما تريد الفصل التشغيلي للملكية أو الحجم أو الحصص أو توجيه التنبيه.
| السطح | SDK | إنف فار | ملاحظات |
| ------------------ | ----------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| المتصفح / SPA | `@sentry/browser` | `VITE_SENTRY_CLIENT_DSN`، أو `SENTRY_CLIENT_DSN`، أو `SENTRY_DSN` | يلتقط الأخطاء التي لم تتم معالجتها ومسارات التنقل لتغيير المسار في العميل. |
| خادم Nitro | `@sentry/node` | `SENTRY_SERVER_DSN` أو `SENTRY_DSN` | يلتقط استجابات 5xx وأخطاء دورة حياة Nitro. مستخدم لكل طلب. |
| `agent-native` CLI | `@sentry/node` | _hardcoded_ | تقارير الأعطال من الإصدار الثنائي CLI المنشور؛ غير قابل للتكوين بواسطة المستخدم. |
### التكوين من جانب الخادم {#sentry-config}
قم بتعيين `SENTRY_SERVER_DSN` أو `SENTRY_DSN` المشترك في بيئة النشر (لوحة تحكم Netlify، أسرار Cloudflare، وما إلى ذلك). يقوم إطار العمل تلقائيًا بتثبيت المكون الإضافي Nitro الذي:
1. استدعاء `Sentry.init` مرة واحدة عند بدء التشغيل (غير فعال - آمن للاتصال من مكونات إضافية متعددة).
2. حل مشكلة المستخدم عبر `getSession(event)` في كل طلب API/إطار العمل وإرفاق `id` / `email` / `username` بالإضافة إلى علامة `orgId` بنطاق عزل Sentry لكل طلب. يتم تخطي مسارات الأصول الثابتة لتجنب زيارات قاعدة البيانات الإضافية.
3. يلتقط كل مسار إطار عمل 5xx مع علامات `route` و`method` و`userAgent` القابلة للبحث.
المقابض الاختيارية:
- `SENTRY_SERVER_TRACES_SAMPLE_RATE` (عائم `0`–`1`) — الاشتراك في تتبع الأداء. الإعدادات الافتراضية هي `0` (الأخطاء فقط). يتم تثبيت القيم غير الصالحة على `0`.
- `AGENT_NATIVE_RELEASE` — يتجاوز علامة `release`. الإعدادات الافتراضية هي `agent-native-server@<core-version>`.
### القوالب
يرث كل قالب هذا تلقائيًا - ولا يوجد شيء لاستيراده. بالنسبة لتطبيقات SSR، يقوم الخادم بإدخال برنامج نصي صغير لتكوين المتصفح عندما يكون `SENTRY_CLIENT_DSN` أو `VITE_SENTRY_CLIENT_DSN` أو `SENTRY_DSN` المشترك متاحًا في وقت التشغيل، لذلك لا يقتصر التقاط المتصفح على بيئة وقت البناء Vite. يمكن للنماذج التي تريد سلوكًا مخصصًا (علامات إضافية، DSN مختلفة لكل قالب، Sentry الذي يمكن تعطيله بشدة) أن تتجاوزها عن طريق تصدير المكون الإضافي الخاص بها من `server/plugins/sentry.ts`:
```ts
// server/plugins/sentry.ts
import { createSentryPlugin } from "@agent-native/core/server";
export default createSentryPlugin();
```
إن DSN المضمن في CLI مقصود - فالاحتياجات الثنائية المنشورة لتعطل هاتف المنزل بغض النظر عن البيئة التي تديره. لا تقوم وحدة الخادم أبدًا بترميز DSN بشكل ثابت لأنها تعمل داخل بيئات العملاء حيث يقرر المشغلون ما إذا كان يجب أن تصل الأخطاء إلى Sentry على الإطلاق.
### الخصوصية وPII {#privacy}
يتم تهيئة كل من الخادم وCLI باستخدام `sendDefaultPii: false` وخطاف `beforeSend` الذي يزيل:
- `request.headers.authorization`, `cookie`, `set-cookie`, `proxy-authorization`
- `request.cookies`
- `user.ip_address` (يتم جمعها تلقائيًا بدون موافقة)
- `contexts.runtime_env` (لقطة بيئة العملية)
- أي حدث يكون نوع استثناء المستوى الأعلى له هو `ValidationError` (يتم التعامل معه على أنه رفض متوقع لإدخال المستخدم، وليس خطأ).
يتم الاحتفاظ بحقول الهوية التي تم تعيينها بشكل صريح عبر `setUser({ id, email, username })`.
## ما هي الخطوة التالية
- [**Tracking**](/docs/tracking) — تحليلات المنتج (PostHog، Mixpanel، Amplitude) لأحداث تطبيقك الخاصة
- [**Actions**](/docs/actions-overview) — العمليات التي تظهر كاستدعاءات أداة في التتبع
- [**Security**](/docs/security) — تحديد نطاق البيانات ومعالجة بيانات الاعتماد
رسائل فشل التشغيل غير موجودة في Analytics وMonitoring، حتى عند تفعيل التقاط المحتوى. يتضمن `$ai_error` رمز النهاية وسببًا مسمى وقابلية إعادة المحاولة ورسالة ثابتة مشتقة من الرمز. لا تتضمن أحداث التتبع `error_message` أو `agent_run_terminal.error_detail` أو نص نتائج الأدوات الفاشلة؛ يحتفظ حدث النهاية بـ`error_code` و`error_cause`. تبقى `agent_runs.error_detail` و`agent_trace_spans.error_message` في قاعدة بيانات التطبيق لتشخيص المشكلات ضمن صلاحيات المالك.
تحتفظ استثناءات التشغيل وبوابة Builder بالنوع والرمز وإطارات المكدس، مع رسالة ثابتة `Internal Server Error` ودون نص الرسالة الأصلية أو الأسباب المتداخلة. يجمع Monitoring المشكلات حسب التطبيق والنوع والإطار ورمز الخطأ وفئة الفشل بدلًا من الأسماء داخل الرسالة. يبقى `$ai_trace_id` للربط بالتتبع. يحذف تصدير OpenTelemetry الاختياري الذي يديره المضيف أيضًا نص فشل التشغيل ويحتفظ بـ`agent.error_code` و`agent.error_cause`. لا يتغير التقاط الاستثناءات الأخرى.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |