agenteye-collector đảm bảo rằng telemetry của các agent của bạn đến AgentEye mà không bao giờ làm chậm ứng dụng của bạn. Mã của bạn ghi các sự kiện vào một thư mục cục bộ và tiếp tục; collector nhận trách nhiệm từ đó, tải lên từng file trong vài mili giây và tồn tại qua các lần khởi động lại, sự cố mạng và lỗi máy chủ tạm thời. Các lần tải lên thất bại được thử lại với exponential backoff, và một lần quét phục hồi định kỳ tái xếp hàng bất kỳ thứ gì bị bỏ lại do sự cố hoặc triển khai. Kết quả là truyền tải bền vững, fire-and-forget: các agent của bạn tiếp tục chạy ở tốc độ tối đa trong khi collector đảm bảo không có sự kiện nào bị mất trong quá trình truyền.
Về mặt cơ học, collector là một daemon nhẹ theo dõi $AGENTEYE_HOME/events/ (mặc định: ~/.agenteye/events/) để tìm các file .jsonl được viết bởi Python SDK và tải chúng lên máy chủ AgentEye.
Đã được đổi tên: lệnh collector bây giờ làagenteye-collector(trước đó làagenteye). Tên ngắnagenteyebây giờ thuộc về CLI AgentEye. Nếu bạn đang nâng cấp cài đặt hiện có, xem enterprise-docs/collector-migration.md.
Điều kiện tiên quyết
AGENTEYE_TOKENcủa bạn: một GitHub PAT mà bạn tự tạo (xem enterprise-docs/github-token.md)- URL máy chủ và một khóa API collector (xem enterprise-docs/api-keys.md)
Tùy chọn A: Binary (được khuyến nghị)
Các binary tĩnh được xây dựng sẵn có sẵn cho Linux, macOS và Windows (x86_64 và arm64). Tải xuống binary cho nền tảng của bạn trực tiếp từ repoagenteye-enterprise/releases dưới tag phát hành mới nhất collector/v<version>.
Tên artifact có sẵn:
| Nền tảng | Artifact |
|---|---|
| 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 (thay đổi phiên bản và chọn artifact của nền tảng của bạn):
curl:
Tùy chọn B: Docker
Các bản dựng beta hiện tại xuất bản tag nổiChạy::beta-latest;:latestđược gán chỉ cho các phát hành ổn định. Để triển khai có thể lặp lại, hãy ưu tiên một tag phiên bản được ghim như:v0.0.1-beta.13.
AGENTEYE_HOME rõ ràng và gắn kết spool máy chủ lưu trữ vào nó. Mount volume chia sẻ cùng một thư mục ~/.agenteye/ mà Python SDK ghi vào trên máy chủ. Nếu bạn đã đặt AGENTEYE_HOME ở nơi khác trên máy chủ, hãy gắn kết thư mục đó thay vì $HOME/.agenteye.
Cấu hình
Tất cả các tùy chọn có thể được đặt ba cách (ưu tiên cao nhất trước):- Cờ CLI:
agenteye-collector start --url https://... - Biến môi trường:
AGENTEYE_URL=https://... - File cấu hình:
~/.agenteye/config.json
Tùy chọn bắt buộc
| Tùy chọn | Cờ CLI | Biến env | khóa config.json |
|---|---|---|---|
| URL backend | --url <URL> | AGENTEYE_URL | "url" |
| Khóa API | --key <KEY> | AGENTEYE_KEY | "key" |
Tùy chọn tùy chọn (với mặc định)
| Tùy chọn | Cờ CLI | Biến env | khóa config.json | Mặc định |
|---|---|---|---|---|
| Tối đa các lần tải lên đồng thời | --max-concurrent-uploads <N> | AGENTEYE_MAX_CONCURRENT_UPLOADS | "max_concurrent_uploads" | 64 |
| Khoảng thời gian quét (s) | --sweep-interval <S> | AGENTEYE_SWEEP_INTERVAL | "sweep_interval_secs" | 60 |
| Tuổi file tối thiểu của quét (s) | --sweep-min-age <S> | AGENTEYE_SWEEP_MIN_AGE | "sweep_min_age_secs" | 120 |
| Tối đa file trên mỗi lần quét | --sweep-max-files <N> | AGENTEYE_SWEEP_MAX_FILES | "sweep_max_files" | 64 |
| Tối đa lần thử tải lên | --max-retries <N> | AGENTEYE_MAX_RETRIES | "max_retries" | 5 |
| Độ trễ cơ sở thử lại (ms) | --retry-base-delay <MS> | AGENTEYE_RETRY_BASE_DELAY | "retry_base_delay_ms" | 1000 |
Tùy chọn mTLS (tùy chọn)
Đối với các triển khai yêu cầu TLS lẫn nhau (mTLS), collector có thể trình bày chứng chỉ máy khách trong bắt tay TLS. Khi các tùy chọn này không được đặt, collector sử dụng HTTPS tiêu chuẩn.| Tùy chọn | Cờ CLI | Biến env | khóa config.json |
|---|---|---|---|
| Chứng chỉ máy khách (PEM) | --tls-cert <PATH> | AGENTEYE_TLS_CERT | "tls_cert" |
| Khóa riêng máy khách (PEM) | --tls-key <PATH> | AGENTEYE_TLS_KEY | "tls_key" |
| Chứng chỉ CA tùy chỉnh (PEM) | --tls-ca <PATH> | AGENTEYE_TLS_CA | "tls_ca" |
--tls-cert và --tls-key phải được đặt cùng nhau. Các file phải được mã hóa PEM.
--tls-ca là độc lập và chỉ cần khi máy chủ AgentEye trình bày chứng chỉ TLS không được cấp bởi CA được tin cậy công khai (ví dụ: tự ký bởi một trình phát hành cert-manager trong cụm khi bạn không có tên miền DNS thực). Collector thêm CA được cung cấp làm một liên kết tin tưởng bổ sung; các gốc công khai tiêu chuẩn vẫn được tin tưởng, vì vậy các triển khai hiện có không bị ảnh hưởng. File có thể chứa một chứng chỉ PEM đơn lẻ hoặc một chuỗi đầy đủ (nhiều khối PEM được nối).
Chạy collector như một sidecar trong pod ứng dụng của bạn? Xem enterprise-docs/single-pod-deployment.md để biết mẫu EKS end-to-end: gói mTLS được cung cấp thông qua AWS Secrets Manager + Secrets Store CSI Driver + IRSA, với xoay vòng tự động.
Khi chạy trong Kubernetes với mẫu bàn giao Secret, gắn kết Secret chứng chỉ dưới dạng một volume và trỏ các đường dẫn này đến các file được gắn kết:
Ví dụ ~/.agenteye/config.json
AGENTEYE_HOME được đặt, thư mục đó được sử dụng thay vì ~/.agenteye.
Thiết lập lần đầu tiên
Sau khi cài đặt, hãy cấu hình collector với URL máy chủ và khóa API của bạn:Sử dụngKiểm tra kết nối (xả lần đầu tiên, thoát sau khi hết các sự kiện chờ):httpscho bất kỳ triển khai nào vượt qua một mạng không đáng tin cậy để các sự kiện không được gửi dưới dạng văn bản thuần. Dạnghttp://your-server-host:8080/eventsthuần túy chỉ thích hợp để kiểm tra cục bộ hoàn toàn chống lại máy chủ trên cùng một máy chủ.
flush báo cáo tiến độ của nó cho stdout. Khi spool trống, nó in No pending files. và thoát 0. Ngược lại, nó in một dòng cho mỗi file ([UPLOADED] <file> hoặc [FAILED] <file> (<reason>)), theo sau bởi tóm tắt Done: <uploaded>/<total> uploaded, <failed> failed.. Điều này làm cho flush là một kiểm tra tiện lợi một lần để URL, khóa và cài đặt TLS của bạn đúng trước khi bạn bắt đầu daemon.
Chạy như một Daemon
Trực tiếp
Container / Docker
Khi collector và ứng dụng của bạn chia sẻ một container, hãy chạy chúng dưới một giám sát quy trình. Tùy chọn đơn giản nhất làsupervisord; nó được cung cấp trong mỗi bản phân phối chính, khởi động lại các quy trình bị sự cố, chuyển tiếp các tín hiệu và chờ tắt một cách duyên dáng.
Dockerfile:
supervisord.conf:
autorestart=truetrên agenteye-collector: khởi động lại khi thoát bất kỳ (sự cố, panic, OOM).autorestart=unexpectedtrên ứng dụng: khởi động lại chỉ khi thoát không bằng 0, vì vậy một agent một lần thoát 0 không lặp lại.stopwaitsecs=30: cung cấp phòng cho collector để hết các lần tải lên chờ đợi trên SIGTERM trước khi supervisord leo thang lên SIGKILL.stdout_logfile=/dev/stdout,*_maxbytes=0: luồng đầu ra của cả hai chương trình đến container stdout; không có file nhật ký bên trong container.
AGENTEYE_URL / AGENTEYE_KEY (và bất kỳ biến env TLS nào) trên docker run -e như trước; supervisord kế thừa môi trường.
Các container riêng biệt? Nếu bạn chạy collector như một container của riêng nó (dịch vụ Docker Compose, sidecar Kubernetes, v.v.), đừng sử dụng supervisord; chính sách khởi động lại của vận hành container đã làm công việc này. Xem enterprise-docs/single-pod-deployment.md cho mẫu sidecar EKS.Kubernetes liveness probe (áp dụng cho dù collector chạy một mình hoặc dưới supervisord):
$AGENTEYE_HOME/health.json mỗi 30 giây. agenteye-collector health đọc file đó và thoát 0 (khỏe mạnh) chỉ khi nhịp tim tươi mới và các nhiệm vụ tải lên chạy bình thường; nó thoát 1 (không khỏe) khi nhịp tim cũ hơn 90 giây (ví dụ: daemon đã dừng) hoặc trong khi watcher và sweeper đang khởi động lại sau một lần thoát không mong muốn. Nhịp tim chỉ được viết bởi start, vì vậy hãy chạy probe chống lại daemon lâu dài thay vì lệnh flush một lần.
systemd (Linux, được khuyến nghị cho sản xuất)
/etc/agenteye/env:
launchd (macOS)
Nâng cấp Collector
Collector không tự cập nhật. Để nâng cấp:- Binary: tải xuống artifact
agenteye-collector-<os>-<arch>mới từ phát hànhcollector/v<version>mới nhất (xem Tùy chọn A), thay thế/usr/local/bin/agenteye-collector, rồi khởi động lại dịch vụ (sudo systemctl restart agenteye-collector,launchctl loadlại, hoặc khởi động lại supervisor của bạn). - Docker:
docker pull ghcr.io/agenteye-enterprise/collector:beta-latest(hoặc một tag:v<version>được ghim;:latestchỉ tồn tại cho các phát hành ổn định) và tạo lại container.
AGENTEYE_TOKEN được yêu cầu để tải xuống các binary/image mới từ repo phát hành riêng, nhưng không được cần bởi daemon đang chạy.
Các lệnh phụ
| Lệnh | Mô tả |
|---|---|
agenteye-collector start | Bắt đầu daemon lâu dài. Khi khởi động, nó xả bất kỳ sự kiện nào còn lại từ lần chạy trước, sau đó theo dõi các file mới và tải chúng lên. Watcher và sweeper tự động khởi động lại khi thoát không mong muốn, và một nhịp tim được viết vào health.json mỗi 30 giây. |
agenteye-collector flush | Một lần: tải lên tất cả các file chờ đợi và thoát. In No pending files. khi spool trống, ngược lại một nhật ký [UPLOADED]/[FAILED] cho mỗi file và một tóm tắt Done: <uploaded>/<total> uploaded, <failed> failed.. |
agenteye-collector health | Đọc nhịp tim health.json của daemon. Thoát 0 khi tươi mới và khỏe mạnh; thoát 1 khi nhịp tim cũ (cũ hơn 90 giây) hoặc các nhiệm vụ đang khởi động lại. |
Bố cục thư mục
failed/ không được tự động thử lại. Để tái xếp hàng chúng theo cách thủ công, hãy di chuyển chúng trở lại events/ và chạy agenteye-collector flush.
