mirror of
https://github.com/crewAIInc/crewAI.git
synced 2026-09-22 02:46:39 +00:00
4e0b2e2b15
* fix(telemetry): record task failures as failures, not as successes close_span() sets StatusCode.OK unconditionally, and TaskFailedEvent was routed to Telemetry.task_ended, which calls it. Every failed task was therefore exported as OK, which is why error_count downstream is not merely low but exactly zero: 240.0M task executions across 13 months in crew_task_executions_daily_target, error_count = 0 in every one of them. The same line had a second defect. The span was only ended when source.agent.crew was present, so a task failing without one was popped from the span map and then never closed - never ended, never exported, invisible rather than mislabelled. task_failed takes no crew (it reads nothing off one), so that condition disappears rather than being widened. Only the exception class name is recorded, never the message, which routinely contains prompts, model output, file paths and credentials. close_span_with_error drops any value failing str.isidentifier(), so a message cannot be recorded even if one is passed by mistake. This is the task half of closed PR #6781, re-cut onto main as that PR asked for. The crew half is deliberately left out: crew_execution_span() returns None unless share_crew=True, so crew._execution_span is None for nearly every user and a crew-failure handler would exit immediately for the default population. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RfV2uMqWRcdfufMvtdCVoN * fix(telemetry): take the exception class for error_type, not a free-form string cursor and CodeRabbit both flagged the sanitization, and they were right: the package already had a stronger convention and this change had not used it. Telemetry._safe_error_type takes the exception *class*, and its docstring says why in as many words - "a single-word message such as 'secret_token' is itself a valid identifier", so filtering a string with isidentifier() is not enough. The ported code predates that helper and reinvented the weaker check. TaskFailedEvent.error_type is now type[BaseException] | None, so pydantic itself rejects a message before any of our code runs, and task_failed routes it through _safe_error_type. The identifier check in close_span_with_error stays as the second gate on the derived name, which is the role _safe_error_type's docstring already describes. Also adds producer-level tests, which CodeRabbit correctly identified as missing: every earlier test constructed TaskFailedEvent directly, so a regression in the two emit sites this change touches in task.py would have passed the whole suite. The sync and async producers are driven through Task._execute_core and Task._aexecute_core with a distinctive exception class, and each patches a different agent method (execute_task vs aexecute_task), which is why they can regress independently. Verified by dropping error_type from both producers: all three new tests fail, and pass again when restored. Removes an unused `import os` left behind when the fixture was rewritten. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RfV2uMqWRcdfufMvtdCVoN * test(telemetry): capture producer failures at the emit boundary, not via the bus The producer tests subscribed a handler to crewai_event_bus and asserted on what it received. That passed this file in isolation and every randomized local run, then failed in CI inside a 621-test shard with zero events captured: FAILED tests/telemetry/test_task_failure_instrumentation.py:: test_sync_producer_puts_the_exception_class_on_the_event assert 0 == 1 + where 0 = len([]) task_failed is an "ending" event, and with an empty scope stack - there is no real kickoff in these tests - dispatch is conditional on event-context state that other tests in the same worker process can leave behind. Subscribing made the assertion depend on the bus choosing to dispatch, which is not what these tests are about: they are about what the producer in task.py constructs. Patching crewai_event_bus.emit records the event unconditionally at the point the producer hands it over, with no dispatch involved. Both producers ignore emit's return value, so returning None is faithful. Containment re-verified after the change: dropping error_type from both producers fails exactly these three tests and nothing else. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RfV2uMqWRcdfufMvtdCVoN * fix(events): keep TaskFailedEvent JSON-serializable with a class-valued error_type error_type holds an exception class, which is not a JSON type, so model_dump(mode="json") raised PydanticSerializationError for the whole event - not just that field. Two real consumers depend on it: the checkpoint listener dumps every event through EventRecord, and the tracing listener JSON-POSTs events to AMP. A single task failure therefore took out checkpointing. field_serializer with when_used="json" returns the class name. The "json" scope is load-bearing: event_listener hands the live class to Telemetry.task_failed, which needs it for _safe_error_type, so python-mode dumps must keep the class. The annotation is a module-level _ExceptionClass alias rather than an inline type[BaseException], because TaskFailedEvent declares a field named `type` which shadows the builtin for the rest of the class body - inline, it raises TypeError at import ("task_failed"[BaseException]) and mypy rejects it as "Variable ... is not valid as a type". Quoting satisfies neither tool: ruff flags UP037 and mypy still resolves it in the class scope. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RfV2uMqWRcdfufMvtdCVoN * fix(events): let a dumped error_type restore, instead of degrading the event The serializer added in the previous commit stopped model_dump(mode="json") from raising, but nothing accepted the class-name string back. _resolve_event (state/event_record.py:32-35) wraps cls.model_validate in a bare except and falls back to BaseEvent, so restoring a checkpoint after a task failure silently dropped the whole event -- including `error`, a plain string that would otherwise have survived. Traded a loud failure for a quiet one. Measured before: dumped error_type='ValueError' and error='boom', restored as BaseEvent with neither attribute. After: restores as TaskFailedEvent with error='boom' and error_type is ValueError. A BeforeValidator resolves a name against real exception classes only -- builtins first, then a walk of BaseException.__subclasses__(). So this does not reopen the hole the class-typed field closes: "secret_token" resolves to nothing, is returned unchanged, and is rejected by the field's own type. Asserted for secret_token, sk_live_1234, dict and os. A name whose class is not imported in this process still degrades, which is deliberate: synthesising a class from an arbitrary string is the injection risk this field exists to avoid. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RfV2uMqWRcdfufMvtdCVoN --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-authored-by: Vidit Ostwal <110953813+Vidit-Ostwal@users.noreply.github.com>
87 lines
14 KiB
Plaintext
87 lines
14 KiB
Plaintext
---
|
|
title: القياس عن بُعد
|
|
description: فهم بيانات القياس عن بُعد التي يجمعها CrewAI وكيف تساهم في تحسين المكتبة.
|
|
icon: signal-stream
|
|
mode: "wide"
|
|
---
|
|
|
|
## القياس عن بُعد
|
|
|
|
<Note>
|
|
بشكل افتراضي، لا نجمع أي بيانات تُعتبر معلومات شخصية بموجب اللائحة العامة لحماية البيانات (GDPR) وغيرها من لوائح الخصوصية.
|
|
نحن نجمع أسماء الأدوات وأدوار الوكلاء، لذا يُنصح بعدم تضمين أي معلومات شخصية في أسماء الأدوات أو أدوار الوكلاء.
|
|
نظراً لعدم جمع معلومات شخصية، ليس من الضروري القلق بشأن إقامة البيانات.
|
|
عند تفعيل `share_crew`، يتم جمع بيانات إضافية قد تحتوي على معلومات شخصية إذا ضمّنها المستخدم.
|
|
يجب على المستخدمين توخي الحذر عند تفعيل هذه الميزة لضمان الامتثال للوائح الخصوصية.
|
|
</Note>
|
|
|
|
يستخدم CrewAI القياس عن بُعد المجهول لجمع إحصائيات الاستخدام بهدف أساسي هو تحسين المكتبة.
|
|
تركيزنا ينصبّ على تحسين وتطوير الميزات والتكاملات والأدوات الأكثر استخداماً من قبل مستخدمينا.
|
|
|
|
من المهم فهم أنه بشكل افتراضي، **لا يتم جمع أي بيانات شخصية** تتعلق بالموجهات أو أوصاف المهام أو خلفيات الوكلاء أو أهدافهم،
|
|
أو استخدام الأدوات أو استدعاءات API أو الاستجابات أو أي بيانات يعالجها الوكلاء أو الأسرار ومتغيرات البيئة.
|
|
عند تفعيل ميزة `share_crew`، يتم جمع بيانات تفصيلية تشمل أوصاف المهام وخلفيات وأهداف الوكلاء وسمات محددة أخرى
|
|
لتوفير رؤى أعمق. قد يتضمن جمع البيانات الموسع هذا معلومات شخصية إذا دمجها المستخدمون في طواقمهم أو مهامهم.
|
|
يجب على المستخدمين النظر بعناية في محتوى طواقمهم ومهامهم قبل تفعيل `share_crew`.
|
|
يمكن للمستخدمين تعطيل القياس عن بُعد عبر تعيين متغير البيئة `CREWAI_DISABLE_TELEMETRY` إلى `true` أو تعيين `OTEL_SDK_DISABLED` إلى `true` (لاحظ أن الأخير يعطل جميع أدوات OpenTelemetry عالمياً).
|
|
|
|
### أمثلة:
|
|
```python
|
|
# Disable CrewAI telemetry only
|
|
os.environ['CREWAI_DISABLE_TELEMETRY'] = 'true'
|
|
|
|
# Disable all OpenTelemetry (including CrewAI)
|
|
os.environ['OTEL_SDK_DISABLED'] = 'true'
|
|
```
|
|
|
|
### العزل عن إعداد OpenTelemetry الخاص بك
|
|
|
|
يعمل القياس عن بُعد الخاص بـ CrewAI على `TracerProvider` خاص به ولا يسجل نفسه
|
|
أبدًا كمزوّد عام. هذا يفصل الاتجاهين:
|
|
|
|
- لا تُرسَل أبدًا إلى CrewAI الامتدادات (spans) الصادرة عن المكتبات الأخرى
|
|
المزوّدة بأدوات القياس في عمليتك — أطر الويب، وعملاء قواعد البيانات،
|
|
وعملاء HTTP.
|
|
- لا تُرسَل امتدادات القياس عن بُعد الخاصة بـ CrewAI إلى نظام المراقبة لديك، لذا
|
|
لن تظهر في Langfuse أو Braintrust أو Phoenix أو أي مُجمِّع آخر تقوم بإعداده.
|
|
|
|
لا تتأثر تكاملات المراقبة: فهي تقيس CrewAI عبر مزوّد التتبع الخاص بها، وهو
|
|
مستقل عن المزوّد الموصوف هنا.
|
|
|
|
### شرح البيانات:
|
|
| افتراضي | البيانات | السبب والتفاصيل |
|
|
|:----------|:------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------|
|
|
| نعم | إصدار CrewAI وPython | تتبع إصدارات البرمجيات. مثال: CrewAI v1.2.3، Python 3.8.10. لا بيانات شخصية. |
|
|
| نعم | بيانات وصفية للطاقم | تشمل: مفتاح ومعرّف مُولّد عشوائياً، نوع العملية (مثل 'sequential'، 'parallel')، علم منطقي لاستخدام الذاكرة (true/false)، علم منطقي يوضح ما إذا تم تمرير أي مدخلات للتشغيل (true/false — وليس مفاتيح المدخلات أو قيمها، والتي لا تُجمع إلا عند تمكين `share_crew`)، عدد المهام، عدد الوكلاء. كلها غير شخصية. |
|
|
| نعم | بيانات الوكيل | تشمل: مفتاح ومعرّف مُولّد عشوائياً، اسم الدور (يجب ألا يتضمن معلومات شخصية)، إعدادات منطقية (verbose، التفويض مُفعّل، تنفيذ الكود مسموح)، أقصى عدد تكرارات، أقصى RPM، أقصى حد لإعادة المحاولة، معلومات LLM (انظر سمات LLM)، قائمة أسماء الأدوات (يجب ألا تتضمن معلومات شخصية). لا بيانات شخصية. |
|
|
| نعم | بيانات وصفية للمهمة | تشمل: مفتاح ومعرّف مُولّد عشوائياً، إعدادات تنفيذ منطقية (async_execution، human_input)، دور ومفتاح الوكيل المرتبط، قائمة أسماء الأدوات. كلها غير شخصية. |
|
|
| نعم | إحصائيات استخدام الأدوات | تشمل: اسم الأداة (يجب ألا يتضمن معلومات شخصية)، عدد محاولات الاستخدام (عدد صحيح)، سمات LLM المستخدمة. لا بيانات شخصية. |
|
|
| نعم | بيانات تنفيذ الاختبار | تشمل: مفتاح ومعرّف الطاقم المُولّد عشوائياً، عدد التكرارات، اسم النموذج المستخدم، درجة الجودة (عدد عشري)، وقت التنفيذ (بالثواني). كلها غير شخصية. |
|
|
| نعم | بيانات دورة حياة المهمة | تشمل: أوقات الإنشاء وبدء/انتهاء التنفيذ، معرّفات الطاقم والمهمة، وما إذا نجحت المهمة أو فشلت. وعند فشل المهمة، يُسجَّل **اسم صنف** الاستثناء (مثل `TimeoutError`) بحيث يمكن عدّ حالات الفشل وتشخيصها — وليس رسالة الخطأ أبدًا، فهي قد تحتوي على مطالبات أو مخرجات نموذج أو مسارات ملفات أو بيانات اعتماد. مخزنة كنطاقات مع طوابع زمنية. لا بيانات شخصية. |
|
|
| نعم | سمات LLM | تشمل: الاسم، model_name، model، top_k، temperature، واسم فئة LLM. كلها بيانات تقنية غير شخصية. |
|
|
| نعم | إنشاء مشروع باستخدام CLI الخاص بـ CrewAI | تشمل: أن مشروعًا جديدًا أُنشئ عبر `crewai create`، ونوعه (`crew` أو `json_crew` أو `flow`)، ومعرّف المشروع الذي تم توليده لهذا المشروع الجديد وكُتب في ملف `pyproject.toml` الخاص به. وهو معرّف المشروع الجديد نفسه، ويُسجَّل بشكل منفصل عن `project_id` الخاص بالمجلد الذي شُغّل منه الأمر — وقد يختلفان. لا اسم مشروع، ولا محتويات ملفات، ولا شيفرة. لا بيانات شخصية. |
|
|
| نعم | محاولة نشر الطاقم باستخدام CLI الخاص بـ CrewAI | تشمل: حقيقة إجراء النشر ومعرّف الطاقم، وما إذا كان يحاول سحب السجلات، وما إذا بدأ النشر من أمر CLI أو من واجهة التشغيل TUI. لا تُسجَّل محتويات المشروع أو الطاقم. لا توجد بيانات شخصية. |
|
|
| نعم | بيئة التنفيذ | تشمل: مساعد البرمجة بالذكاء الاصطناعي الذي يشغّل العملية إن وُجد (واحد من قائمة ثابتة مثل `claude_code` أو `codex` أو `cursor` أو `unknown`)، ومكان تشغيل العملية (واحد من قائمة ثابتة مثل `ci` أو `container` أو `serverless` أو `interactive`)، و`project_id` من ملف `pyproject.toml` عند ضبطه. يتحقق الاكتشاف فقط مما إذا كانت متغيرات البيئة المعروفة مضبوطة، ولا يقرأ قيمها أبدًا. لا بيانات شخصية. |
|
|
| نعم | إشارات دورة حياة التدفق | تشمل: بدء التدفق، وما إذا اكتمل أو فشل، وما إذا فشلت إحدى طرقه، وما إذا توقف مؤقتًا لانتظار إدخال أو ملاحظات بشرية، وما إذا كان البدء تشغيلًا مستأنفًا، وما إذا فشل دور محادثة، ومدة تشغيل التدفق، وما إذا كان التدفق مما تشغّله CrewAI داخليًا أو مما كتبته أنت. ويُسجَّل اسم التدفق، كما هو الحال بالفعل لإنشاء التدفق وتنفيذه. وعند فشل تدفق أو إحدى طرقه، يُسجَّل **اسم فئة** الاستثناء (مثل `TimeoutError`) لتشخيص الأعطال — ولا تُسجَّل أبدًا رسالة الخطأ، التي قد تحتوي على مطالبات أو مخرجات النموذج أو مسارات ملفات أو بيانات اعتماد. ولا تُسجَّل أبدًا أسماء الطرق أو حالة التدفق. لا توجد بيانات شخصية. |
|
|
| نعم | إشارة مشاركة التتبع | تشمل: نجاح مشاركة دفعة من عمليات التتبع مع CrewAI AMP، وما إذا تمت المشاركة بشكل مجهول (قبل إنشاء حساب) أو مرتبطة بحسابك. ومثل كل span، تحمل أيضًا سمات بيئة التنفيذ الموضحة أعلاه (`project_id` عند تكوينه، ومساعد البرمجة، وبيئة التشغيل). يصف هذا الصف بيانات القياس عن بُعد الخاصة بالمشاركة فقط — وليس محتويات التتبع أو الوصول الذي تمنحه روابط التتبع المشتركة. لا تُسجَّل محتويات التتبع أو المدخلات أو المخرجات في هذه الإشارة. قبل مشاركة التتبعات، راجع الأسرار والبيانات الشخصية وإعدادات التنقيح والاحتفاظ في AMP. |
|
|
| لا | بيانات الوكيل الموسّعة | تشمل: وصف الهدف، نص الخلفية، معرّف ملف موجهات i18n. يجب على المستخدمين التأكد من عدم تضمين معلومات شخصية في حقول النص. |
|
|
| لا | معلومات المهمة التفصيلية | تشمل: وصف المهمة، وصف المخرجات المتوقعة، مراجع السياق. يجب على المستخدمين التأكد من عدم تضمين معلومات شخصية في هذه الحقول. |
|
|
| لا | معلومات البيئة | تشمل: المنصة، الإصدار، النظام، الإصدار، وعدد وحدات المعالجة المركزية. مثال: 'Windows 10'، 'x86_64'. لا بيانات شخصية. |
|
|
| لا | مدخلات ومخرجات الطاقم والمهام | تشمل: معاملات الإدخال ونتائج المخرجات كبيانات غير قابلة للتعريف. يجب على المستخدمين التأكد من عدم تضمين معلومات شخصية. |
|
|
| لا | بيانات تنفيذ الطاقم الشاملة | تشمل: سجلات مفصّلة لعمليات الطاقم، جميع بيانات الوكلاء والمهام، المخرجات النهائية. كلها غير شخصية وتقنية بطبيعتها. |
|
|
|
|
<Note>
|
|
"لا" في عمود "افتراضي" تشير إلى أن هذه البيانات تُجمع فقط عند تعيين `share_crew` إلى `true`.
|
|
</Note>
|
|
|
|
### الاشتراك في مشاركة قياس عن بُعد إضافية
|
|
|
|
يمكن للمستخدمين اختيار مشاركة بيانات القياس عن بُعد الكاملة عبر تفعيل سمة `share_crew` إلى `True` في تكوينات طواقمهم.
|
|
تفعيل `share_crew` يؤدي إلى جمع بيانات تفصيلية لتنفيذ الطاقم والمهام، بما في ذلك `goal` و`backstory` و`context` و`output` للمهام.
|
|
يتيح هذا رؤية أعمق لأنماط الاستخدام.
|
|
|
|
<Warning>
|
|
إذا فعّلت `share_crew`، فقد تتضمن البيانات المجمعة معلومات شخصية إذا تم دمجها في تكوينات الطاقم أو أوصاف المهام أو المخرجات.
|
|
يجب على المستخدمين مراجعة بياناتهم بعناية وضمان الامتثال للائحة العامة لحماية البيانات (GDPR) وغيرها من لوائح الخصوصية المعمول بها قبل تفعيل هذه الميزة.
|
|
</Warning>
|