ایجنت ابرووا تریس (Docker)

ایجنت ابرووا تریس لاگ همه‌ی کانتینرهای Docker روی سرورهای شما را استریم می‌کند؛ همراه با مدیریت کانتینر، آمار زنده، پشتیبانی از چند سرور، پوشاندن اطلاعات محرمانه و تشخیص خودکار سطح لاگ. با یک دستور راه‌اندازی می‌شود.

ایجنت ابرووا تریس لاگ همه‌ی کانتینرهای Docker روی سرور شما را استریم می‌کند؛ همراه با مدیریت لحظه‌ای کانتینرها، پشتیبانی از چند سرور و تشخیص خودکار سطح لاگ. برای راه‌اندازی فقط یک دستور docker run لازم است.

ایجنت چه چیزهایی به شما می‌دهد.

لاگ زنده‌ی Docker در کنسول ابرووا — همه‌ی کانتینرها و همه‌ی سرورها در یک فید
مدیریت کانتینر از کنسول: start، stop، restart و حذف
آمار زنده‌ی CPU، حافظه و شبکه برای هر کانتینر
چند سرور: یک collector لاگ ایجنت‌های راه دور روی سرورهای دیگر را جمع می‌کند
تشخیص خودکار سطح لاگ، یکی کردن خروجی چندخطی (هر stack trace یک ورودی می‌شود) و پوشاندن اطلاعات محرمانه پیش از خروج هر چیزی از سرور

هزینه از کیف پول.

لاگ کانتینرها جزو لاگ‌های ابرووا تریس شما حساب می‌شود: ۱ گیگابایت رایگان در هر ماه، و بعد از آن هر گیگابایت ۱۵٬۰۰۰ تومان هزینه از کیف پول. قیمت‌ها را ببینید.

نحوه‌ی کار#

ایجنت از معماری collector + ایجنت راه دور استفاده می‌کند:

collector روی سرور اصلی شما اجرا می‌شود. کانتینرهای محلی را زیر نظر می‌گیرد، به ایجنت‌های راه دور وصل می‌شود و لاگ‌ها را دسته‌دسته از طریق HTTPS به ابرووا تریس می‌فرستد.
ایجنت‌های راه دور روی سرورهای دیگر اجرا می‌شوند و لاگ کانتینرهایشان را از طریق WebSocket به collector استریم می‌کنند.
همه‌ی کانتینرها (در حال اجرا و متوقف) در پروژه‌ی شما ثبت می‌شوند تا بتوانید آن‌ها را ببینید و مدیریت کنید.
ارتباط دوطرفه است، پس دستورهای کانتینر (start، stop، restart، حذف، آمار) به هر سروری می‌رسند.

اگر فقط یک سرور دارید، همان collector کافی است؛ حالت پیش‌فرض هم همین است.

حالت	دستور	کارکرد
پیش‌فرض (collector)	(none)	Docker محلی را زیر نظر می‌گیرد و به ایجنت‌های راه دور وصل می‌شود؛ لاگ‌ها را به ابرووا تریس می‌فرستد. به کلید نیاز دارد
ایجنت	agent	سرور WebSocket که لاگ کانتینرهای این سرور را به یک collector استریم می‌کند. کلید لازم ندارد
فقط collector	collector	فقط به ایجنت‌های راه دور وصل می‌شود و Docker محلی را زیر نظر نمی‌گیرد. به کلید نیاز دارد

راه‌اندازی روی یک سرور#

bash

docker run -d \
  --name abrova-trace-agent \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v abrova-trace-agent-data:/var/lib/abrova-trace-agent \
  -e ABROVA_TRACE_API_KEY=ab_srv_your_server_secret \
  ghcr.io/abrova-co/abrova-trace-agent:latest

ایمیج از کجا می‌آید.

ایمیج ایجنت از ghcr.io (رجیستری کانتینر GitHub) دریافت می‌شود، پس سرور باید به آن دسترسی داشته باشد. اگر دسترسی ندارد، ایمیج را روی دستگاهی که دسترسی دارد pull کنید و بعد با docker save ghcr.io/abrova-co/abrova-trace-agent:latest -o agent.tar و docker load -i agent.tar منتقلش کنید.

این volume بافر دیسک ایجنت و موقعیت‌های خوانده‌شده را هنگام ساخت دوباره‌ی کانتینر نگه می‌دارد تا هیچ خطی گم نشود یا دو بار فرستاده نشود.

کدام کلید؟

کلید سرور پروژه (ab_srv_...) را در ABROVA_TRACE_API_KEY به ایجنت بدهید. کلید اپ (ab_live_...) هم تا وقتی تنظیم پروژه‌ی Server routes require the server secret خاموش است کار می‌کند، اما این کلید داخل اپ‌های شما منتشر می‌شود و نباید ایجنت با آن اجرا شود. کلید سرور و مسیرهای سرور را ببینید.

ایجنت ظرف چند ثانیه همه‌ی کانتینرهای در حال اجرا و متوقف را در پروژه‌ی شما ثبت می‌کند. در کنسول ابرووا، ابرووا تریس › Logs را باز کنید تا رسیدن لاگ‌ها را ببینید.

راه‌اندازی چند سرور#

برای چند سرور، روی هر سرور اضافه یک ایجنت راه دور راه بیندازید و یک collector را به آن‌ها وصل کنید.

ایجنت راه دور (روی هر سرور اضافه)

bash

docker run -d \
  --name abrova-trace-agent \
  --restart=always \
  -p 7008:7008 \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -e ABROVA_TRACE_HOSTNAME=server-2 \
  ghcr.io/abrova-co/abrova-trace-agent:latest agent

collector (روی سرور اصلی)

bash

docker run -d \
  --name abrova-trace-agent \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v abrova-trace-agent-data:/var/lib/abrova-trace-agent \
  -e ABROVA_TRACE_API_KEY=ab_srv_your_server_secret \
  -e ABROVA_TRACE_REMOTE_AGENTS=server2:YOUR_SERVER2_HOST:7008,server3:YOUR_SERVER3_HOST:7008 \
  ghcr.io/abrova-co/abrova-trace-agent:latest

مقدار ABROVA_TRACE_REMOTE_AGENTS فهرستی از name:host:port است که با کاما جدا شده‌اند. هر ایجنت راه دور لاگ‌ها را از طریق WebSocket به collector استریم می‌کند و پس از قطع ارتباط خودش دوباره وصل می‌شود (هر ۵ ثانیه).

راه‌اندازی از اپ دسکتاپ.

اپ دسکتاپ ابرووا (به‌زودی) ایجنت را از طریق SSH برایتان روی سرورها راه می‌اندازد: سرور را اضافه کنید، کلید میزبانش را تأیید کنید و راه‌اندازی کنید. تا آن زمان از دستورهای docker run همین صفحه استفاده کنید.

مدیریت کانتینرها از کنسول#

در کنسول ابرووا، ابرووا تریس › Logs را باز کنید. پنل منبع‌ها همه‌ی سرورها و کانتینرهایشان را فهرست می‌کند؛ منوی کنار هر کانتینر این گزینه‌ها را دارد:

مشاهدهٔ آمار — پنجره‌ای زنده با درصد CPU، حافظه‌ی مصرفی / سقف حافظه و درصد حافظه، و RX / TX شبکه (بایت‌های دریافتی و ارسالی روی همه‌ی رابط‌های شبکه)
شروع — اجرای یک کانتینر متوقف
restart — راه‌اندازی دوباره در همان جا
توقف — توقف آرام یک کانتینر در حال اجرا
حذف — توقف و حذف کانتینر

دستورها از طریق ابرووا تریس به WebSocket ایجنت می‌رسند، پس فرقی نمی‌کند کانتینر روی سرور اصلی باشد یا روی سروری با ایجنت راه دور.

برای start، stop، restart و حذف، نقش admin یا owner لازم است؛ همه‌ی نقش‌ها می‌توانند کانتینرها، لاگ‌ها و آمار را ببینند. نقش‌ها و دسترسی‌ها را ببینید.

مرجع پیکربندی#

متغیرهای محیطی collector

گزینه	نوع	اجباری	توضیح
ABROVA_TRACE_API_KEY	string	بله	کلید سرور پروژه (ab_srv_...، پیشنهادی). کلید اپ (ab_live_...) فقط تا وقتی تنظیم «Server routes require the server secret» خاموش است کار می‌کند
ABROVA_TRACE_URL	string	خیر	آدرس API ابرووا تریس (پیش‌فرض: https://trace.abrova.ir)
ABROVA_TRACE_EXCLUDE	string	خیر	نام کانتینرهایی که کنار گذاشته می‌شوند، جداشده با کاما (پیش‌فرض: abrova-trace-agent)
ABROVA_TRACE_INCLUDE	string	خیر	نام کانتینرهایی که زیر نظر گرفته می‌شوند، جداشده با کاما (خالی = همه)
ABROVA_TRACE_LABEL_FILTER	string	خیر	فقط کانتینرهایی با این label زیر نظر گرفته می‌شوند (مثلاً abrova-trace.project=abc123)؛ بر include/exclude اولویت دارد
ABROVA_TRACE_REMOTE_AGENTS	string	خیر	ایجنت‌های راه دور با قالب name:host:port، جداشده با کاما
ABROVA_TRACE_HOSTNAME	string	خیر	نامی که این سرور با آن نمایش داده می‌شود (پیش‌فرض: نام میزبان Docker)

متغیرهای محیطی ایجنت راه دور

گزینه	نوع	اجباری	توضیح
ABROVA_TRACE_AGENT_PORT	number	خیر	پورت WebSocket ایجنت (پیش‌فرض: 7008)
ABROVA_TRACE_HOSTNAME	string	خیر	نامی که این سرور با آن نمایش داده می‌شود (پیش‌فرض: نام میزبان سیستم)
ABROVA_TRACE_EXCLUDE	string	خیر	نام کانتینرهایی که کنار گذاشته می‌شوند، جداشده با کاما (پیش‌فرض: abrova-trace-agent)
ABROVA_TRACE_INCLUDE	string	خیر	نام کانتینرهایی که زیر نظر گرفته می‌شوند، جداشده با کاما (خالی = همه)
ABROVA_TRACE_LABEL_FILTER	string	خیر	فقط کانتینرهایی با این label زیر نظر گرفته می‌شوند

پردازش لاگ (همه‌ی حالت‌ها)

گزینه	نوع	اجباری	توضیح
ABROVA_TRACE_MULTILINE	boolean	خیر	stack traceها و خروجی چندخطی در یک ورودی یکی می‌شوند (پیش‌فرض: true)
ABROVA_TRACE_REDACT	boolean	خیر	پوشاندن اطلاعات محرمانه: توکن‌ها، رمزهای عبور، کلیدهای API و اطلاعات ورود داخل URLها (پیش‌فرض: true)
ABROVA_TRACE_REDACT_PII	boolean	خیر	پوشاندن آدرس‌های ایمیل و شماره‌تلفن‌ها (پیش‌فرض: true)
ABROVA_TRACE_HEALTH_SAMPLE	number	خیر	از هر N خط health check موفق یکی نگه داشته می‌شود؛ 1 = همه، 0 = هیچ‌کدام (پیش‌فرض: 20)
ABROVA_TRACE_DROP	string	خیر	عبارت‌های منظم که با \|\| جدا می‌شوند؛ ورودی‌های منطبق فرستاده نمی‌شوند
ABROVA_TRACE_DATA_DIR	string	خیر	بافر دیسک و موقعیت‌های خوانده‌شده (پیش‌فرض: /var/lib/abrova-trace-agent؛ برای نگه داشتنشان یک volume وصل کنید)
ABROVA_TRACE_SPOOL_MB	number	خیر	سقف بافر دیسک به مگابایت؛ بیش از آن، قدیمی‌ترین دسته‌های ارسال‌نشده دور ریخته می‌شوند (پیش‌فرض: 50)
ABROVA_TRACE_CATCHUP_SECONDS	number	خیر	پس از راه‌اندازی دوباره، اگر آخرین خط خوانده‌شده تا این حد تازه باشد، ادامه از همان‌جا (پیش‌فرض: 900)

تشخیص سطح لاگ#

ایجنت برای هر ورودی یک سطح تعیین می‌کند تا فیلترهای سطح در کنسول بدون تغییر کد کار کنند:

نشانه‌های صریح مقدم‌اند — [ERROR]، ERROR:، level=warn، [debug] و موارد مشابه در ابتدای خط، همان سطحی را می‌گیرند که نوشته شده. critical و panic fatal حساب می‌شوند، notice info و verbose trace.
لاگ‌های JSON — فیلد level، severity، lvl یا loglevel استفاده می‌شود، از جمله سطح‌های عددی pino و bunyan.
خط‌های NestJS ([Nest] PID - TIMESTAMP LEVEL ...) سطحی را می‌گیرند که NestJS چاپ کرده.
در غیر این صورت، کلیدواژه‌ها — fatal یا panic ← fatal؛ error، exception، failed، unhandled، uncaught، ECONNREFUSED، ETIMEDOUT ← error؛ warn، warning، deprecated ← warn؛ debug، dbg ← debug.
info — پیش‌فرض وقتی هیچ‌کدام منطبق نباشد؛ پس info: 0 errors found همان info می‌ماند.

هر ورودی چه چیزهایی دارد#

هر ورودی لاگ یک رویداد است، نه یک خط. علاوه بر پیام و سطح، فیلدهای اضافه‌ای در metadata دارد:

فیلد	معنا
fingerprint / template	پیام با شناسه‌ها، عددها و تاریخ‌هایی که با جای‌نگهدار جایگزین شده‌اند، و یک hash از آن، تا مشکل‌های یکسان کنار هم گروه شوند
attributes	فیلدهایی که از لاگ‌های JSON، جفت‌های key=value و خط‌های دسترسی HTTP استخراج شده‌اند (method، path، status، durationMs)
traceId	شناسه‌ی درخواست یا trace که در ورودی پیدا شده، برای دنبال کردن یک درخواست در چند کانتینر
lines	تعداد خط‌های خامی که یکی شده‌اند (stack traceها، شیءهای چاپ‌شده)
kind: container_event	یک رویداد چرخه‌ی عمر Docker (start، کد خروج، kill به‌خاطر کمبود حافظه، restart، health check) که در همان خط زمانی نوشته می‌شود
sampled	این خط health check نماینده‌ی N خط است
hostname	میزبان Docker

دسته‌بندی و ارسال#

ارسال دسته‌ای — لاگ‌ها در دسته‌های حداکثر ۱۰۰ ورودی یا هر ۵ ثانیه، هر کدام زودتر برسد، فرستاده می‌شوند.
تلاش دوباره هنگام خطا — دسته‌های ناموفق دوباره در صف قرار می‌گیرند و ارسالشان تکرار می‌شود؛ برای هر منبع تا ۵٬۰۰۰ ورودی در انتظار در حافظه نگه داشته می‌شود (بیش از آن، قدیمی‌ترین‌ها دور ریخته می‌شوند).
بافر دیسک — اگر ابرووا تریس در دسترس نباشد، دسته‌ها در ABROVA_TRACE_DATA_DIR نوشته می‌شوند و وقتی دوباره در دسترس شد به ترتیب ارسال می‌شوند (تا سقف ABROVA_TRACE_SPOOL_MB).
ادامه پس از راه‌اندازی دوباره — ایجنت آخرین خط خوانده‌شده‌ی هر کانتینر را به خاطر می‌سپارد و از همان‌جا ادامه می‌دهد.
خاموش شدن آرام — docker stop abrova-trace-agent پیش از خروج، دسته‌های در انتظار را می‌فرستد.

ویژگی‌های اصلی#

کشف خودکار

کانتینرهای جدید به محض اجرا شناسایی و زیر نظر گرفته می‌شوند

ثبت کانتینرها

همه‌ی کانتینرها (در حال اجرا و متوقف) هنگام شروع در پروژه‌ی شما ثبت می‌شوند

گزارش وضعیت

رویدادهای start، stop، die و kill کانتینرها همان لحظه گزارش می‌شوند

پشتیبانی از چند سرور

کانتینرهای چند سرور را از یک جا مانیتور کنید

اتصال دوباره‌ی خودکار

ارتباط ایجنت‌های راه دور پس از قطع شدن خودش برقرار می‌شود (با ۵ ثانیه تأخیر)

پوشاندن اطلاعات محرمانه

توکن‌ها، رمزهای عبور، کلیدهای API، آدرس‌های ایمیل و شماره‌تلفن‌ها پیش از خروج هر چیزی از سرور پوشانده می‌شوند

مدل امنیتی#

دسترسی به سوکت Docker

ایجنت /var/run/docker.sock را mount می‌کند. پرچم :ro فقط از فایل سوکت محافظت می‌کند، نه از API داکر؛ پس با ایجنت مثل هر کانتینر دیگری که به Docker دسترسی دارد رفتار کنید. ایجنت فقط وقتی روی کانتینرها کاری انجام می‌دهد که دستور start / stop / restart / remove / stats از ابرووا تریس برسد، و ابرووا تریس آن را با اعتبارنامه‌ی پروژه‌ی شما احراز هویت می‌کند.

ایجنت را با کلید سرور اجرا کنید

برای ایجنت از کلید سرور (ab_srv_...) استفاده کنید و «Server routes require the server secret» را در تنظیمات پروژه › محصولات › ابرووا تریس روشن کنید. کلید اپ داخل اپ‌های شما منتشر می‌شود؛ با روشن بودن این تنظیم، دیگر نمی‌توان با آن به‌عنوان ایجنت وصل شد یا کانتینر ثبت کرد.

کلید را بیرون از فایل‌ها نگه دارید

کلید را با متغیر محیطی یا Docker secrets بدهید؛ هرگز آن را مستقیم در فایل compose که commit می‌کنید ننویسید.

مجوز دستورها بر اساس نقش

دستورهای کانتینر را owner یا admin واردشده‌ی پروژه می‌دهد؛ این دستورها از ابرووا تریس می‌گذرند و بعد از طریق WebSocket به ایجنت می‌رسند. ایجنت هرگز از جای دیگری دستور نمی‌پذیرد.

پورت ایجنت راه دور (7008)

فقط باید از collector شما در دسترس باشد. فایروال را طوری تنظیم کنید که فقط آدرس collector بتواند وصل شود.

عیب‌یابی#

کانتینر ایجنت مدام restart می‌شود

لاگ ایجنت را بررسی کنید: docker logs abrova-trace-agent. علت‌های رایج: کلید نامعتبر، در دسترس نبودن آدرس API یا mount نشدن سوکت Docker.

لاگ‌ها می‌رسند، اما کانتینرها دیده نمی‌شوند یا قابل کنترل نیستند

اگر تنظیم پروژه‌ی Server routes require the server secret روشن باشد و ایجنت با کلید اپ اجرا شود، خط‌های لاگ همچنان می‌رسند، اما ایجنت نمی‌تواند کانتینرها را ثبت کند، وضعیتشان را گزارش دهد یا دستور بگیرد. ایجنت را دوباره با مقدار کلید سرور (ab_srv_...) برای ABROVA_TRACE_API_KEY راه‌اندازی کنید. کلید سرور و مسیرهای سرور را ببینید.

کانتینرها در کنسول نمایش داده نمی‌شوند

ایجنت کانتینرها را هنگام شروع ثبت می‌کند. اگر ایجنت را بعد از اجرای کانتینرها اضافه کرده‌اید و هنوز دیده نمی‌شوند، ایجنت را restart کنید: docker restart abrova-trace-agent.

پنجره‌ی آمار صفر نشان می‌دهد یا به‌روز نمی‌شود

آمار از daemon محلی Docker ایجنتی خوانده می‌شود که کانتینر روی آن است. سروری که فقط در حالت agent اجرا می‌شود، لاگ‌هایش را به collector خودش استریم می‌کند؛ اگر آمار کانتینرهای آن خالی می‌ماند، بررسی کنید collector به آن وصل باشد (مورد بعدی را ببینید).

ایجنت راه دور وصل نمی‌شود

مطمئن شوید پورت 7008 از سمت collector در دسترس است، مثلاً ufw allow from COLLECTOR_IP to any port 7008. قالب ABROVA_TRACE_REMOTE_AGENTS را دوباره بررسی کنید: name:host:port، جداشده با کاما.

هیچ لاگی نمایش داده نمی‌شود

بررسی کنید کانتینرهایتان در فهرست کنارگذاشته‌ها (ABROVA_TRACE_EXCLUDE) نباشند و اگر ABROVA_TRACE_INCLUDE / ABROVA_TRACE_LABEL_FILTER را تنظیم کرده‌اید، با آن‌ها منطبق باشند. درست بودن کلید و دسترسی ایجنت به آدرس API را بررسی کنید. لاگ‌ها دسته‌ای فرستاده می‌شوند — تا ۵ ثانیه برای نمایششان صبر کنید.

خطی که لازم دارم وجود ندارد

ABROVA_TRACE_DROP (ورودی‌های منطبق فرستاده نمی‌شوند) و ABROVA_TRACE_HEALTH_SAMPLE را بررسی کنید (به‌طور پیش‌فرض از هر ۲۰ خط health check موفق فقط یکی نگه داشته می‌شود؛ برای نگه داشتن همه، آن را 1 بگذارید).

نحوه‌ی کار#

۱راه‌اندازی روی یک سرور#

۲راه‌اندازی چند سرور#

ایجنت راه دور (روی هر سرور اضافه)

collector (روی سرور اصلی)

۳مدیریت کانتینرها از کنسول#

۴مرجع پیکربندی#

متغیرهای محیطی collector

متغیرهای محیطی ایجنت راه دور

پردازش لاگ (همه‌ی حالت‌ها)

۵تشخیص سطح لاگ#

۶هر ورودی چه چیزهایی دارد#

۷دسته‌بندی و ارسال#

ویژگی‌های اصلی#

مدل امنیتی#

عیب‌یابی#

راه‌اندازی روی یک سرور#

راه‌اندازی چند سرور#

مدیریت کانتینرها از کنسول#

مرجع پیکربندی#

تشخیص سطح لاگ#

هر ورودی چه چیزهایی دارد#

دسته‌بندی و ارسال#