Superlog কীভাবে নিজের সার্ভারে সেটআপ করবেন

Superlog self-hosting-এ আসলে যা ইনস্টল হয়

Superlog self-host করার জন্য আপনাকে প্রথমে রিপোজিটরি ক্লোন করতে হবে। এরপর Docker Compose ব্যবহার করে Postgres, ClickHouse এবং একটি OpenTelemetry collector চালু করতে হবে। একটি ডাটাবেস মাইগ্রেশন চালানোর পর সোর্স থেকে চারটি Node সার্ভিস শুরু করতে হবে। আপনার অ্যাপ্লিকেশনগুলো OTLP (OpenTelemetry protocol) ট্রেস, লগ এবং মেট্রিক একটি ইনটেক পোর্টে পাঠাবে। Superlog সেগুলোকে ফিঙ্গারপ্রিন্ট করবে, পুনরাবৃত্তিমূলক ডেটাগুলোকে একটি ইনসিডেন্টে গ্রুপ করবে এবং একটি এজেন্ট ট্রায়াজের প্রাথমিক ধাপটি সম্পন্ন করবে। এই ইনস্টলেশন প্রক্রিয়াটি সম্পন্ন করতে সাধারণত এক বিকেল সময় লাগে। কাজ শুরু করার আগে এর ফুটপ্রিন্ট এবং সীমাবদ্ধতাগুলো জেনে নেওয়া জরুরি।

Superlog-এর লাইসেন্স Apache 2.0 এবং এটি github.com/superloglabs/superlog-এ পাওয়া যায়। আগস্ট 2026 পর্যন্ত এতে প্রায় 1.2 হাজার স্টার, main-এ প্রায় 460টি কমিট রয়েছে এবং কোনো রিলিজ ট্যাগ নেই। এই শেষ পয়েন্টটি ইনস্টলেশন প্রক্রিয়াকে প্রভাবিত করে: git checkout v1.0.0-এ চেক আউট করার মতো কিছু নেই, তাই আপনাকে নিজে একটি কমিট পিন করতে হবে অথবা ক্লোন করার দিন main-এ যে অবস্থা ছিল, সেটিই চালাতে হবে।

Uptime Kuma এবং Langfuse যা উত্তর দিতে পারে না, Superlog তা কীভাবে দেয়

বাইরে থেকে self-hosted মনিটরিং টুলগুলোকে একই রকম মনে হতে পারে। কিন্তু বাস্তবে সেগুলো এক নয়, এবং ভুল টুল ব্যবহার করলে কোনো লাভ ছাড়াই সার্ভারের রিসোর্স নষ্ট হয়।

• Uptime Kuma আপনার এন্ডপয়েন্টগুলোকে বাইরে থেকে পরীক্ষা করে এবং একটি প্রশ্নের উত্তর দেয়: সার্ভিসটি কি সচল আছে?
• Zabbix আপনার Ubuntu 24.04-এর হোস্ট এবং সার্ভিসগুলো পর্যবেক্ষণ করে, যেখানে আপনি সেট করা থ্রেশহোল্ড অনুযায়ী CPU, মেমোরি, ডিস্ক এবং সার্ভিসের অবস্থা যাচাই করা হয়।
• Langfuse এলএলএম (LLM) কলগুলো ট্র্যাক করে, প্রতিটি কলের প্রম্পট, মডেল, টোকেন, ল্যাটেন্সি এবং খরচ রেকর্ড করে।
• Superlog আপনার সাধারণ সার্ভিসগুলো থেকে নির্গত টেলিমেট্রি সংগ্রহ করে এবং বারবার ঘটা ব্যর্থতাগুলোকে ইনসিডেন্ট হিসেবে চিহ্নিত করে।

Superlog সম্পূর্ণ ভিন্ন একটি প্রশ্নের উত্তর দেয়: কিছু একটা ভেঙেছে, কী ভেঙেছে এবং কেন ভেঙেছে। এলএলএম কল নিয়ে এর কোনো কাজ নেই এবং এটি বাইরে থেকে আপনার সার্ভিসকে প্রোব করে না। এটি আপনার সাধারণ অ্যাপ্লিকেশন কোড থেকে OTLP গ্রহণ করে এবং ট্রায়াজ (triage) ধাপে একটি এজেন্ট বসায়, যা একজন অন-কল ইঞ্জিনিয়ার সাধারণত প্রথম ধাপে করে থাকেন।

একটি ভিপিএস (VPS) বাজেটের ক্ষেত্রে গুরুত্বপূর্ণ পার্থক্য হলো স্টোরেজ। Uptime Kuma 1 জিবি র‍্যামেই ভালোভাবে চলে, কারণ এটি মাত্র কয়েক হাজার চেক রেজাল্ট জমা রাখে। Superlog-এ একটি কলাম স্টোর থাকে, কারণ টেলিমেট্রি একবার লেখা হয় এবং পরবর্তীতে লক্ষ লক্ষ রো (row) থেকে সময়সীমা অনুযায়ী কোয়েরি করা হয়। ClickHouse ঠিক এই কাজের জন্যই তৈরি, যা Postgres নয়। Postgres এখানে ছোট রিলেশনাল ডেটা যেমন—প্রজেক্ট, ইউজার, ইনসিডেন্ট এবং ইনজেস্ট কি (ingest keys) ধরে রাখার জন্য ব্যবহৃত হয়।

docker compose up -d আসলে কী কী চালু করে?

তিনটি কন্টেইনার চালু হয়, যার কোনোটিই Superlog নয়। যারা একটি কমান্ডেই সব ইনস্টল হয়ে যাবে বলে আশা করেন, তাদের জন্য এটি আশ্চর্যজনক হতে পারে।

• postgres:16, যা host port 5434-এ প্রকাশিত।
• clickhouse/clickhouse-server:26.1, HTTP-এর জন্য 8123 এবং native protocol-এর জন্য 9000 পোর্টে।
• otel/opentelemetry-collector-contrib:0.150.1, gRPC-এর জন্য 4317 এবং OTLP over HTTP-এর জন্য 4318 পোর্টে।

Superlog অ্যাপ্লিকেশনগুলো host-এ সোর্স থেকে চলে, যা pnpm dev দ্বারা শুরু হয়। আগস্ট 2026 পর্যন্ত রিপোজিটরিতে কোনো production compose ফাইল নেই, তাই দীর্ঘমেয়াদী ইনস্টলেশনের জন্য প্রতিটি অ্যাপের start স্ক্রিপ্টের চারপাশে আপনার নিজের systemd ইউনিট তৈরি করতে হবে, অথবা ট্রিতে থাকা প্রতি-অ্যাপ Dockerfile ব্যবহার করতে হবে।

একটি span যে পথ অনুসরণ করে তা মনে রাখুন, কারণ নিচে উল্লিখিত প্রতিটি ব্যর্থতা সেই পথের কোনো একটি ধাপে বিচ্ছিন্নতার কারণে ঘটে। আপনার অ্যাপ Superlog intake proxy-তে OTLP পাঠায়। প্রক্সি আপনার ingest key দিয়ে অনুরোধটি যাচাই করে, তাতে project id যুক্ত করে এবং collector-এর কাছে পাঠিয়ে দেয়। collector ক্লায়েন্টের সেট করা যেকোনো superlog.* অ্যাট্রিবিউট সরিয়ে ফেলে, প্রক্সি থেকে পাওয়া হেডার থেকে superlog.project_id যুক্ত করে, ব্যাচ তৈরি করে এবং ClickHouse-এ লেখে। এরপর web app এবং API ClickHouse থেকে টেলিমেট্রি এবং Postgres থেকে অন্যান্য তথ্য পড়ে।

এই অ্যাট্রিবিউট সরিয়ে ফেলা কেবল সাজসজ্জা নয়, এটি একটি প্রকৃত multi-tenancy নিয়ন্ত্রণ। এটি ছাড়া, একটি বৈধ ingest key-এর অধিকারী যেকোনো ব্যক্তি নিজেই superlog.project_id সেট করে অন্য কোনো প্রজেক্টের ডেটাতে লিখতে পারত।

VPS-এর আকার কত বড় হওয়া প্রয়োজন?

কম ইনজেস্ট ভলিউমে সিঙ্গেল নোড ইনস্টলেশনের জন্য 4টি vCPU, 8 জিবি র‍্যাম এবং 40 জিবি SSD-এর পরিকল্পনা করুন। এটি একটি প্রাথমিক মাপকাঠি, কোনো চূড়ান্ত পরিমাপ নয়; তাই এটিকে শুরুর আকার হিসেবে বিবেচনা করুন এবং আপনার নিজস্ব ট্রাফিকের সাথে মিলিয়ে যাচাই করুন।

মেমোরি চারটি জায়গায় ব্যবহৃত হয়। ClickHouse প্রচুর র‍্যাম আছে এমন মেশিনের জন্য তৈরি এবং এর ডিফল্ট সেটিংস সেই অনুযায়ী করা। Postgres 16 এখানে খুব সামান্য মেমোরি ব্যবহার করে, কারণ এটি টেলিমেট্রির পরিবর্তে মেটাডেটা ধরে রাখে। কালেক্টরও খুব সামান্য মেমোরি ব্যবহার করে। তবে চারটি Node প্রসেস তা নয়: একটি Vite ডেভেলপমেন্ট সার্ভার এবং তিনটি tsx watch প্রসেস প্রত্যেকে শত শত মেগাবাইট মেমোরি দখল করে রাখে, যে কারণে 2 জিবি র‍্যামের বক্সে pnpm dev চালানো কষ্টসাধ্য।

ডিস্কের বিষয়টি তুলনামূলক কম আলোচিত সমস্যা। এই মনোরেপোতে pnpm install চালানোর সময় একটি স্প্যান ইনজেস্ট করার আগেই AWS SDK, একটি ClickHouse ক্লায়েন্ট, OpenTelemetry SDK এবং একটি React টুলচেইন ডাউনলোড হয়। এরপর আপনার ট্রাফিকের সাথে ClickHouse-এর আকার বাড়তে থাকে। উভয়ই পরিমাপ করুন:

df -h /
free -m
docker stats --no-stream
docker compose exec clickhouse clickhouse-client --database superlog --query "SELECT table, formatReadableSize(sum(bytes_on_disk)) AS size FROM system.parts WHERE active AND database = 'superlog' GROUP BY table ORDER BY sum(bytes_on_disk) DESC"

কম ভলিউমে, অর্থাৎ যখন অল্প কিছু সার্ভিস প্রতি মিনিটে কয়েকশ স্প্যান পাঠায়, তখন বক্সটি শান্ত থাকে এবং ClickHouse বেশিরভাগ সময় অলস থাকে। যে লোডটি সমস্যা তৈরি করে তা হলো বার্স্ট (burst): একটি ভুল ডেপ্লয়মেন্টের কারণে প্রতি মিনিটে হাজার হাজার একই ধরনের এরর তৈরি হওয়া। ফিঙ্গারপ্রিন্টিং (fingerprinting) সেগুলোকে পাঠকের জন্য একটি ইনসিডেন্টে রূপান্তর করে, কিন্তু ClickHouse তবুও প্রতিটি রো (row) নিচে লিখে রাখে।

রিটেনশন বা ডেটা ধরে রাখার সময়সীমা আপনার নির্ধারণ করতে হবে। কালেক্টরের ClickHouse এক্সপোর্টার টেবিলগুলো তৈরি করে, যেমন otel_traces, otel_logs এবং প্রতিটি মেট্রিক টাইপের জন্য একটি করে টেবিল। এটি কেবল তখনই টাইম-টু-লিভ (TTL) প্রয়োগ করে যদি infra/collector/config.yaml-এর কনফিগারেশনে তা সেট করা থাকে। নিজে থেকে কোনো ডেটা মুছে যায় না, তাই আপনি যদি পরিকল্পনা না করেন তবে একটি ব্যস্ত মাস শেষে ডিস্ক পূর্ণ হয়ে যাবে।

একটি নির্দিষ্ট commit থেকে ইনস্টল করা

git clone https://github.com/superloglabs/superlog.git
cd superlog
git tag -l
git log -1 --format='%H %cs %s'

git tag -l কোনো আউটপুট না দেখানোই 2026 সালের আগস্ট মাস অনুযায়ী প্রত্যাশিত ফলাফল। আপনি যে commit-টি পরীক্ষা করেছেন সেটি বেছে নিন এবং সেই commit-এই থাকুন:

git checkout 0d3a6c8bb63eda3493e6ba0003e7c2a70750bc1e

এরপর, টুলচেইন:

node -v
corepack enable
corepack prepare pnpm@9.12.0 --activate
pnpm -v

package.json ঘোষণা করে যে engines.node হলো >=20.0.0 এবং packageManager হলো pnpm@9.12.0। পুরনো Node ভার্সনে ইনস্টল করার চেষ্টা করলে pnpm ERR_PNPM_UNSUPPORTED_ENGINE দিয়ে থেমে যাবে এবং প্রয়োজনীয় ভার্সনটির নাম উল্লেখ করবে। Ubuntu 24.04 আর্কাইভের nodejs প্যাকেজটি 20-এর চেয়ে পুরনো, তাই NodeSource বা nvm থেকে Node 20 বা তার চেয়ে নতুন ভার্সন ইনস্টল করুন। রিপোজিটরিতে একটি .nvmrc থাকে, তাই আপনার কাছে nvm থাকলে nvm use স্বয়ংক্রিয়ভাবে কাঙ্ক্ষিত ভার্সনটি বেছে নেয়।

pnpm install
docker compose up -d
docker compose ps

up -d মানেই সার্ভিসটি প্রস্তুত—এমনটা ধরে না নিয়ে বরং হেলথ চেক সম্পন্ন হওয়ার জন্য অপেক্ষা করুন। Postgres এবং ClickHouse উভয়ই compose ফাইলে হেলথ চেক ঘোষণা করে:

curl -sS http://127.0.0.1:8123/ping
pg_isready -h 127.0.0.1 -p 5434 -U postgres

ClickHouse Ok. উত্তর দেয় এবং pg_isready accepting connections উত্তর দেয়। 8123 পোর্টে connection refused আসার অর্থ হলো কন্টেইনারটি এখনো চালু হচ্ছে অথবা বন্ধ হয়ে গেছে। docker compose logs clickhouse কমান্ডটি এর কারণ দেখাবে এবং docker inspect $(docker compose ps -q clickhouse) | grep -i oomkilled রিপোর্ট করবে true, যদি মেমোরির অভাবে কার্নেল সেটিকে বন্ধ করে দেয়। এটি নির্দেশ করে যে আপনার কনফিগারেশনে সমস্যা নেই, বরং সার্ভারের রিসোর্স কম।

এরপর মাইগ্রেশন এবং অ্যাপ্লিকেশনগুলো:

pnpm --filter @superlog/db db:migrate
pnpm dev

পোর্টটি খেয়াল করুন: 5432 নয়, 5434। compose ফাইলে Postgres-কে 5434 পোর্টে পাবলিশ করা হয়েছে যাতে এটি হোস্ট মেশিনে আগে থেকে থাকা Postgres-এর সাথে সংঘর্ষ না ঘটায়। অ্যাপের .env.example ফাইলগুলো DATABASE_URL=postgres://postgres:postgres@localhost:5434/superlog-এর সাথে সামঞ্জস্যপূর্ণ। যদি আপনি আগে থেকে Postgres চলছে এমন কোনো মেশিনে 5432 পোর্টে মাইগ্রেশন পয়েন্ট করেন, তবে আপনি হয় connection refused পাবেন, অথবা ভুল ডাটাবেসে মাইগ্রেশন প্রয়োগ হয়ে যাবে।

pnpm dev রিপোজিটরির Procfile-এ তালিকাভুক্ত চারটি প্রসেস শুরু করে: api, web, worker এবং proxy। প্রতিটি প্রসেস তার আউটপুট tmp/logs/-এ পাঠায়, তাই ইনজেস্ট মনিটর করার জন্য tail -f tmp/logs/proxy.log দেখুন। README অনুযায়ী ওয়েব অ্যাপটি http://localhost:5173-এ, API http://localhost:4100-এ এবং OTLP ইনটেক http://localhost:4101-এ থাকে।

কোন পোর্টে সার্ভিসগুলো বাইন্ড হয়েছে তা নিশ্চিত করুন:

ss -lntp | grep -E '4100|4101|5173'
curl -sS http://127.0.0.1:4101/health

এটি পরবর্তীতে গুরুত্বপূর্ণ। প্রক্সি তার নিজস্ব পোর্ট PORT এনভায়রনমেন্ট ভেরিয়েবল থেকে পড়ে এবং PORT সেট করা না থাকলে ডিফল্ট হিসেবে 4000 পোর্ট ব্যবহার করে। ডেভেলপমেন্ট স্ট্যাক এটি আপনার জন্য সেট করে দেয়। আপনি নিজে কোনো systemd ইউনিট লিখলে তা স্বয়ংক্রিয়ভাবে সেট হবে না। ফলে 4000 পোর্টে লিসেন করা প্রক্সির বিপরীতে 4101 পোর্টে কোনো এক্সপোর্টার পয়েন্ট করলে তা connection refused দেখাবে এবং অন্য কোনো সংকেত দেবে না।

একটি ট্রেস পাঠান, একটি এরর তৈরি করুন, একটি ইনসিডেন্ট দেখুন

ওয়েব অ্যাপে একটি প্রজেক্ট তৈরি করুন এবং এর ingest key কপি করুন। ইনটেক (intake) প্রতিটি রিকোয়েস্ট এই কী-এর বিপরীতে যাচাই করে, তাই কোনো কী ছাড়া পাঠানো টেলিমেট্রি কখনোই ClickHouse-এ পৌঁছাবে না।

স্ট্যান্ডার্ড এনভায়রনমেন্ট ভেরিয়েবল ব্যবহার করে যেকোনো OpenTelemetry SDK-কে ইনটেকের দিকে নির্দেশ করুন:

export OTEL_SERVICE_NAME=checkout-api
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4101
export OTEL_EXPORTER_OTLP_HEADERS='x-api-key=YOUR_INGEST_KEY'

ইনটেক x-api-key হেডার থেকে কী-টি পড়ে। আপনার এক্সপোর্টার কনফিগার করা সহজ হলে এটি authorization: bearer YOUR_INGEST_KEY-ও গ্রহণ করে। এটি তিনটি স্ট্যান্ডার্ড OTLP পাথ, /v1/traces, /v1/logs এবং /v1/metrics, এবং সেই সাথে /health-এ সার্ভিস প্রদান করে।

একটি সাধারণ ভুল উল্লেখ করা প্রয়োজন। OTEL_EXPORTER_OTLP_ENDPOINT হলো একটি বেস URL এবং SDK এর সাথে সিগন্যাল পাথ যুক্ত করে দেয়। OTEL_EXPORTER_OTLP_TRACES_ENDPOINT-এর মতো সিগন্যাল-নির্দিষ্ট ভেরিয়েবলগুলো হুবহু যেভাবে লেখা আছে সেভাবেই ব্যবহৃত হয়, এর সাথে কোনো পাথ যুক্ত হয় না। সিগন্যাল-নির্দিষ্ট ভেরিয়েবলটিকে http://127.0.0.1:4101-এ সেট করলে প্রতিটি এক্সপোর্ট /-এ পোস্ট হবে, যা কোনো রুট নয়। ফলে কিছুই পৌঁছাবে না এবং আপনার অ্যাপ সুস্থ দেখালেও SDK একটি এক্সপোর্ট ফেইলিয়র লগ করবে।

Node সার্ভিসের ক্ষেত্রে পাইপলাইন যাচাই করার জন্য জিরো-কোড পাথই যথেষ্ট:

npm install @opentelemetry/api @opentelemetry/auto-instrumentations-node
node --require @opentelemetry/auto-instrumentations-node/register server.js

এখন ইচ্ছাকৃতভাবে কিছু ভেঙে ফেলুন। যেকোনো রুট যা এরর থ্রো করে তা-ই কাজ করবে:

curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3000/boom

হপগুলো ক্রমানুসারে পরীক্ষা করুন, কারণ প্রথম গ্যাপটিই আপনাকে বলে দেবে কোনটি ব্যর্থ হয়েছে:

tail -n 50 tmp/logs/proxy.log
docker compose exec clickhouse clickhouse-client --database superlog --query 'SELECT count() FROM otel_traces'

ওয়েব অ্যাপ খালি থাকা অবস্থায় otel_traces-এ কাউন্ট বাড়তে থাকলে বুঝতে হবে প্রজেক্টের অমিল রয়েছে, তাই ingest key কোন প্রজেক্টের তা যাচাই করুন। প্রক্সি লগে অ্যাক্টিভিটি থাকা সত্ত্বেও কাউন্ট স্থির থাকলে সমস্যাটি কালেক্টর বা ClickHouse রাইটে হতে পারে, তাই docker compose logs collector পড়ুন। প্রক্সি লগে কোনো অ্যাক্টিভিটি না থাকলে বুঝতে হবে এক্সপোর্টার কখনোই ইনটেকে পৌঁছাতে পারেনি: ভুল পোর্ট, ভুল পাথ বা প্রত্যাখ্যাত কী এর কারণ হতে পারে।

ওয়েব অ্যাপে এই পুনরাবৃত্ত ব্যর্থতাগুলো প্রতি রিকোয়েস্টের জন্য আলাদা সারি না হয়ে একটি ইনসিডেন্ট হিসেবে জমা হয়। Superlog ইনকামিং সিগন্যালগুলোর ফিঙ্গারপ্রিন্ট তৈরি করে এবং মিল থাকা সিগন্যালগুলোকে গ্রুপ করে। এটিই ইনবক্সে 4,000 অভিন্ন এরর থাকা এবং একটি পেজে একটি ইনসিডেন্ট থাকার মধ্যে পার্থক্য। এরপর এজেন্ট সেই গ্রুপের ওপর ভিত্তি করে তার তদন্ত প্রতিবেদন লেখে।

তদন্তের ধাপটি একটি মডেল কল করে, তাই ওয়ার্কারের জন্য একটি মডেল প্রোভাইডার কনফিগার করা প্রয়োজন। এই ভেরিয়েবলগুলোর নাম কোনো এক্সটারনাল ডকুমেন্ট থেকে না নিয়ে আপনার পিন করা কমিটের প্রতিটি অ্যাপ ডিরেক্টরির ভেতরের .env.example ফাইল থেকে নিন, কারণ এগুলো main-এর সাথে পরিবর্তিত হয়। GitHub এবং Sentry ইন্টিগ্রেশনের ক্ষেত্রেও একই নিয়ম প্রযোজ্য; এদের নিজস্ব সেটআপ ডকুমেন্ট docs/github-app-setup.md এবং docs/sentry-app-setup.md-এ রয়েছে এবং ওয়েবহুক পেলোডগুলো docs/webhooks.md-এ নথিভুক্ত করা আছে।

ইনটেককে ব্যক্তিগত রাখুন এবং এজেন্টকে রিড-অনলি মোডে রাখুন

Docker ডিফল্টভাবে কন্টেইনার পোর্টগুলোকে 0.0.0.0-এ প্রকাশ করে। এই প্রকাশিত পোর্টগুলো ufw-কে বাইপাস করে, কারণ Docker তার নিজস্ব রুলগুলো DOCKER-USER চেইনে লিখে রাখে যা ufw প্যাকেট দেখার আগেই কার্যকর হয়। পাবলিক IP-সহ একটি VPS-এ, সরবরাহকৃত compose ফাইলে ClickHouse HTTP-কে 8123 পোর্টে এবং Postgres-কে 5434 পোর্টে রাখা হয়, যা ইন্টারনেট থেকে অ্যাক্সেসযোগ্য। ঐ ফাইলের ক্রেডেনশিয়ালগুলো ডেভেলপমেন্টের জন্য ডিফল্ট: ClickHouse ইউজার default যার কোনো পাসওয়ার্ড নেই, এবং Postgres-এর ইউজার ও পাসওয়ার্ড উভয়ই postgres।

এগুলোকে লুপব্যাক (loopback)-এ বাইন্ড করুন। compose ফাইলের প্রতিটি প্রকাশিত পোর্ট তার হোস্ট সাইডের জন্য একটি এনভায়রনমেন্ট ভেরিয়েবল ব্যবহার করে, তাই রিপোজিটরির রুটে একটি .env ফাইল থাকাই যথেষ্ট:

POSTGRES_HOST_PORT=127.0.0.1:5434
CLICKHOUSE_HTTP_HOST_PORT=127.0.0.1:8123
CLICKHOUSE_TCP_HOST_PORT=127.0.0.1:9000
COLLECTOR_GRPC_HOST_PORT=127.0.0.1:4317
COLLECTOR_HTTP_HOST_PORT=127.0.0.1:4318

ফলাফলটি বিশ্বাস করার আগে যাচাই করুন, তারপর কন্টেইনারগুলোকে পুনরায় তৈরি করুন:

docker compose config
docker compose up -d
ss -lntp | grep -E '5434|8123|9000|4317|4318'

docker compose config কমান্ডটি রিজলভ করা ফাইলটি প্রিন্ট করে, তাই আপনি অনুমান না করে সরাসরি 127.0.0.1:5434:5432 পড়তে পারেন। ss কমান্ডের আউটপুটে তখন 127.0.0.1:5434 দেখানো উচিত, কখনোই 0.0.0.0:5434 নয়। এটি ঠিক করার জন্য এমন কোনো compose ওভাররাইড ফাইল ব্যবহার করবেন না যা ports-কে পুনরায় ঘোষণা করে, কারণ Compose ফাইলগুলোর মধ্যে পোর্ট লিস্টগুলোকে রিপ্লেস না করে কনক্যাটেনেট (concatenate) করে। ফলে আপনি উভয় বাইন্ডিংই পাবেন এবং পাবলিক পোর্টটি খোলা থেকে যাবে।

ইনটেকের ক্ষেত্রেও একই সতর্কতা প্রয়োজন। আপনার ইনজেস্ট কি (ingest key) একটি হেডারের মাধ্যমে যায়, তাই এর সামনে TLS (transport layer security) থাকা আবশ্যক: প্রক্সির আগে nginx বা Caddy-তে TLS টার্মিনেট করুন, অথবা ইনজেস্টকে একটি প্রাইভেট নেটওয়ার্ক বা WireGuard টানেলের ভেতরে রাখুন। 5173 পোর্টে থাকা ওয়েব অ্যাপটি একটি Vite ডেভেলপমেন্ট সার্ভার, যার ইন্টারনেটের মুখোমুখি হওয়ার কোনো প্রয়োজন নেই।

এরপর এজেন্টের বিষয়টি। Superlog-এর মূল বৈশিষ্ট্য হলো এজেন্ট তদন্ত করে সমাধানের প্রস্তাব দেয়, এবং এখানে গুরুত্বপূর্ণ শব্দটি হলো 'প্রস্তাব'। এজেন্টকে প্রোডাকশনে রিড-অনলি মোডে রাখুন যতক্ষণ না আপনি কয়েকটি বাস্তব ইনসিডেন্টে এর কার্যকারিতা পর্যবেক্ষণ করছেন। GitHub App-কে রিড স্কোপ দিন এবং এটিকে এমন পুল রিকোয়েস্ট ওপেন করতে দিন যা আপনি রিভিউ করবেন। যে এজেন্ট টেলিমেট্রি পড়ে এবং প্যাচ লেখে তা কার্যকর। যে এজেন্ট আপনার সার্ভিস রিস্টার্ট করতে পারে তা ভিন্ন মাত্রার ঝুঁকির সৃষ্টি করে, এবং এটি এমন একটি সিদ্ধান্ত যা আপনার সচেতনভাবে নেওয়া উচিত, ডিফল্ট হিসেবে গ্রহণ করা নয়। খরচের বিষয়টিও সমান মনোযোগের দাবি রাখে, কারণ প্রতিটি তদন্তই একটি মডেল কল: একটি নয়েজি প্রোডাকশন সিস্টেমে এটি ব্যবহার করার আগে VPS-এ এজেন্টের খরচের বাজেট নির্ধারণ করুন এবং এজেন্ট আসলে কী করেছে তার একটি রেকর্ড রাখুন, যাতে কোনো অপ্রত্যাশিত পুল রিকোয়েস্টের পেছনে একটি অডিট ট্রেইল থাকে।

যেসব ব্যর্থতার সম্মুখীন হবেন এবং সেগুলোর নাম নির্দেশকারী স্ট্রিং

• ERR_PNPM_UNSUPPORTED_ENGINE চলাকালীন pnpm install এর অর্থ হলো Node-এর ভার্সন 20-এর চেয়ে পুরনো। node -v কমান্ডটি এক লাইনে এটি নিশ্চিত করে।
• মাইগ্রেশনের সময় ECONNREFUSED 127.0.0.1:5434 এর অর্থ হলো compose stack চালু নেই, অথবা DATABASE_URL ভুল পোর্ট নির্দেশ করছে।
• ClickHouse লুপে রিস্টার্ট হওয়ার কারণ সাধারণত মেমোরি। docker compose logs clickhouse পড়ুন, তারপর কন্টেইনারে OOMKilled এর মান true কি না তা যাচাই করুন।
• কোনো এক্সপোর্টার সফল রিপোর্ট করার পরেও ওয়েব অ্যাপ খালি থাকলে বুঝতে হবে ডেটা সরাসরি 4318 পোর্টে কালেক্টরে চলে গেছে, যা প্রক্সির মাধ্যমে করা প্রজেক্ট স্ট্যাম্পিং প্রক্রিয়াকে এড়িয়ে গেছে।
• প্রোডাকশন ইন্সটলেশনে 4101 পোর্টে Connection refused আসার অর্থ হলো প্রক্সি PORT=4000-এ ফিরে গেছে। ইউনিট ফাইলে স্পষ্টভাবে PORT সেট করুন।
• docker compose ps এ 0.0.0.0:8123 দেখালে বুঝতে হবে আপনার লুপব্যাক বাইন্ডিং কার্যকর হয়নি। docker compose config চালান এবং রেজলভ হওয়া পোর্টগুলো দেখুন।

Flawless, HyperProbe এবং Superlog-এর অবস্থান

এই বিভাগটি নতুন এবং এজেন্ট কী কী পরিবর্তন করতে পারবে, তা নিয়ে টুলগুলোর মধ্যে ভিন্নমত রয়েছে। Flawless হলো একটি ওপেন সোর্স AI SRE (site reliability engineering) টুল যা Kubernetes-এর জন্য তৈরি। এটি সরাসরি পাইপলাইনের নিয়ন্ত্রণ না নিয়ে বিদ্যমান Prometheus, Loki এবং Grafana স্ট্যাক থেকে তথ্য সংগ্রহ করে। HyperProbe ভিন্ন পথে চলে: এটি একটি হোস্ট করা পণ্য (আগস্ট 2026 পর্যন্ত ক্লোজড সোর্স), যা চলমান প্রসেসের ভেতরে রিড-অনলি প্রোব স্থাপন করে ভেরিয়েবল স্টেট ক্যাপচার করে এবং MCP (model context protocol)-এর মাধ্যমে সেই স্টেট একটি অ্যাসিস্ট্যান্টের কাছে পৌঁছে দেয়।

Superlog এই দুটির মাঝামাঝি অবস্থানে রয়েছে। এটি OTLP ইনটেক থেকে শুরু করে ClickHouse স্টোরেজ পর্যন্ত পুরো পাইপলাইনটি নিয়ন্ত্রণ করে এবং এজেন্টকে সমস্যার সমাধানের পরিবর্তে ট্রায়াজ (triage) ধাপে স্থাপন করে। এই ডিজাইনের কারণেই এটিকে সেলফ-হোস্ট করা একটি অবকাঠামোগত সিদ্ধান্ত, এটি এমন কোনো কন্টেইনার নয় যা একবার চালু করে ভুলে যাওয়া যায়। আপনি যখন Superlog চালাবেন, তখন আপনি মূলত একটি কলাম স্টোর (column store) চালাচ্ছেন, এবং আপনার মালিকানাধীন অন্য যেকোনো ডাটাবেসের মতোই এটির রক্ষণাবেক্ষণ প্রয়োজন।

FAQ

একটি self-hosted Superlog-এর জন্য কতটুকু RAM প্রয়োজন?

কম ingest ভলিউমের একটি সিঙ্গেল নোডের জন্য 8 GB RAM, 4 vCPU এবং 40 GB ডিস্কের পরিকল্পনা করুন। এই স্ট্যাকটিতে Postgres, ClickHouse, একটি OpenTelemetry collector এবং চারটি Node প্রসেস থাকে, এবং ClickHouse-এর জন্য পর্যাপ্ত headroom প্রয়োজন। 1 GB বা 2 GB-এর VPS যথেষ্ট নয়: pnpm install নিজেই বেশ ভারী, এবং লোড বাড়লে ClickHouse-কে kernel-এর out of memory killer বন্ধ করে দেয়। কোনো প্রকাশিত তথ্যের ওপর নির্ভর না করে docker stats --no-stream এবং free -m ব্যবহার করে আপনার নিজস্ব প্রয়োজনীয়তা পরিমাপ করুন।

আমার OTLP exporter-কে কোন পোর্টে পয়েন্ট করব?

Superlog intake proxy-তে, যা README অনুযায়ী http://localhost:4101-এ থাকে। এটি /v1/traces, /v1/logs এবং /v1/metrics পরিবেশন করে এবং এটি আপনার প্রজেক্টের ingest key দিয়ে authenticate করে, যা x-api-key হেডার অথবা authorization: bearer হেডার থেকে নেওয়া হয়। পোর্ট 4318 হলো এর নিচের OpenTelemetry collector, এবং সরাসরি সেখানে export করলে proxy-কে এড়িয়ে যাওয়া হয়, অথচ এই proxy-ই আপনার ডেটাতে প্রজেক্ট আইডি যুক্ত করে। PORT সেট করা না থাকলে proxy ডিফল্টভাবে 4000 পোর্টে ফিরে যায়, তাই 4101 ধরে নেওয়ার আগে ss -lntp চালিয়ে নিশ্চিত হয়ে নিন এটি কোন পোর্টে bind হয়েছে।

Superlog কি Uptime Kuma বা Zabbix-এর বিকল্প?

না। Uptime Kuma উত্তর দেয় আপনার নেটওয়ার্কের বাইরে থেকে কোনো endpoint সাড়া দিচ্ছে কি না, এবং Zabbix আপনার সেট করা threshold অনুযায়ী হোস্ট ও সার্ভিসের মেট্রিক পর্যবেক্ষণ করে। Superlog আপনার অ্যাপ্লিকেশনের পাঠানো trace, log এবং metric গ্রহণ করে এবং বারবার ঘটা ব্যর্থতাগুলোকে incident হিসেবে গ্রুপ করে। এর পাশাপাশি একটি এক্সটারনাল uptime probe রাখুন, কারণ আপনার telemetry pipeline যে সার্ভারে চলছে সেটি মারা গেলেও অন্য কোথাও চলা একটি probe তা রিপোর্ট করতে পারবে।

Superlog agent কি আমার প্রোডাকশন সিস্টেমে পরিবর্তন আনতে পারে?

শুধুমাত্র আপনার দেওয়া অনুমতির মাধ্যমে। এর আউটপুট হলো একটি তদন্ত এবং প্রস্তাবিত পরিবর্তন, যা একজন মানুষ রিভিউ করেন। শুরুতে GitHub App-কে শুধুমাত্র read scope এবং pull request-এর অনুমতি দিন, এবং worker-এর কাছে থাকা credential-গুলোকে শুধুমাত্র পড়ার (read) জন্য সীমাবদ্ধ রাখুন। প্রোডাকশনে write access দেওয়ার বিষয়টি আলাদাভাবে এবং ভেবেচিন্তে সিদ্ধান্ত নিন, কারণ যে agent সার্ভিস রিস্টার্ট করতে পারে তা telemetry পড়া বা প্যাচ তৈরি করা agent-এর চেয়ে অনেক বেশি ঝুঁকিপূর্ণ।

আমি কি একটি নির্দিষ্ট commit পিন করব নাকি main ট্র্যাক করব?

একটি commit পিন করুন। আগস্ট 2026 পর্যন্ত repository-তে কোনো release tag নেই, তাই main হলো একমাত্র চলমান টার্গেট এবং এতে সপ্তাহে বেশ কয়েকটি commit আসে। আপনি যে SHA পরীক্ষা করেছেন তা রেকর্ড করুন, সেটি deploy করুন এবং সামনে এগিয়ে যাওয়ার আগে diff পড়ে নিন। git log --oneline <old-sha>..main হলো রিভিউ, এবং কোনো পরিবর্তনের পর নতুন কোনো variable প্রয়োজন কি না তা দেখার জন্য প্রতি অ্যাপের .env.example ফাইলগুলো সবার আগে চেক করুন।