agenteye-collector أن تصل بيانات المراقبة (telemetry) لوكلائك إلى AgentEye دون أن يعطل تطبيقك أبداً. يكتب الكود الخاص بك الأحداث إلى دليل محلي ثم ينتقل; يتولى المجمّع المسؤولية من هناك، ويرفع كل ملف خلال ملي ثوان ويبقى صامداً في وجه إعادة التشغيل والانقطاعات الشبكية والأخطاء العابرة في الخادم. تُعاد محاولات الرفع الفاشلة مع تأخير بتراجع أسي (exponential backoff)، وكنس دوري للاسترجاع يعيد قائمة أي شيء تُرك خلفه عند تعطل أو نشر. والنتيجة هي توصيل متين وتجاهل وانطلق (fire-and-forget): يواصل الوكلاء الخاص بك العمل بسرعة كاملة بينما يضمن المجمّع عدم فقدان أي أحداث أثناء النقل.
من الناحية الميكانيكية، المجمّع هو خادم خفيف الوزن يراقب $AGENTEYE_HOME/events/ (الافتراضي: ~/.agenteye/events/) بحثاً عن ملفات .jsonl مكتوبة بواسطة Python SDK ويرفعها إلى خادم AgentEye.
تمت إعادة التسمية: أصبح أمر المجمّع الآنagenteye-collector(كان يُسمى سابقاًagenteye). اسمagenteyeالأقصر يعود الآن إلى AgentEye CLI. إذا كنت تقوم بترقية تثبيت موجود، انظر enterprise-docs/collector-migration.md.
المتطلبات الأساسية
AGENTEYE_TOKENالخاص بك: رمز الوصول الشخصي لـ GitHub الذي تُنشئه بنفسك (انظر enterprise-docs/github-token.md)- عنوان URL للخادم ومفتاح API للمجمّع (انظر enterprise-docs/api-keys.md)
الخيار أ: الملف الثنائي (موصى به)
ملفات ثنائية ثابتة مجهزة مسبقاً متاحة لـ Linux و macOS و Windows (x86_64 و arm64). حمّل الملف الثنائي لنظامك مباشرة من مستودعagenteye-enterprise/releases تحت أحدث علامة إصدار collector/v<version>.
أسماء الأعمال المتاحة:
| المنصة | الأعمال |
|---|---|
| Linux x86_64 | agenteye-collector-linux-x86_64 |
| Linux arm64 | agenteye-collector-linux-arm64 |
| macOS x86_64 | agenteye-collector-darwin-x86_64 |
| macOS arm64 | agenteye-collector-darwin-arm64 |
| Windows x86_64 | agenteye-collector-windows-x86_64.exe |
| Windows arm64 | agenteye-collector-windows-arm64.exe |
gh (استبدل الإصدار واختر أعمال منصتك):
curl:
الخيار ب: Docker
تنشر إصدارات بيتا الحالية العلامة العائمةالتشغيل::beta-latest؛ يتم تعيين:latestفقط للإصدارات المستقرة. للنشرات القابلة للتكرار، فضّل علامة إصدار محددة مثل:v0.0.1-beta.13.
AGENTEYE_HOME بشكل صريح وجهز مجلد الانتظار المضيف له. يشاركك وصل المجلد نفس دليل ~/.agenteye/ الذي يكتب إليه Python SDK على المضيف. إذا كنت قد ضبطت AGENTEYE_HOME في مكان آخر على المضيف، جهز ذلك الدليل بدلاً من $HOME/.agenteye.
الإعدادات
يمكن تعيين جميع الخيارات بثلاث طرق (من الأعلى أولويةً أولاً):- علم سطر الأوامر:
agenteye-collector start --url https://... - متغير البيئة:
AGENTEYE_URL=https://... - ملف الإعدادات:
~/.agenteye/config.json
الخيارات المطلوبة
| الخيار | علم CLI | متغير البيئة | مفتاح config.json |
|---|---|---|---|
| عنوان URL للواجهة الخلفية | --url <URL> | AGENTEYE_URL | "url" |
| مفتاح API | --key <KEY> | AGENTEYE_KEY | "key" |
الخيارات الاختيارية (مع الافتراضيات)
| الخيار | علم CLI | متغير البيئة | مفتاح config.json | الافتراضي |
|---|---|---|---|---|
| الحد الأقصى للرفع المتزامن | --max-concurrent-uploads <N> | AGENTEYE_MAX_CONCURRENT_UPLOADS | "max_concurrent_uploads" | 64 |
| فترة الكنس (ث) | --sweep-interval <S> | AGENTEYE_SWEEP_INTERVAL | "sweep_interval_secs" | 60 |
| الحد الأدنى لعمر الملف في الكنس (ث) | --sweep-min-age <S> | AGENTEYE_SWEEP_MIN_AGE | "sweep_min_age_secs" | 120 |
| الحد الأقصى للملفات لكل كنس | --sweep-max-files <N> | AGENTEYE_SWEEP_MAX_FILES | "sweep_max_files" | 64 |
| الحد الأقصى لمحاولات الرفع | --max-retries <N> | AGENTEYE_MAX_RETRIES | "max_retries" | 5 |
| تأخير أساس إعادة المحاولة (مللي ث) | --retry-base-delay <MS> | AGENTEYE_RETRY_BASE_DELAY | "retry_base_delay_ms" | 1000 |
خيارات mTLS (اختياري)
بالنسبة للنشرات التي تتطلب TLS المتبادل (mTLS)، يمكن للمجمّع تقديم شهادة عميل أثناء مصافحة TLS. عندما لا يتم تعيين هذه الخيارات، يستخدم المجمّع HTTPS القياسي.| الخيار | علم CLI | متغير البيئة | مفتاح config.json |
|---|---|---|---|
| شهادة العميل (PEM) | --tls-cert <PATH> | AGENTEYE_TLS_CERT | "tls_cert" |
| المفتاح الخاص للعميل (PEM) | --tls-key <PATH> | AGENTEYE_TLS_KEY | "tls_key" |
| شهادة CA مخصصة (PEM) | --tls-ca <PATH> | AGENTEYE_TLS_CA | "tls_ca" |
--tls-cert و --tls-key معاً. يجب أن تكون الملفات بصيغة PEM.
--tls-ca مستقل وضروري فقط عندما يقدم خادم AgentEye شهادة TLS لم تصدرها جهة اعتماد موثوقة علناً (على سبيل المثال، موقّعة ذاتياً بواسطة مُصدر cert-manager داخل المجموعة عندما لا يكون لديك نطاق DNS حقيقي). يضيف المجمّع الشهادة المرفوعة كنقطة ثقة إضافية؛ تبقى الجذور العامة الموثوقة موثوقة، لذا لا تتأثر النشرات الموجودة. قد يحتوي الملف على شهادة PEM واحدة أو سلسلة كاملة (كتل PEM متعددة متسلسلة).
تشغيل المجمّع كـ sidecar في حاوية تطبيقك؟ انظر enterprise-docs/single-pod-deployment.md لنمط EKS من النهاية إلى النهاية: حزمة mTLS يتم تسليمها عبر AWS Secrets Manager + Secrets Store CSI Driver + IRSA، مع الدوران التلقائي.
عند التشغيل في Kubernetes مع نمط تسليم الخدمة السرية، جهز الخدمة السرية للشهادة كمجلد وأشر هذه المسارات إلى الملفات المجهزة:
مثال ~/.agenteye/config.json
AGENTEYE_HOME، يتم استخدام ذلك الدليل بدلاً من ~/.agenteye.
الإعداد للمرة الأولى
بعد التثبيت، جهز المجمّع برقم خادم عنوان URL ومفتاح API:استخدماختبر الاتصال (تطبيق الامتصاص الواحد، الخروج بعد استنزاف الأحداث المعلقة):httpsلأي نشر يعبر شبكة غير موثوقة بحيث لا يتم إرسال الأحداث بنص عادي. نموذج النص العاديhttp://your-server-host:8080/eventsمناسب فقط للاختبار المحلي تماماً ضد خادم على نفس المضيف.
flush تقدمه إلى stdout. عندما يكون مجلد الانتظار فارغاً يطبع No pending files. والخروج 0. خلاف ذلك يطبع سطراً واحداً لكل ملف ([UPLOADED] <file> أو [FAILED] <file> (<reason>)), متبوعاً بملخص Done: <uploaded>/<total> uploaded, <failed> failed.. هذا يجعل flush فحصاً مفيداً للاستخدام الواحد بأن عنوان URL ومفتاح API وإعدادات TLS الخاصة بك صحيحة قبل بدء الخادم.
التشغيل كخادم
مباشر
الحاوية / Docker
عندما يشاركك المجمّع والتطبيق حاوية، شغلهما تحت مراقب العملية. الخيار الأبسط هوsupervisord؛ يأتي في كل توزيع رئيسي، ويعيد تشغيل العمليات المتعطلة، ويعيد توجيه الإشارات، وينتظر الإغلاق البطيء.
Dockerfile:
supervisord.conf:
autorestart=trueعلى agenteye-collector: أعد التشغيل عند أي خروج (تعطل، ذعر، OOM).autorestart=unexpectedعلى التطبيق: أعد التشغيل فقط عند خروج غير صفري، بحيث لا يحلقة وكيل الاستخدام الواحد الذي يخرج 0.stopwaitsecs=30: يعطي المجمّع مجالاً لاستنزاف الرفع المعلقة على SIGTERM قبل أن يصعد supervisord إلى SIGKILL.stdout_logfile=/dev/stdout,*_maxbytes=0: بث إخراج كلا البرنامجين إلى حاوية stdout؛ لا توجد ملفات سجل داخل الحاوية.
AGENTEYE_URL / AGENTEYE_KEY (وأي متغيرات بيئة TLS) على docker run -e كما هو الحال من قبل؛ يرث supervisord البيئة.
حاويات منفصلة؟ إذا قمت بتشغيل المجمّع كحاوية منفصلة (خدمة Docker Compose, Kubernetes sidecar, إلخ.)، لا تستخدم supervisord؛ سياسة إعادة تشغيل الحاوية runtime تقوم بهذه الوظيفة بالفعل. انظر enterprise-docs/single-pod-deployment.md لنمط EKS sidecar.مسبار حيوية Kubernetes (ينطبق سواء تم تشغيل المجمّع وحده أو تحت supervisord):
$AGENTEYE_HOME/health.json كل 30 ثانية. يقرأ agenteye-collector health ذلك الملف والخروج 0 (صحي) فقط عندما تكون نبضة القلب طازجة وتعمل مهام الرفع بشكل طبيعي؛ يخرج 1 (غير صحي) عندما تكون نبضة القلب أقدم من 90 ثانية (على سبيل المثال، توقف الخادم) أو بينما يتم إعادة تشغيل المراقب والكنس بعد خروج غير متوقع. يتم كتابة نبضة القلب فقط بواسطة start, لذا قم بتشغيل المسبار ضد الخادم طويل الأمد وليس الأمر flush الواحد.
systemd (Linux، موصى به للإنتاج)
/etc/agenteye/env:
launchd (macOS)
ترقية المجمّع
لا يحدّث المجمّع نفسه. للترقية:- الملف الثنائي: حمّل أعمال
agenteye-collector-<os>-<arch>الجديدة من أحدث إصدارcollector/v<version>(انظر الخيار أ)، استبدل/usr/local/bin/agenteye-collector، ثم أعد تشغيل الخدمة (sudo systemctl restart agenteye-collector, إعادةlaunchctl load، أو إعادة تشغيل مراقبك). - Docker:
docker pull ghcr.io/agenteye-enterprise/collector:beta-latest(أو علامة:v<version>محددة؛:latestموجودة فقط للإصدارات المستقرة) وأعد إنشاء الحاوية.
AGENTEYE_TOKEN مطلوب لتحميل الملفات الثنائية/الصور الجديدة من مستودع الإصدارات الخاص، لكنه ليس ضروري بواسطة الخادم الجاري.
الأوامر الفرعية
| الأمر | الوصف |
|---|---|
agenteye-collector start | ابدأ الخادم طويل الأمد. عند بدء التشغيل، يقوم بتطبيق امتصاص أي أحداث متبقية من التشغيل السابق، ثم يراقب الملفات الجديدة ويرفعها. يتم إعادة تشغيل المراقب والكنس تلقائياً عند خروج غير متوقع، وتتم كتابة نبضة قلب إلى health.json كل 30 ثانية. |
agenteye-collector flush | استخدام واحد: رفع جميع الملفات المعلقة والخروج. يطبع No pending files. عندما يكون مجلد الانتظار فارغاً, خلاف ذلك لكل ملف [UPLOADED]/[FAILED] سجل وملخص Done: <uploaded>/<total> uploaded, <failed> failed.. |
agenteye-collector health | اقرأ نبضة القلب health.json للخادم. الخروج 0 عندما يكون طازجاً وصحياً؛ الخروج 1 عندما تكون نبضة القلب قديمة (أقدم من 90 ثانية) أو تعاد تشغيل المهام. |
تخطيط الدليل
failed/ لا تُعاد محاولة تلقائياً. لإعادة قائمة متابعتها يدويّاً، انقل الملفات مرة أخرى إلى events/ وشغّل agenteye-collector flush.
