AgentExecutor.execute() وFlowExecutor.execute() ينتجان spans عبر TraceExporter. أسماء الـ spans والـ attributes تتبع GenAI semantic conventions في OpenTelemetry، فالـ observability backends التي تفهم GenAI تتعرف عليها بدون mapping خاص.
الاستقرار. اصطلاحات GenAI ما زالت بحالةDevelopment(أي غير مستقرة). أسماء الـ attributes تغيّرت بين إصدارات المواصفة من قبل — مثلًاgen_ai.systemأصبحتgen_ai.provider.name— وقد تتغير مرة أخرى. الـ SDK تتبع المواصفة كما هي بتاريخ 2026-10-01 من مستودع semantic-conventions-genai (مكانها الحالي). إذا كانت الـ dashboards لديك تعتمد على هذه الأسماء، ثبّت إصدار الـ SDK.
البداية السريعة
مرّرexporter إلى createAgent(). بعد ذلك يُسجَّل trace لكل run للـ agent: send() وstream() وturns الـ session (الجلسة) وresume() والـ runs التي يكملها agent.approvals.resolve() — حتى الـ sub-agents. إذا أردت حفظ الـ traces على القرص وتصفحها بـ npx lousho traces، فاستخدم fileTraceExporter() (راجع Local traces). بادئة vendor/ في اسم الـ model تختار الـ provider؛ مع OpenRouter استخدم openrouter/<vendor>/<model> (مثلًا openrouter/openai/gpt-4o-mini).
onSpanStart وonSpanEnd يُعتبر exporter. الـ run لا ينتظرهما: الـ hook الذي يرمي خطأ، أو الـ hook الـ async الذي يُرفض الـ promise الخاص به، يُبلَّغ عنه مرة واحدة لكل exporter عبر console.warn ويُتجاهَل غير ذلك.
متقدم: الـ executor API
مع الـ executor، مرّر الـ exporter إلىAgentExecutor.execute():
createOtelTraceExporter() من lousho/otel. تحتاج الـ peer dependency الاختيارية @opentelemetry/api وTracerProvider مسجّلًا. تنقل نوع الـ span وحالة الخطأ إلى OpenTelemetry. راجع examples/tracing (npm run example:tracing:console، وnpm run example:tracing:otel الذي يطبع metrics أيضًا).
شجرة الـ spans
handoff وapproval.wait هي spans علامات (marker spans): startTime === endTime، فيستطيع المستهلك أن يعلّم الـ agent الهدف في الـ handoff على أنه العقدة النشطة في الـ run (lousho.handoff.from / lousho.handoff.to)، ويعلّم عقدة الـ tool لـ call متوقف على أنها في حالة انتظار (lousho.approval.id / lousho.approval.kind / lousho.approval.expires_at)، دون أن يُبقي span مفتوحًا طوال فترة الانتظار.
كل استدعاء لـ send() / stream() هو trace مستقل بذاته إلا إذا حدّدت له parent. إذا أردت جمع عدة runs في trace واحد، فمرّر id لـ span من عندك في parentSpanId؛ يصبح الـ span invoke_agent للـ run ابنًا (child) له، وتكلفته تتجمّع فيه:
agent.approvals.resolve() هو trace مستقل بذاته: الـ span invoke_agent فيه يحتوي span الـ execute_tool الخاص بالـ call الموافَق عليه أولًا (لأن الـ call يعمل قبل استدعاء الـ model مرة أخرى)، ثم spans الـ chat لبقية الـ run. الـ call المرفوض ليس له span execute_tool.
run لـ flow (FlowExecutor.execute) ينتج:
parentSpanId (withSpan تسلّم الـ span للـ callback الخاص بها). بعد ذلك يصبح span الـ flow ابنًا (child) له.
السمات
ثوابت كل الأسماء موجودة فيsrc/execution/semconv.ts (متصدَّرة بالأسماء GenAiAttr، GenAiOperation، GenAiMetric، ErrorAttr، FlowAttr، SdkAttr، LegacyAttr).
Agent run: invoke_agent {agent name}
Summing token usage over spans
المجاميع على spans الـinvoke_agent تحسب tokens موجودة أصلا على spans الـ chat في الـ run، ومجموع run الـ agent الرئيسي يحسب أيضًا runs الـ sub-agents التابعة له. لذلك الـ backend الذي يجمع gen_ai.usage.* على كل spans الـ trace (بعض dashboards تكلفة الـ LLM في OpenTelemetry تفعل هذا) يحسب كل token مرتين على الأقل، ومرة إضافية لكل مستوى تداخل sub-agents: agent رئيسي معه sub-agent واحد، وcalls الـ model فيهما استهلكت 33 + 7 input tokens، يُظهر 40 على spans الـ chat، و7 على span الـ invoke_agent الخاص بالـ sub-agent، و40 على span الـ agent الرئيسي، أي 87 بالمجموع.
للحصول على المجموع الحقيقي، اجمع spans الـ chat فقط (gen_ai.operation.name = chat)، أو اقرأ span الـ invoke_agent الأعلى وحده، أو استخدم الـ metric gen_ai.client.token.usage. إذا كان الـ backend لا يستطيع الفلترة، فمرّر createOtelTraceExporter({ agentUsageTotals: false }): عندها تبقى سمات الاستهلاك تبقى على spans الـ chat فقط (وlousho.cost_usd تبقى على كل span).
Model call: chat {model} (CLIENT)
Tool call: execute_tool {tool}
فحص حاجز الحماية: guardrail {name}
span واحد لكل فحص guardrail (حاجز حماية)، تحت span الـ invoke_agent للـ run (فحوص المدخلات والمخرجات) أو تحت span الـ execute_tool للـ call المفحوص (فحوص tools). الـ span يحمل الـ ids والنتيجة فقط، ولا يحمل أبدا النص المفحوص أو سبب التفعيل، لأنهما قد يحتويان بيانات المستخدم (والتفعيل يُبلَّغ عنه أصلا عبر الحدث guardrail.tripped).
Flows
مواصفة GenAI لا تعرّف أي convention لعقد الـ flows، فـ spans الـ nodes تستخدم الـ namespacelousho.flow.*. أما span الـ run فيستخدم convention الـ workflow الوارد في المواصفة.
الأخطاء
الـ span الفاشل يحصل علىerror.type وعلى حالة خطأ للـ span (ERROR في OpenTelemetry، والرسالة = رسالة الخطأ). قيمة error.type هي name الخطأ المرمي (_OTHER إذا لم يكن المرمي Error). والـ tool call الذي يُرجع خطأ للـ model (isError) يُوسَم بـ error.type = tool_error.
Metrics
createOtelTraceExporter() يسجّل أيضا metrics عميل GenAI في OpenTelemetry عبر الـ metrics API في @opentelemetry/api، باستخدام الـ MeterProvider العام (metrics.getMeter(...)) أو الخيار meter:
كلاهما يستخدم حدود الـ buckets التي توصي بها المواصفة. ويتبعان صفحة
gen-ai-metrics في semantic-conventions v1.40 (بدرجة استقرار Development): أحدث الاصطلاحات تقسّم الـ histogram الخاص بالـ tokens إلى counters لكل نوع، وهذه الـ SDK لم تصدّرها بعد. spans الـ agents والـ flows لا تدخل في metric المدة — فقط calls الـ model والـ tools داخلها.
MeterProvider مسجّل، الـ no-op meter في OpenTelemetry يرمي القياسات. الـ metrics API موجودة في @opentelemetry/api، فالـ SDK لن تسجّل شيئا (ولن تحمّل شيئا) إذا لم تكن تلك الـ peer dependency الاختيارية مثبتة. والتكلفة تقدير من جدول الأسعار (راجع registerModel)، ليست فاتورة.
محتوى الرسائل والـ arguments هو opt-in
الـ prompts ومخرجات الـ model وarguments ونتائج الـ tools حساسة وكبيرة الحجم. لذلك سمات المحتوىgen_ai.* لا تُسجَّل افتراضيا أبدا. فعّلها لكل agent على حدة بـ createAgent({ exporter, captureContent: true }).
الاستثناء هو الـ collector المحلي: عندما يشير LOUSHO_OBSERVE إلى loopback (1/true، أو URL الـ host فيه 127.0.0.1 أو localhost أو ::1؛ ومنفذ localhost يحوّله SSH tunnel إلى daemon بعيد يُعتبر loopback أيضا، فاضبط captureContent: false إذا كان هذا الـ daemon يجب ألا يستلم المحتوى)، createAgent يجعل القيمة الافتراضية لـ captureContent هي true، فعرض الـ trace في الـ daemon يُظهر الـ prompt ومخرجات الـ model وarguments ونتائج الـ tools التي تشرح سبب الفشل. الـ daemon وحده يستلم هذا المحتوى، ويبقى في قاعدة بيانات الـ daemon على جهازك: الـ exporter الخاص بالـ agent نفسه (ملفات fileTraceExporter()، أو exporter لـ OTLP أو لـ vendor، أو تصدير OTel في الـ server المبني) يظل يرى كل span بدونه، إلا إذا ضبط الـ agent captureContent: true أو كان متغير محتوى OTel المذكور تحت true. عطّله بـ captureContent: false؛ والـ collector الذي يتجاوز loopback يحتفظ بالقيمة الافتراضية (opt-in). هذه القيمة الافتراضية تنطبق على الـ agents المبنية بـ createAgent.
الأسرار في المحتوى المسجَّل
المحتوى المسجَّل يمر علىredactContent قبل أن يُسجَّل. إذا كانت غير محددة أو true (الافتراضي)، يعمل منظّف مدمج على نص الرسائل وتعليمات النظام وarguments الـ tool calls ونتائج الـ tools، ويستبدل أشكال مفاتيح الـ API بـ [redacted]:
التنظيف نفسه (أو الدالة الخاصة بك) يعمل على نص الخطأ المسجَّل على الـ span، أي
error ورسالة حالة الخطأ، فالـ token الموجود في رسالة خطأ مرمي يُحجب أيضا؛ وerror.type (اسم الـ class) يبقى كما هو. redactContent: false يسجّل نص الخطأ كما هو.
كل شكل يحتاج token طويلا بعد البادئة (16 حرفا أو أكثر لـ sk- وlsv2_ وgh*_ وgithub_pat_ وStripe وBearer؛ و10 أو أكثر لـ Slack؛ و35 لـ Google؛ وأجزاء JWT من 8 أو أكثر)، فكلمات مثل sk-learn أو task- تبقى كما هي. Bearer لا يميّز حالة الأحرف، فكلمة طويلة بعد “bearer” في نص عادي قد تُحجب أيضًا. المنظّف يلتقط صيغ المفاتيح الشائعة، لا كل سر: كلمة مرور مكتوبة في prompt تظل تُسجَّل، فاضبط captureContent: false إذا كان المحتوى يجب ألا يصل أبدًا إلى قاعدة البيانات المحلية.
مرّر دالة إذا أردت استخدام الحجب الخاص بك بدلًا من المنظّف. تستلم كل قطعة نص عادي (قبل ترميز JSON) وتُرجع ما يُسجَّل؛ وإذا رمت خطأ، يُسجَّل ذلك النص على هيئة [redacted] والـ run يكمل:
redactContent: false يسجّل المحتوى كما هو (ويسجّل أيضا الـ attributes الـ deprecated input/prompt/args/result، انظر أدناه).
متقدم: الـ executor API
مع الـ executor، فعّلها لكل run على حدة:captureContent). إذا لم تحدّد captureContent، متغير البيئة OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true (وهو الاسم الذي تستخدمه المواصفة مثالا) يفعّله. والقيمة الصريحة captureContent: false تغلب دائما.
عند التفعيل، يسجّل الـ SDK المحتوى على هيئة JSON strings (وهو الـ fallback الذي تحدده المواصفة للـ spans) حسب message schema المواصفة:
Deprecated attribute names
قبل اصطلاحات GenAI، كانت الـ spans تستخدم أسماء ارتجالية وأسماء spans مثلagent.run وllm.generate وtool.call. أسماء الـ attributes القديمة ما زالت تُصدَر بجانب الجديدة لكي تظل الـ dashboards القائمة تعمل، لكنها deprecated وستُزال في major version قادم. أما أسماء الـ spans فتغيّرت (إلى ما تفرضه المواصفة)، فحدّث الـ queries التي كانت تطابقها.
مع
createOtelTraceExporter({ legacyAttributes: false }) تحمل spans الـ OpenTelemetry أسماء GenAI فقط، دون الأسماء الـ deprecated بجانبها (attributes أقل في كل span)؛ والقيمة الافتراضية true تحتفظ بكليهما.
سمات المحتوى الـ deprecated (input، prompt، args، result) معطّلة افتراضيًا: قيمة redactContent الافتراضية true (والدالة تُحسب true هنا). مرّر redactContent: false إذا أردت تسجيلها كما في السابق؛ وcaptureContent يتحكم فقط بسمات المحتوى gen_ai.*.
Local traces
fileTraceExporter() من lousho/traces تكتب كل run في ملف، وlousho traces يعرض الملفات في الـ terminal. لا backend لـ OpenTelemetry ولا حزمة إضافية.
--dir D يقرأ مجلدًا آخر (الافتراضي .lousho/traces)، --limit N يعرض N من الـ runs (الافتراضي 20)، --json يطبع الملخصات أو الـ spans بصيغة JSON. بادئة id تطابق أكثر من run تعرضها كلها ويخرج الأمر بالرمز 1. تتعطّل الألوان إذا كان NO_COLOR مضبوطًا أو إذا لم يكن الـ output terminal. أعداد الـ tokens والتكلفة هي مجاميع spans الـ chat في الـ run، بما فيها الخاصة بالـ sub-agents (حتى التي تعمل في الخلفية)؛ والتكلفة تبقى فارغة (-) إذا كان سعر أحد الـ models مجهولًا.
الملفات. ملف واحد لكل run في <dir>/<YYYY-MM-DD>/<traceId>.jsonl (تاريخ بداية الـ run بالتوقيت المحلي؛ الـ trace id هو id الـ span invoke_agent الخاص به)، فيمكنك حذف الـ traces القديمة يومًا بيوم. كل سطر هو span واحد منتهي، يُكتب فور انتهائه:
startTime وendTime بالـ milliseconds منذ الـ epoch؛ attributes هي سمات الـ span المذكورة أعلاه، كاملة دون اختصار. الـ span الذي لم ينتهِ أبدا (العملية ماتت) لا يوجد في الملف. إذا تعذّرت الكتابة في المجلد، الـ exporter يحذّر مرة واحدة والـ run يكمل. listTraces({ dir, limit }) وreadTrace(idOrPrefix, { dir }) تقرأ الملفات من الكود.
الملفات تحمل ما تحمله الـ spans. افتراضيا هذا يعني لا محتوى رسائل ولا tools: الـ attributes الـ deprecated input وprompt وargs وresult تُسجَّل فقط مع redactContent: false (راجع Deprecated attribute names)، وcaptureContent: true يضيف محتوى gen_ai.*. أبقِ .lousho/ خارج الـ version control؛ المشاريع التي ينشئها lousho init تتجاهله.
lousho dev وlousho chat يكتبان هذه الملفات عندما تمرّر --traces (إلى .lousho/traces) أو --traces=<dir>، سواء لملف spec أو مجلد agent أو module. أي أن الـ agent المبني من ملف spec يمكنك تتبّعه دون أي كود. وهي opt-in عن قصد: الملفات تحفظ توقيتات الـ spans وأعداد الـ tokens والتكاليف، ومحتوى الـ prompt والـ tools فقط إذا ضبط الـ agent redactContent: false أو captureContent: true، فلا يُكتب شيء على القرص إلا إذا طلبت. تنسيق ملف الـ spec ليس فيه إعداد للـ traces.
الـ observe daemon
lousho observe start يشغّل collector محليًا على http://127.0.0.1:7777 (loopback فقط، دون حاجة إلى مصادقة). عندما يكون LOUSHO_OBSERVE مضبوطًا، كل agent مبني على هذه الـ SDK يبلّغه بالـ spans تلقائيا: 1 أو true أو on أو yes يرسل إلى الـ URL الافتراضي، وURL بـ http:///https:// يرسل إليه، و0 أو false أو off أو no أو none أو disabled أو القيمة الفارغة (بأي حالة أحرف) توقف الإبلاغ. أي قيمة أخرى تُعامَل كخطأ إملائي: يُطبع تحذير واحد يذكر LOUSHO_OBSERVE لكل عملية والإبلاغ يبقى متوقفا. LOUSHO_OBSERVE_PROJECT يعطي الصفوف label؛ وLOUSHO_OBSERVE_TOKEN يرسل bearer token للـ daemons المربوطة على عنوان يتجاوز loopback (--require-token مع lousho observe token create).
الأمان. لأن الـ daemon على loopback لا يطلب token، فهو يرفض الطلبات التي تستطيع صفحة ويب في متصفحك تزويرها. على كل route تحت /api/*:
- الـ daemon المربوط على loopback يجيب فقط أسماء
Hostالخاصة بـ loopback (localhost،*.localhost،127.x.y.z،[::1])، وأيHostآخر يحصل على 403، وهذا يُفشل هجمات DNS rebinding؛ - الكتابة (أي شيء غير
GET/HEAD/OPTIONS) التيOriginفيها ليس origin بـhttp(s)على loopback (بما فيهاOrigin: null)، أو التي تحملSec-Fetch-Site: cross-site، تحصل على 403؛ - الكتابة التي لها body يجب أن ترسل
Content-Type: application/json، وأي شيء آخر (text/plain، إرسال النماذج) يحصل على 415.
Origin وترسل JSON دائمًا، فلا تتأثر؛ أما الـ client المخصص الذي يكتب إلى الـ daemon فيجب أن يرسل application/json أيضًا. وفي daemon يطلب token، يأتي فحص الـ 401 أولًا.
ملف SQLite واحد (الافتراضي ~/.lousho/observe.db، بوضع WAL) يحفظ observations الأسطول (fleet) وجلساته (sessions) ودرجات التقييم (eval scores) وإصدارات الـ prompts والسياق المشترك. npx lousho studio يعرضه (راجع Agent Forge): Traces وTrace (أشجار traces مع waterfall للـ latency)، وThreads، وMonitoring (مراقبة حية للأسطول بحالة مشتقة من الـ heartbeat — الجلسات المفتوحة لـ agent متعطّل تتحول إلى interrupted — فوق رسوم بيانية لكل agent للـ runs وlatency الـ p95 ونسبة الأخطاء والتكلفة والـ tokens)، وScores، وDatasets، وEvaluators، وAnnotation queues، وPrompts، وContext Hub. شريط التنقل في Studio يبيّن هل يستطيع الوصول إلى الـ daemon. التنبيهات على انتقالات down أو على حدود نسبة الأخطاء ترسل POST إلى URLs الـ --webhook أو إلى alerts.json بجانب قاعدة البيانات.
Insights يحسب متوسط الـ runs في اليوم على الأيام التي كان فيها الـ agent نشطا ضمن النافذة (من الأحدث بين بداية النافذة وأول ظهور للـ agent)، فـ agent ظهر أول مرة اليوم ومعه 12 run يُظهر 12/يوم، وليس 12/7. السلسلة لكل bucket (series في GET /api/v1/insights، buckets بالساعة أو اليوم لكل agent) تحمل runs وerrors وcost_usd وinput_tokens وoutput_tokens وlatency_ms، بالإضافة إلى p95_latency_ms (على الـ runs المنتهية في الـ bucket؛ لا صف إذا لم ينتهِ أي run) وerror_rate (الأخطاء / الـ runs). هاتان تُخزَّنان لكل bucket، ولا تُجمعان. قاعدة البيانات التي كتبها daemon أقدم تفتقدهما للـ buckets السابقة: شغّل lousho observe rebuild-rollups مرة واحدة لتعبئتها.
الـ daemon يقدّم أيضًا مخزنين تستطيع الـ agents استخدامهما وقت التشغيل:
- سجل الـ prompts (Prompt registry).
createAgent({ prompt: 'name@version' })(أو'name@label') أوLOUSHO_PROMPTيجلب التعليمات منه وقت البناء (@latestوالـ labels تُحلّ على الـ daemon؛ والـ daemon الذي لا يمكن الوصول إليه يرجع إلىinstructions؛ وبدونinstructionsيفشل الـ run بـLOUSHO_PROMPT_UNRESOLVED). الجلب الفاشل لا يُخزَّن مؤقتا للأبد: الـ runs في الـ 30 ثانية التالية تُحلّ فورا (باستخدامinstructions، أو بالفشل)، ثم الـ run التالي يعيد المحاولة، فالـ daemon الذي كان متوقفا لفترة قصيرة وقت البناء يتعافى بدون إعادة تشغيل. ذلك الـ run وحده ينتظر جلب إعادة المحاولة، حتى 2.5 ثانية. كل run يسجّل الإصدار الذي استخدمه بالضبط.lousho prompt pushينشر إصدارا جديدا؛ والـ push الذي نصه ومتغيراته تساوي الإصدار الأحدث لا ينشئ شيئا (200 { unchanged: true, version }). الـ label (prod،staging) يشير إلى إصدار واحد بالضبط:lousho prompt label mira prod 3(أوPUT /api/v1/prompts/:name/labels/:labelمع{ version }) ينقله، وpush --labelsينقله إلى الإصدار المنشور، وGET /api/v1/prompts/:name/:refيقبل رقما صحيحا أوlatestأو label. الـ ref الذي هو label يسلك مسار الإصدار نفسه: إذا تعذّر حلّه فالنتيجة هي الرجوع إلىinstructionsأوLOUSHO_PROMPT_UNRESOLVED، مع نفس نافذة إعادة المحاولة ذات الـ 30 ثانية. - Context hub.
hub()/hubTools()تسمح للـ agents بنشر قيم key-value ضمن namespaces والاستعلام عنها، بنطاقprivate(الـ agent الكاتب فقط) أوfleet(كل agent على الـ daemon).
POST /playground/run، راجع Agent Forge) تُبلَّغ على أنها الـ agent playground؛ والـ run الذي بدأ من prompt في السجل يحمل ref الـ prompt (name@label، name@3) في الـ attribute lousho.prompt.ref على الـ root span.
الإبلاغ يتم بأسلوب fire-and-forget ولا يوقف الـ run أبدًا: عندما يكون الـ daemon متوقفًا، تعود الدفعة الفاشلة إلى الطابور ويُعاد إرسالها مع exponential backoff (1 ث، 2 ث، 4 ث … بحد أقصى 30 ث)، فإعادة تشغيل الـ daemon في منتصف run لا تضيّع شيئا. الـ backlog يُفرَّغ في دفعات واحدة بعد الثانية مباشرة، كل دفعة بحد أقصى 1000 حدث و4 MB من JSON (تحت حدود الـ daemon لكل طلب: 1000 حدث و5 MB). فقط هذه تُسقَط وتُحسب في dropped الخاص بالـ reporter: الأحداث المطرودة بعد تجاوز حد الـ buffer (maxBuffered، الافتراضي 5000 حدث، أو 32 MB من الأحداث المسلسلة، أيهما يأتي أولًا؛ الأقدم أولًا)؛ والأحداث التي تتجاوز أحدث 16 MB عندما يحدث flush عند انهيار؛ والأحداث التي ما زالت غير مرسلة بعد آخر محاولة في flush الخروج؛ والحدث الواحد الأكبر من أي طلب (فوق 5 MB مسلسلا، مثلا مع تفعيل تسجيل المحتوى)؛ والدفعة التي يرفضها الـ daemon نهائيا (400/413)، والتي لا يُعاد إرسالها أبدا. بداية الـ root لـ run مفتوح (في الطابور، ونهايته لم تأتِ بعد) تُحفظ في الحالتين: تقليم الـ buffer وشريحة الـ 16 MB في flush الانهيار يطردان الأحداث الأخرى أولا، فالـ run الذي تتجاوز أبناؤه الـ buffer يظل يظهر. فقط عندما لا يبقى شيء آخر للطرد تُطرد بدايات الـ runs المفتوحة أيضا، الأقدم أولا، لكي تبقى الذاكرة محدودة. العدد يُرسل مع كل heartbeat في meta.dropped (تراكمي للعملية)، وكل صف في قائمة الأسطول /api/v1/agents في الـ daemon يعرض آخر قيمة منه في dropped: رقم، أو null لـ agent على SDK أقدم لم يرسل شيئا.
العملية التي تموت بسبب exception غير ملتقط أو rejection غير معالَج تظل تبلّغ عن آخر run لها: الـ reporter يراقب uncaughtExceptionMonitor ويرسل ما يحمله (أحدث 16 MB منه، بدايات الـ root للـ runs المفتوحة أولا)، الأقدم أولا، ويؤخّر الانهيار حتى 1 ث لكل reporter. مخرجات الخطأ في Node ورمز الخروج يبقيان كما هما، والسكربت الذي ينجو من الـ throw (عبر معالج uncaughtException خاص به، أو callback التقاط مثل الذي في الـ REPL) يستمر في الإبلاغ. أما process.exit() الصريح أو SIGKILL فيظلان يضيّعان ما في الـ buffer.
كل run يظهر من لحظة بدايته: الـ reporter يرسل الـ root span للـ run (الـ invoke_agent الأعلى، الذي بلا parent) بمجرد أن يُفتح، دون انتظار الفاصل الزمني ذي الـ 5 ث، وStudio يعرض ذلك الـ trace على أنه running. نهاية الـ run تستبدل ذلك الصف بالحالة النهائية والاستهلاك والتكلفة والمخرجات، وتُحسب مرة واحدة. فالعملية التي تُقتل في منتصف run (SIGKILL، انقطاع الكهرباء) تظل تترك الـ trace الخاص بها، ويتحول الـ trace إلى interrupted عندما يتوقف الـ agent عن إرسال heartbeat ويعلّمه الـ sweep بـ down. كل عملية reporter ترسل أيضًا instance_id عشوائيًا، لأن إعادة التشغيل أو عملية أخرى للـ agent نفسه تُبلغ تحت id الـ agent نفسه. عمليات الـ agent الواحد التي تعمل جنبًا إلى جنب لا تقاطع runs بعضها أبدًا ما دامت ترسل heartbeat، حتى لو تشاركت الـ hostname والـ pid نفسيهما (نسخ --network host كلها pid 1). عندما تسكت عملية من عمليات agent بينما تستمر عملية أخرى منه في إرسال heartbeat (supervisor أعاد تشغيلها بـ pid جديد، أو مات واحد من عدة workers)، يعلّم الـ sweep الـ runs المفتوحة للعملية الساكتة بـ interrupted بعد أن تفوّت حوالي heartbeatين (علامة stale)، والحكم يكون على الفاصل الزمني للـ heartbeat الخاص بتلك العملية وعلى ساعة الـ daemon. إعادة التشغيل على الـ host نفسه بالـ pid نفسه (pid 1 في container) تعلّمها أبكر: عند أول heartbeat للعملية الجديدة (بعد أول heartbeat لها) يصل بعد أكثر من فاصل heartbeat واحد زائد 10 ثوان من آخر heartbeat للعملية القديمة، إذا كانت العملية القديمة ساكتة من لحظة ظهور الجديدة. وعندما لا تبقى أي عملية للـ agent، يصبح الـ agent down وتُعلَّم الـ runs المفتوحة له كما سبق. العملية التي تخرج بشكل سليم في منتصف run (SIGINT، SIGTERM) تعلّم الـ runs المفتوحة لها بـ interrupted فورا. الـ agent الذي عطّل الـ heartbeats (heartbeatIntervalMs: 0) لا يمر عليه الـ sweep أبدا، فالـ runs المقتولة له تبقى running. أما الـ child spans (calls الـ model وcalls الـ tools) فما زالت تُرسل فقط عندما تنتهي، فالـ run المقتول يحتفظ بالـ root وبأي child انتهى وأُرسل.
درجات التقييم تمر عبر نفس الأنبوب — lousho eval --observe يرسلها حتى لو كان LOUSHO_OBSERVE غير مضبوط. كل case ينتج صف <eval>/<check> واحدا لكل assertion، بالإضافة إلى صف <eval> واحد للنجاح/الفشل (1 إذا نجحت كل فحوص الـ gate، وإلا 0).
ملاحظات البشر هي درجة أيضا. POST /api/v1/scores مع { "trace_id", "obs_id"?, "name", "value", "comment"? } (value رقم أو null، وname حتى 200 حرف، وcomment حتى 10 000) يضيف درجة واحدة بـ source: "human" ويجيب بـ 201 { "score_id" }. كل استدعاء يضيف صفا، والدرجة تُنسب إلى الـ agent الخاص بالـ trace. الـ trace_id غير المعروف (أو obs_id غير موجود في ذلك الـ trace) يعطي 404، والـ name الفارغ يعطي 400. يقبل الـ token نفسه الذي يقبله الـ ingest، وGET /api/v1/scores?trace_id=... يعرضه.
مجموعات البيانات (Datasets)
الـ dataset هي مجموعة أمثلة لها اسم، تشغّل عليها التقييمات. كل مثال فيهinput وقيمة expected اختيارية، وكلاهما أي قيمة JSON. شاشة Datasets في Studio تعرضها وتنشئها، وAdd to dataset في الـ trace ينسخ الـ trace إليها. الـ routes تقبل نفس الـ token الذي يقبله الـ ingest:
صف الـ dataset هو
{ dataset_id, name, description, created_at, example_count } وصف المثال هو { example_id, dataset_id, input, expected, source_trace_id, created_at }، وexpected وsource_trace_id قيمتهما null إذا لم تُحدَّدا. from_trace_id ينسخ الـ root observation للـ trace: مدخلاته تصبح input ومخرجاته expected. النص المخزَّن الذي هو JSON صالح يُنسخ كتلك القيمة، وأي نص آخر يُنسخ كـ JSON string. الـ trace الذي الـ root فيه بلا input مسجَّل (تسجيل المحتوى كان معطّلا) يعطي 400. الـ dataset أو الـ trace أو المثال غير المعروف يعطي 404 بالرمز LOUSHO_REQUEST_INVALID. يمكن أن يصل body المثال إلى 1 MiB.
الـ retention لا يحذف أبدًا الـ datasets أو الأمثلة. يحتفظ المثال بـ source_trace_id الخاص به بعد حذف ذلك الـ trace.
قواعد التقييم الحي (Online evaluator rules)
قاعدة الـ evaluator تحدد أي traces جديدة تُقيَّم وكيف. قاعدةcode تحمل مصدر دالة (trace) => number | { value, comment }، وقاعدة judge تحمل model ومعيار تقييم (rubric) للحكم. الـ daemon يشغّل قواعد code على الـ traces الجديدة (راجع Online evaluators)؛ وقواعد judge تعمل عبر Agent Forge (راجع Judge rules). شاشة Evaluators في Studio تديرها. الـ routes تقبل نفس الـ token الذي يقبله الـ ingest:
صف القاعدة هو
{ rule_id, name, enabled, filter, sample_rate, kind, config, created_at, updated_at }. الحقول هي:
name: من 1 إلى 200 حرف بعد إزالة المسافات من الطرفين، وفريد.enabled: قيمة منطقية،trueافتراضيا.filter:{ "agent_id"?, "status"?, "name_contains"? }، و{}افتراضيا.statusهوokأوerror، وكل قيمة string غير فارغ.sample_rate: رقم من 0 إلى 1، و1افتراضيا.kindوconfig:codeيأخذ{ "source" }(حتى 64 KiB من النص)، وjudgeيأخذ{ "model", "rubric" }(حتى 200 و20 000 حرف).
kind غير معروف، أو config لا يطابق الـ kind يعطي 400 بالرمز LOUSHO_REQUEST_INVALID. القاعدة غير المعروفة تعطي 404 بالرمز نفسه. updated_at يتغير مع كل PUT. يمكن أن يصل الـ body إلى 128 KiB. الـ retention لا يحذف القواعد أبدا.
التقييم الحي (Online evaluators)
عندما تنتهي الـ root observation للـ trace، يشغّل الـ daemon كل قاعدةcode مفعّلة يطابق filter فيها الـ root (agent_id، وstatus، وname_contains على اسمه). تعمل القاعدة عندما يكون Math.random() < sample_rate، فـ 0 لا تعمل أبدًا و1 تعمل دائمًا. كل تشغيل يكتب درجة واحدة بـ source: "online"، وname = اسم القاعدة، وagent_id الخاص بالـ root، ودون obs_id. الـ trace الذي لديه أصلًا درجة online بالاسم نفسه لا يُقيَّم مرة أخرى.
الـ source الخاص بالقاعدة يعمل كـ (<source>)(trace) في بيئة الـ isolate المعزولة (sandbox({ driver: 'isolate', timeoutMs: 2000 })). الـ trace هو object JSON عادي:
observations يحمل صفوف الـ trace، الأقدم أولا، بحد أقصى 200. الصف الذي JSON الـ attrs فيه أطول من 8192 حرفا يحمل "attrs": { "truncated": true } بدلا منه. error_message هو attrs.error لأول صف خطأ، حتى لو كان ذلك الصف بعد أول 200. القواعد تطابق على صف الـ root وحده، فالـ trace الذي لا يحتفظ به filter أي قاعدة لا يحمّل أي صفوف أخرى، والـ worker يعالج trace واحدا في كل دورة من الـ event loop. الدالة ترجع رقما محدودا (قيمة value للدرجة) أو { "value": <number | null>, "comment"?: "<text>" } (الـ comment يُقص عند 1000 حرف). أي شيء آخر يعطي درجة value: null بالـ comment invalid_result. التشغيل الذي يفشل يعطي درجة value: null ونوع خطأ الـ sandbox كـ comment: timeout أو oom أو driver. الخطأ الذي يرميه كودك لا يحمل نوعا، فيُبلَّغ عنه كـ driver.
الـ isolate driver يحتاج الحزمة الاختيارية isolated-vm (npm install isolated-vm). على Node 20 وما بعده، الـ daemon يحتاج أيضا NODE_OPTIONS=--no-node-snapshot. بدونهما، تُتخطّى قواعد الـ code ويحذّر الـ daemon مرة واحدة.
تعمل القواعد خارج طلب الـ ingest، trace واحد في كل مرة، فيبقى الـ ingest سريعًا حتى عندما يكون evaluator بطيئًا أو يفشل. حتى 1000 trace تنتظر في الذاكرة؛ وبعد ذلك، تُسقَط الـ traces الجديدة (وتُحسب). الـ traces المنتظرة تضيع عندما يُعاد تشغيل الـ daemon، فتلك الـ traces لا تحصل أبدا على درجات online.
POST /api/v1/evaluators/:id/test { "trace_id": "<trace-id>" } يجرّب القاعدة تجربة جافة (dry run) على trace واحد ويجيب بـ 200 { "result": { "value", "comment" } }. يتجاهل enabled وfilter وsample_rate، ولا يكتب أي درجة. القاعدة غير المعروفة تعطي 404، وكذلك الـ trace غير الموجود أو الذي بلا root observation. الـ body الخاطئ يعطي 400. التجارب الجافة تجري واحدة تلو الأخرى: الطلب الثاني ينتظر حتى تنتهي التجربة الجارية. قاعدة judge تعطي 409 (judge evaluators run through Agent Forge). وبدون الـ isolate يجيب بـ { "result": { "value": null, "comment": "isolate_unavailable" } }.
قواعد الحَكَم (عبر Agent Forge)
الـ daemon لا يحمل مفاتيح أي provider، فلا يستطيع تشغيل قاعدةjudge بنفسه. عندما تطابق قاعدة judge trace جديدًا (بفحوص filter وsample_rate و”مُقيَّم من قبل” نفسها التي في قواعد الـ code)، يضع الـ daemon job في الطابور لتلك القاعدة وذلك الـ trace. Agent Forge (lousho studio) يسحب الـ jobs، ويشغّل كل judge بمفاتيح الـ provider الموجودة لديه أصلًا (المفتاح المحفوظ في إعدادات Studio يتقدّم على متغير البيئة الخاص بالـ provider، كما في الـ playground)، ثم يعيد إرسال النتيجة. يكتبها الـ daemon كدرجة source: "online" نفسها. فالـ judges تعمل فقط ما دام Studio يعمل. وحتى ذلك الحين تنتظر الـ jobs.
- بحد أقصى 500 job تنتظر في الوقت نفسه (المعلّقة زائد المحجوزة). بعد ذلك، الـ jobs الجديدة تُسقَط وتُحسب. الـ jobs تعيش في الذاكرة، فإعادة تشغيل الـ daemon تضيّعها.
- الـ judge هو call واحد للـ model المحدد في
modelالخاص بالقاعدة (provider/model، أوmock). الـ system prompt هو تعليمة تقييم ثابتة زائد الـrubricالخاص بالقاعدة. رسالة المستخدم تحمل اسم الـ trace وحالته ومدخلاته ومخرجاته وخطأه، كل واحد مقصوص عند حوالي 8 KB. يجب أن يرد الـ model بـ object JSON{ "score": <0..1>, "comment": "<short reason>" }. Agent Forge يقرأ أول object JSON في الرد. الرد الذي بلا درجة صالحة يعطي درجةvalue: nullبالـ commentinvalid_judge_output. وخطأ الـ provider (مفتاح ناقص مثلا) يعطي درجةvalue: nullبالـ commentjudge_error: <message>. - call الـ judge لا ينشئ trace خاصا به، فلا يشغّل الـ evaluators أبدا.
LOUSHO_OBSERVE_TOKEN إذا كان مضبوطا):
Agent Forge يحجز حتى 5 jobs كل ثانيتين، بمدة حجز 60 ثانية، ويشغّلها واحدة تلو الأخرى. كل call للـ judge يُقطع بعد 20 ثانية، أو أبكر إذا كان المتبقي من مدة الحجز أقل (الـ call المقطوع يعطي درجة
value: null بالـ comment judge_error: timed out after <n> ms). الـ job المحجوزة التي انتهت مدة حجزها قبل دورها لا تعمل: تنتهي صلاحيتها وتُحجز مرة أخرى لاحقًا. الـ daemon المتوقف يوقف الحلقة مؤقتًا فقط، ويسجّل مرة واحدة لكل انقطاع. التجربة الجافة أدناه لها الحد نفسه ذو الـ 20 ثانية.
لتجربة قاعدة judge تجربة جافة، استخدم Agent Forge: POST /observe/api/v1/evaluators/:id/test { "trace_id" } على server الـ Studio يشغّل الـ judge على ذلك الـ trace ويجيب بـ 200 { "result": { "value", "comment" } } دون كتابة درجة. ولقاعدة code يمرّر الطلب إلى الـ daemon دون تغيير. أما /test الخاص بالـ daemon نفسه فما زال يجيب بـ 409 لقاعدة judge.
طوابير المراجعة (Annotation queues)
طابور المراجعة هو قائمة traces لها اسم، يراجعها شخص واحدًا تلو الآخر. إكمال عنصر يكتب درجاته كدرجات بشرية، وهي صفوفsource: "human" نفسها التي يكتبها POST /api/v1/scores، فتظهر في GET /api/v1/scores وعلى الـ trace. شاشة Annotation queues في Studio تنشئ الطوابير وهي واجهة المراجعة. الـ routes تقبل الـ token نفسه الذي يقبله الـ ingest:
صف الطابور هو
{ queue_id, name, rubric, created_at, counts: { pending, done, skipped } }. صف العنصر هو { item_id, queue_id, trace_id, status, reviewer, created_at, done_at }، وreviewer وdone_at قيمتهما null حتى ينتهي العنصر. :id هو الـ queue_id.
name: من 1 إلى 200 حرف بعد إزالة المسافات من الطرفين، وفريد.rubric: حتى 50 مدخلا من{ "name", "description"?, "min"?, "max"? }، و[]افتراضيا. الأسماء من 1 إلى 200 حرف وفريدة، والوصف حتى 2000 حرف، وminلا يجوز أن يتجاوزmax.
scores، حتى 50 مدخلا من { "name", "value", "comment"? } حيث value رقم أو null، وreviewer اختياري (حتى 200 حرف)، وstatus، وهو done (الافتراضي) أو skipped. كل درجة تُكتب على الـ trace الخاص بالعنصر، والحالة وreviewer وdone_at تُضبط في الـ transaction نفسها. عندما يكون للطابور rubric، يجب أن يكون كل اسم درجة واحدًا من أسمائه وأن تكون القيمة ضمن min وmax للمدخل المطابق، وإلا فالجواب 400. التخطي مع درجات يعطي 400. إكمال عنصر منتهٍ أو متخطّى أصلا يعطي 409 ولا يكتب شيئا. العنصر غير الموجود في الطابور يعطي 404.
next لا يحجز العنصر الذي يُرجعه ولا يقفله. السؤال مرتين يُرجع العنصر نفسه حتى يكمله أحد. الطابور مصمَّم لمراجع واحد يعمل محليًا، فقد يقيّم مراجعان على الطابور نفسه الـ trace نفسه.
الـ retention لا يلمس الطوابير أو العناصر أبدًا. إذا حُذف trace عنصر ما، يحتفظ العنصر بـ trace_id الخاص به ويظل next يُرجعه. إكماله بدرجات يعطي حينها 404 يذكر الـ trace، والعنصر يبقى معلّقا، فتخطّاه بدلا من ذلك. الـ bodies الخاطئة والحقول غير المعروفة تعطي 400 بالرمز LOUSHO_REQUEST_INVALID، والطابور غير المعروف يعطي 404 بالرمز نفسه. يمكن أن تصل الـ bodies إلى 256 KiB.
الاحتفاظ بالبيانات (Retention)
الـ daemon يحتفظ افتراضيا بـ 30 يوما من الـ runs. في أول sweep بعد التشغيل، ثم مرة كل يوم، يحذف كل trace انتهت كل observations فيه وانتهت آخرها قبل أكثر من--retention-days (الافتراضي 30؛ و--retention-days 0 يحتفظ بكل شيء). الـ trace يُحذف كله أو يبقى كله: observation واحدة ما زالت مفتوحة (end غير مضبوط، run جارٍ) تحفظ الـ trace بأكمله، مهما كان قديما. مع الـ trace تُحذف درجاته وروابط استخدام الـ prompts الخاصة به؛ والدرجات الأقدم من النافذة التي لم يبقَ للـ trace الخاص بها أي observations تُحذف أيضا. الجلسة تُحذف فقط إذا لم تكن active، وانتهت (أو، إذا بلا نهاية، بدأت) قبل النافذة، ولا تشير إليها أي observation متبقية، فالمحادثة القديمة التي ما زالت نشطة لا تُحذف أبدا. الجلسات الخاملة تنتهي من تلقاء نفسها (راجع Idle sessions)، فالمحادثات المنتهية تتقادم فعلا.
الحذف لا يلمس أبدا الـ rollups الخاصة بـ Insights (الرسوم البيانية للأيام المحذوفة تبقى)، ولا سجل الـ prompts، ولا مدخلات الـ hub، ولا سجل الـ agents، ولا الـ tokens. الحذف اليومي لا يشغّل VACUUM، لأنه يوقف الـ ingest؛ لاسترجاع مساحة القرص، شغّل lousho observe prune --older-than 30d. يحذف فورا بالنافذة التي تعطيها (أيام كاملة فقط)، ويطبع كم observation ودرجة وجلسة حذف، ثم يشغّل VACUUM. وهو آمن حتى أثناء عمل الـ daemon على قاعدة البيانات نفسها.
التصدير
lousho observe export [--since 7d] [--agent X] [--out file] يفرّغ الـ traces بصيغة JSONL للتحليل دون اتصال أو لأداة أخرى. كل سطر هو trace واحد: { "trace": <trace row>, "observations": [...], "scores": [...] }، بأشكال الـ APIs نفسها الخاصة بقائمة الـ traces وتفاصيلها، الأقدم أولا وبلا حد أقصى. --since يأخذ <N>d أو <N>h أو <N>m رجوعا من الآن؛ و--agent يطابق agent_id، أو اسم agent إذا كان يشير إلى agent واحد بالضبط. الأسطر تذهب إلى stdout (والعدد إلى stderr) إلا إذا حدد --out ملفا، فيُكتب فوقه. يقرأ قاعدة البيانات مباشرة ويعمل دون daemon قيد التشغيل. المحتوى المسجَّل يُصدَّر كما هو مخزَّن، فتعامل مع الملف مثل قاعدة البيانات.
الـ API لقائمة الـ traces
GET /api/v1/traces يُرجع { traces, total, limit, offset }، صف واحد لكل trace، الأحدث أولا. معاملات الاستعلام (كلها اختيارية):
قيمة
sort أو order غير معروفة، أو min_duration_ms غير رقمي، أو prompt باسم فارغ أو بإصدار غير صحيح، يُجاب عنه بـ 400 بالرمز LOUSHO_REQUEST_INVALID.
كل صف فيه trace_id وname وagent_id وsession_id وstart وend وstatus، والأعداد observations وgenerations وtools وerrors، والمجاميع input_tokens وoutput_tokens وcost_usd، بالإضافة إلى:
agent_name: اسم الـ agent من الـ heartbeat الخاص به، أوnull.model: الـ model الخاص بأول call لـ model، أوnull.error_message: الـ attributeerrorلأول observation فاشلة (مثلاupstream 529 overloaded)، أوnull.input_preview/output_preview: أول 200 حرف من مدخلات الـ run ومخرجاته المخزَّنة، أوnullإذا لم يُسجَّل شيء.
الـ API للجلسات (threads)
GET /api/v1/sessions يُرجع { sessions, total, limit, offset }، الأحدث أولا (started_at تنازليا). معاملات الاستعلام (كلها اختيارية): agent_id، وstatus (مطابقة تامة)، وfrom / to (بداية الجلسة بالـ ms منذ الـ epoch، نصف مفتوحة from <= started_at < to)، وlimit / offset (1-500، الافتراضي 50). صف الجلسة هو { session_id, agent_id, agent_name, status, started_at, ended_at, traces, input_tokens, output_tokens, cost_usd, last_input_preview }: traces يعدّ ids الـ traces المختلفة، والـ tokens والتكلفة مجاميع observations الجلسة، وlast_input_preview هو أول 200 حرف من مدخلات الـ root لآخر trace فيها. status هو active أو ended (خاملة، انظر أدناه) أو interrupted (توقف الـ agent الخاص بها).
GET /api/v1/sessions/:id يُرجع { session, traces } مع الـ traces (صفوف قائمة الـ traces نفسها) مرتبة حسب البداية تصاعديا، بحد أقصى 500؛ والـ id غير المعروف يعطي 404 بالرمز LOUSHO_REQUEST_INVALID. شاشة Threads في Studio تقرأ هذين الـ routeين.
الجلسات الخاملة
الـ SDK لا ترسل أي حدث “session closed”: صف الجلسة موجود لأن الـ runs الخاصة بها تحمل الـ id الخاص بها، فالـ daemon هو الذي يقرر متى تنتهي المحادثة. كل sweep (كل 30 ث) يعلّم الجلسة بـended عندما لا يكون أي run فيها ما زال مفتوحًا (الـ run الجاري يبقيها active مهما طال) ولم يبدأ أو ينتهِ فيها شيء لمدة --session-idle-minutes (الافتراضي 30؛ و0 يعطّل هذا). الـ run المعلَّم بـ interrupted (ماتت عمليته بينما استمر الـ agent في العمل) لم يعد يُحسب جاريًا؛ بل يُحسب نشاطا في لحظة مقاطعته. ended_at للجلسة هو وقت آخر نشاط، وليس وقت الـ sweep. الجلسة التي لا يشير إليها أي run ترجع إلى آخر وقت حدّثها فيه الـ daemon. الجلسات في قاعدة بيانات كتبها daemon أقدم تُغلق في أول sweep يجدها خاملة.
run جديد في جلسة ended يُعيدها active (وended_at يتبع الـ runs الخاصة بها من جديد)، وكذلك النشاط الجديد في جلسة interrupted. الحدث المعاد إرساله أو المعاد ترتيبه لنشاط في ended_at الخاص بالجلسة أو قبله لا يعيد فتحها. مرحلة الخمول لا تلمس أبدا الجلسات interrupted. بعد أن تنتهي، تُحذف الجلسة عبر الـ retention مثل أي جلسة منتهية أخرى، فـ Threads يعرض فقط المحادثات الحية على أنها active. نافذة الخمول يُحكم عليها حسب الطوابع الزمنية التي تُبلغ عنها الـ agents الخاصة بك، فالـ agent الذي تتأخر ساعته كثيرًا عن ساعة الـ daemon قد ينهي جلسة مبكرًا؛ والـ run التالي له يعيد فتحها.
الـ server المبني
الـ server الذي ينشئهlousho build --target=node-server أو --target=docker يصدّر الـ traces دون أي كود عندما يكون المتغير القياسي OTEL_EXPORTER_OTLP_ENDPOINT (أو OTEL_EXPORTER_OTLP_TRACES_ENDPOINT) مضبوطًا في المكان الذي يعمل فيه. يسجّل tracer provider لـ OpenTelemetry يرسل الـ spans عبر OTLP/HTTP، ويعطي الـ agent createOtelTraceExporter()، فكل turn لـ /chat يصل كشجرة invoke_agent / chat / execute_tool المذكورة أعلاه. والـ exporter الموجود أصلًا في إعدادات الـ agent (الخاصة بمجلد agent أو module) يستمر في العمل: كلاهما يستلم كل span.
الـ SDK الخاصة بـ OpenTelemetry ليست مضمَّنة. ثبّت هذه الحزم بجانب dist/server.js، أو أضفها إلى dependencies في package.json الخاص بالبناء قبل أن تبني صورة الـ docker:
- الـ server يستوردها عند بدء التشغيل فقط إذا كان المتغير مضبوطا. عندما تنقص واحدة منها، يسجّل الحزم التي يجب تثبيتها ويخدم دون تصدير الـ traces.
service.nameهوOTEL_SERVICE_NAMEإذا كان مضبوطا، وإلا اسم الـ agent.OTEL_RESOURCE_ATTRIBUTESوOTEL_EXPORTER_OTLP_HEADERS(لمفتاح API) وإعدادات الـ batch (OTEL_BSP_SCHEDULE_DELAY، …) تعمل كما يوثّقها الـ OTel SDK.- عند SIGINT أو SIGTERM، يرسل الـ server الـ spans التي ما زالت لديه قبل أن يخرج.
- إذا لم يكن أي من المتغيرين مضبوطًا، لا يُستورد شيء ويعمل الـ server كما كان.