Log আর config — structured logging, request id আর health check

১ · console.log কোথায় ফুরিয়ে যায়

শুক্রবার সন্ধ্যা। “বাজারঘর”-এ অফার চলছে। একজন ক্রেতা ফেসবুকে লিখলেন, “টাকা কেটেছে, order আসেনি।” আপনি server-এর log খুললেন। সেখানে আছে:

here
order ok
here
Error: failed
order ok
user 42
here

কোন “here” কার? “failed” কোন order-এর? ঘটনা কখন ঘটেছিল? এই লাইনগুলো লেখার সময় আপনার মনে পুরো প্রসঙ্গ ছিল, কিন্তু log-এ সেই প্রসঙ্গ নেই। লেখার মানুষ আর পড়ার মুহূর্তের মধ্যে কয়েক মাসের দূরত্ব থাকতে পারে। console.log ছোট কাজের জন্য ভালো, কিন্তু production-এ তার তিনটি অভাব ধরা পড়ে:

• গঠন নেই। লেখা বাক্য যন্ত্র দিয়ে খোঁজা কঠিন। “৫০০ টাকার বেশি যেসব order ব্যর্থ হয়েছে” এই প্রশ্নের উত্তর এমন log থেকে আসে না।
• গুরুত্বের মাত্রা নেই। সাধারণ খবর আর জরুরি ভুল একই চেহারায় আসে, আর production-এ বাড়তি লাইন বন্ধ করার সহজ উপায় নেই।
• সংযোগ নেই। একসাথে একশো request চললে তাদের লাইন মিশে যায়। কোন লাইন কোন request-এর, বোঝার উপায় থাকে না।

প্রচলিত আকার হলো প্রতি লাইনে একটি JSON object. আর অ্যাপ লেখে শুধু stdout-এ। Log ফাইল ঘোরানো, জমা করা, এক জায়গায় পাঠানো, এসব চালানোর পরিবেশের কাজ। Twelve-Factor App নীতিও log-কে ঘটনার একটি ধারা হিসেবে দেখে, যা অ্যাপ stdout-এ ছেড়ে দেয়।

এবার ৩০ লাইনের কম কোডে নিজেই একটি logger বানিয়ে ভেতরের কৌশলটি দেখুন। সংবেদনশীল key ঢাকার একটি ছোট ব্যবস্থাও এতে আছে। সত্যিকারের সময়ের বদলে এখানে ক্রমিক নম্বর, যাতে আউটপুট প্রতিবার এক থাকে।

const LEVELS = { debug: 20, info: 30, warn: 40, error: 50 };
const SENSITIVE = new Set(["password", "token", "phone", "cardNumber"]);

// JSON.stringify প্রতিটি key-তে, প্রতিটি গভীরতায়, এই ফাংশন ডাকে
function hideSensitive(key, value) {
  return SENSITIVE.has(key) ? "[REDACTED]" : value;
}

function createLogger(minLevel) {
  let seq = 0; // নিশ্চিত আউটপুটের জন্য সময়ের বদলে ক্রমিক নম্বর
  function write(level, fields, msg) {
    if (LEVELS[level] < LEVELS[minLevel]) return;
    const line = { level, seq: ++seq, ...fields, msg };
    console.log(JSON.stringify(line, hideSensitive));
  }
  return {
    debug: (fields, msg) => write("debug", fields, msg),
    info: (fields, msg) => write("info", fields, msg),
    error: (fields, msg) => write("error", fields, msg),
  };
}

const log = createLogger("info");
log.debug({ sql: "SELECT ..." }, "query text");
log.info({ orderId: 42, totalTaka: 1250 }, "order placed");
log.info({ user: { phone: "01700000000", city: "Rajshahi" } }, "signup");
log.error({ orderId: 42, token: "example-token" }, "payment failed");

হিসাব: log-এর আয়তন কত হয়

Level শুধু পরিষ্কার পড়ার জন্য নয়, খরচের জন্যও জরুরি। ধরে নিন, দিনে ২,০০,০০০ request, প্রতিটিতে ৪টি লাইন, প্রতি লাইনে গড়ে ২০০ byte. আমাদের ল্যাবের ২৩টি লাইনের গড় ছিল প্রায় ১৬৪ byte, তবে এটি একটি ছোট লোকাল run; বাস্তবে লাইন বড় হয়।

Health check-ও লাইন বাড়ায়। দুটি load balancer ৫ সেকেন্ড পরপর ডাকলে দিনে 86,400 ÷ 5 × 2 = 34,560টি কল। প্রতিটির একটি লাইন মানে দিনে প্রায় ৬.৯ MB অপ্রয়োজনীয় লেখা। তাই নিচে এদের log থেকে বাদ দেওয়া হয়েছে।

২ · Express 5-এ pino আর pino-http

নিজের logger শেখার জন্য ভালো, কিন্তু production-এ পরীক্ষিত library ব্যবহার করুন। Node.js জগতে pino বহুল ব্যবহৃত, winston-ও অনেক প্রকল্পে চলে। pino-http হলো তার middleware, যা প্রতিটি request শেষে একটি লাইন লেখে। Middleware-এর ক্রম নিয়ে বিস্তারিত আছে পর্ব ২৬-এ।

লেখার সময়ের version: Node 24.15.0, Express 5.3.0, pino 10.4.0, pino-http 11.0.0, Zod 4.6.7. এগুলো বদলায়, তাই নিজের project-এ npm view pino version দিয়ে মিলিয়ে নিন।

npm i express pino pino-http zod prom-client
npm i -D pino-pretty

import pino from 'pino';
import { requestContext } from './context.js';

export function createLogger({ level }) {
  return pino({
    level,
    base: null, // pid আর hostname বাদ
    timestamp: pino.stdTimeFunctions.isoTime,
    formatters: { level: (label) => ({ level: label }) },
    mixin() {
      const store = requestContext.getStore();
      return store ? { requestId: store.requestId } : {};
    },
    redact: {
      paths: [
        'password', '*.password', 'token', '*.token',
        'phone', '*.phone', 'cardNumber', '*.cardNumber',
        'req.headers.authorization', 'req.headers.cookie',
      ],
      censor: '[REDACTED]',
    },
  });
}

লাইনগুলো ছোট করে বুঝি। pino নিজে থেকে প্রতিটি লাইনে pid আর hostname যোগ করে। base: null সেগুলো বাদ দেয়, তাই এই পর্বের সব আউটপুটে এই দুটি নেই। অনেক প্রকল্পে এগুলো রাখাই কাজের, কারণ কয়েকটি server-এর মধ্যে কোনটি থেকে লাইন এলো তা বোঝা যায়। isoTime সময়কে পড়ার মতো করে। formatters.level সংখ্যা 30-এর বদলে info লেখে। mixin প্রতিটি লাইনে একটি বাড়তি field জোড়ে; এর ভূমিকা পরের অংশে।

app.use(pinoHttp({
  logger: log,
  genReqId: (req) => req.id,
  autoLogging: {
    ignore: (req) => ['/healthz', '/readyz', '/metrics'].includes(req.url),
  },
  serializers: {
    req: (r) => ({ method: r.method, url: r.url.split('?')[0] }),
    res: (r) => ({ statusCode: r.statusCode }),
  },
}));

সত্যিকারের run. একটি GET /orders/42-এর শেষে pino-http এই লাইনটি লিখল (Node 24.15.0, ল্যাবের project ~/bazarghar):

{"level":"info","time":"2026-11-01T16:33:40.268Z","req":{"method":"GET","url":"/orders/42"},"requestId":"8e08e93d-e083-4d4c-8662-9c53e882a724","res":{"statusCode":200},"responseTime":25,"msg":"request completed"}

responseTime এখানে মিলিসেকেন্ডে, অর্থাৎ এই একটি লোকাল run-এ ২৫ ms. Development-এ JSON পড়া ক্লান্তিকর হলে আউটপুট pino-pretty-তে পাঠান। Logger কোড বদলায় না, শুধু পড়ার চেহারা বদলায়:

$ node --env-file=.env src/main.js | npx pino-pretty
[22:33:40] INFO: request completed
    req: {
      "method": "GET",
      "url": "/orders/42"
    }
    requestId: "8e08e93d"
    res: {
      "statusCode": 200
    }
    responseTime: 25

৩ · Request id — এক request-এর সব লাইন এক সুতোয়

এখন একসাথে দুটি order দেখা হচ্ছে। Async কোডে এদের লাইন মিশে যায়। পর্ব ২-এ request id-এর ধারণা পেয়েছিলেন (অনুরোধের যাত্রা)। প্রতিটি request-এর জন্য একটি আলাদা পরিচয়, যা তার প্রতিটি log লাইনে থাকবে।

সমস্যা হলো, id-টি repository-এর গভীর ফাংশন পর্যন্ত পৌঁছাবে কীভাবে? প্রতিটি ফাংশনে requestId argument যোগ করলে কোড নোংরা হয়, আর একটি জায়গায় ভুলে গেলেই সুতো ছিঁড়ে যায়। Module-স্তরের একটি সাধারণ variable-ও চলবে না, কারণ একই process-এ অনেক request একসাথে চলে; একটি অন্যটির মান মুছে দেবে।

সমাধান node:async_hooks-এর AsyncLocalStorage. run(store, fn) একটি অদৃশ্য বাক্স খোলে। fn-এর ভেতর থেকে শুরু হওয়া সব async কাজ, await, timer, যাই হোক, getStore() দিয়ে একই বাক্স পায়। Node-এর docs অনুযায়ী এটি v16.4.0 থেকে Stable. নিচের কোডে দুটি request একসাথে চলছে, আর node:http ছাড়া কোনো package নেই।

const http = require("node:http");
const { AsyncLocalStorage } = require("node:async_hooks");
const context = new AsyncLocalStorage();
const wait = (ms) => new Promise((done) => setTimeout(done, ms));
function log(msg) {
  const requestId = context.getStore()?.requestId ?? "none";
  console.log(JSON.stringify({ requestId, msg }));
}
// খেয়াল করুন: এই দুই ফাংশনে requestId কোনো argument হয়ে আসেনি
async function findOrder(id, ms) {
  await wait(ms);
  log(`repository: order ${id} found`);
}
async function getOrder(id, ms) {
  log(`service: loading order ${id}`);
  await findOrder(id, ms);
}
let next = 0;
const server = http.createServer((req, res) => {
  const [, id, ms] = req.url.split("/");
  context.run({ requestId: `req-${++next}` }, async () => {
    await getOrder(id, Number(ms));
    log("response sent");
    res.end("ok");
  });
});

server.listen(0, "127.0.0.1", async () => {
  const url = `http://127.0.0.1:${server.address().port}`;
  const first = fetch(`${url}/42/80`);
  await wait(20);
  await Promise.all([first, fetch(`${url}/7/20`)]);
  log("outside any request");
  server.close();
});

{"requestId":"req-1","msg":"service: loading order 42"}
{"requestId":"req-2","msg":"service: loading order 7"}
{"requestId":"req-2","msg":"repository: order 7 found"}
{"requestId":"req-2","msg":"response sent"}
{"requestId":"req-1","msg":"repository: order 42 found"}
{"requestId":"req-1","msg":"response sent"}
{"requestId":"none","msg":"outside any request"}

Express-এ একই ধারণা একটি middleware হয়ে যায়। এটি সবার আগে বসে, যাতে পরের সব middleware আর route বাক্সের ভেতরে চলে। বাকি কাজ করে আগে দেখা pino mixin: logger প্রতিটি লাইন লেখার সময় নিজেই getStore() ডাকে।

const SAFE_ID = /^[A-Za-z0-9-]{8,64}$/;

app.use((req, res, next) => {
  const incoming = req.get('x-request-id');
  const requestId = incoming && SAFE_ID.test(incoming)
    ? incoming
    : randomUUID();
  req.id = requestId;
  res.setHeader('x-request-id', requestId);
  requestContext.run({ requestId }, next);
});

এখন দেখুন, এই id স্তরগুলো পেরিয়ে কীভাবে যায়। প্রতিটি log লাইন ল্যাবের আসল run থেকে নেওয়া; পড়ার সুবিধায় id ছোট করা হয়েছে। Service আর repository-এর গঠন পর্ব ২৯-এর আলোচ্য।

x-request-id: 8e08e93d…
store = { requestId: "8e08e93d…" }

{"level":"info","requestId":"8e08e93d…",
 "orderId":42,"msg":"loading order"}

{"level":"debug","requestId":"8e08e93d…",
 "table":"orders","found":true,"msg":"query done"}

{"level":"info","requestId":"8e08e93d…",
 "res":{"statusCode":200},"responseTime":25,
 "msg":"request completed"}

$ grep -c . app.log
74
$ grep 8e08e93d app.log | wc -l
3

৪ · কী কখনো log করবেন না

Log সাধারণত database-এর চেয়ে কম সুরক্ষিত থাকে। অনেক মানুষ দেখতে পারেন, অন্য সিস্টেমে কপি হয়, মাসের পর মাস থাকে। তাই যা database-এ hash করে রাখেন, তা log-এ খোলা লিখলে সব সুরক্ষা অর্থহীন। তাত্ত্বিক আলোচনা আছে Cybersecurity কোর্সের Security logging পর্বে; এখানে শুধু হাতের কাজ।

pino-র redact নির্দিষ্ট path-এর মান লেখার আগেই বদলে দেয়। Path-এ * মানে এক স্তরের যেকোনো key. একটি login-এ পুরো body log করে পরীক্ষা করা হলো (ইচ্ছা করেই খারাপ অভ্যাস, নকল মান):

{"level":"info","time":"2026-11-01T16:33:40.370Z","requestId":"65c68c0f-3467-4bc9-9754-bba00c7e4808","body":{"phone":"[REDACTED]","password":"[REDACTED]","profile":{"password":"example-2"}},"msg":"login attempt"}

// ভুল: কী কী আসবে, আপনি জানেন না
log.info({ body: req.body }, 'login attempt');

// ঠিক: নিজের বেছে নেওয়া field
log.info({ userId: user.id, method: 'password' }, 'login succeeded');

এই “বেছে নেওয়া field”-এর নীতিকে allowlist বলা হয়। redact হলো তার পেছনের দ্বিতীয় বেড়া, যদি কেউ ভুল করে। আরেকটি সতর্কতা: pino-র docs অনুযায়ী redact path শুরুতে একবার ঠিক করার জিনিস, ব্যবহারকারীর ইনপুট থেকে কখনো আসবে না। আর wildcard path সরাসরি লেখা path-এর চেয়ে বেশি খরচের।

৫ · Config — কোডে নয়, environment-এ

একই কোড আপনার ল্যাপটপে, test-এ আর production-এ চলে, কিন্তু database আলাদা, port আলাদা, log level আলাদা। যা deploy ভেদে বদলায়, সেটিই config. Twelve-Factor App-এর নীতি: config কোড থেকে কঠোরভাবে আলাদা থাকবে, আর থাকবে environment variable-এ। এর একটি সহজ পরীক্ষাও আছে: কোনো credential ফাঁস না করে এখনই কি codebase প্রকাশ করা যায়?

Vite-এর .env আর VITE_ prefix দেখেছিলেন পর্ব ৫-এ; সেটি browser-এর গল্প। Server-এ .env ফাইল শুধু লোকাল সুবিধার জন্য, আর Node এটি নিজেই পড়তে পারে। --env-file এসেছে v20.6.0-তে, আর docs অনুযায়ী v24.10.0 ও v22.21.0 থেকে এটি আর experimental নয়। ছোট প্রকল্পে এখন dotenv package প্রায়ই লাগে না।

# নকল মান, শুধু লোকাল কাজের জন্য
NODE_ENV=development
PORT=4131
LOG_LEVEL=debug
DATABASE_PATH=./dev.sqlite
SESSION_SECRET=example-secret-not-real-0123456789abcdef

অগ্রাধিকারের নিয়ম সত্যিকারের run-এ যাচাই করা হয়েছে (Node 24.15.0; .env-এ PORT=4131, LOG_LEVEL=debug, আর .env.test-এ LOG_LEVEL=warn):

$ PORT=4140 node --env-file=.env print.js
PORT = 4140 | LOG_LEVEL = debug

$ node --env-file=.env --env-file=.env.test print-level.js
LOG_LEVEL = warn

$ node --env-file=.env.nope src/main.js
node: .env.nope: not found
exit code: 9

$ node --env-file-if-exists=.env.nope src/main.js
.env.nope not found. Continuing without it.

তিনটি নিয়ম বেরিয়ে এলো। Environment-এ আগে থেকে থাকা মান ফাইলের ওপরে জেতে। একাধিক ফাইলে পরের ফাইল আগেরটিকে ছাপিয়ে যায়। আর ফাইল না থাকলে --env-file থেমে যায়, কিন্তু --env-file-if-exists এগিয়ে যায়। প্রথম নিয়মটি production-এ কাজে লাগে: চালানোর প্ল্যাটফর্ম যে মান দেয়, সেটিই আসল।

Secret রেপোর বাইরে

Secret মানে যে মান ফাঁস হলে ক্ষতি। কোড একবার repository-তে গেলে তার ইতিহাসে থেকে যায়, পরের commit-এ মুছলেও। তাই শুরু থেকেই:

.env
.env.*
!.env.example

# এই ফাইল commit হয়: নাম থাকে, আসল মান থাকে না
NODE_ENV=development
PORT=4131
LOG_LEVEL=info
DATABASE_PATH=
SESSION_SECRET=

মনে রাখবেন, .gitignore আগেই commit হওয়া ফাইল সরায় না। Secret একবার ঠেলে দিলে ফাইল মুছে শান্তি নেই; মানটি ফাঁস ধরে নিয়ে নতুন secret বানিয়ে পুরোনোটি বাতিল করুন।

Staging, secret manager আর প্রতিটি পরিবেশের পূর্ণ আলোচনা পর্ব ৭৮-এ আসবে। Cloud-এর দিক দেখতে পারেন Secrets ও KMS পর্বে।

৬ · শুরুতেই যাচাই — ভুল config-এ থেমে যান

ধরুন SESSION_SECRET দিতে ভুলে গেছেন। সাধারণ কোডে server দিব্যি চালু হবে, health check সবুজ, আর সমস্যা দেখা দেবে কয়েক ঘণ্টা পরে, প্রথম login-এ। তখন খুঁজে বের করা কঠিন। Fail fast নীতি বলে: ভুল config-এ server খোলাই যাবে না। Deploy সেখানেই ব্যর্থ হোক, যেখানে পুরোনো version এখনো চলছে।

Environment variable-এর সব মান string. PORT সংখ্যা নয়, "4131". Zod-এর schema (পর্ব ২১-এর form validation আর পর্ব ২৭-এর request যাচাই থেকে পরিচিত) একই সাথে যাচাই করে আর ধরন বদলায়।

import { z } from 'zod';

const schema = z.object({
  NODE_ENV: z.enum(['development', 'test', 'production']),
  PORT: z.coerce.number().int().min(1).max(65535),
  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
  DATABASE_PATH: z.string().min(1),
  SESSION_SECRET: z.string().min(32),
  SHUTDOWN_DRAIN_MS: z.coerce.number().int().min(0).default(1000),
});

export function loadConfig(source) {
  const result = schema.safeParse(source);
  if (!result.success) {
    // শুধু কোন key-তে সমস্যা, মান কখনো নয়
    const lines = result.error.issues.map(
      (i) => `  ${i.path.join('.')}: ${i.message}`,
    );
    throw new Error(`Invalid config:\n${lines.join('\n')}`);
  }
  return Object.freeze(result.data);
}

import { start } from './server.js';

try {
  start(process.env);
} catch (err) {
  console.error(err.message);
  process.exit(1);
}

loadConfig process.env নিজে পড়ে না; সে একটি object নেয়। ফলে test-এ সহজেই নকল object দেওয়া যায়। সত্যিকারের run (Zod 4.6.7), যেখানে .env-এর ওপরে shell থেকে দুটি ভুল মান বসানো হয়েছে:

$ PORT=abc SESSION_SECRET=short node --env-file=.env src/main.js
Invalid config:
  PORT: Invalid input: expected number, received NaN
  SESSION_SECRET: Too small: expected string to have >=32 characters
exit code: 1

দুটি ভুল একসাথে এসেছে, তাই একবারেই ঠিক করা যায়। আর বার্তায় short মানটি নেই, শুধু key-র নাম। নিচের ধাপগুলোয় ওই একই run ভেঙে দেখুন।

1node --env-file=.env src/main.js2const config = loadConfig(process.env);3// issues থাকলে: throw4const log = createLogger(config);5const db = openDb(config.DATABASE_PATH);6app.listen(config.PORT);7catch: process.exit(1);

একই ধারণা package ছাড়া, নিজে চালিয়ে দেখুন। এখানে আসল environment ছোঁয়া হচ্ছে না; brokenEnv আর goodEnv তার জায়গায় বসানো দুটি সাধারণ নকল object.

// নকল environment: সত্যিকারের environment-এর জায়গায় একটি সাধারণ object
const brokenEnv = { NODE_ENV: "prod", PORT: "abc", SESSION_SECRET: "short" };
const goodEnv = {
  NODE_ENV: "production",
  PORT: "4131",
  DATABASE_PATH: "./shop.sqlite",
  SESSION_SECRET: "example-secret-not-real-0123456789abcdef",
};

const rules = {
  NODE_ENV: (v) => ["development", "test", "production"].includes(v),
  PORT: (v) => Number.isInteger(Number(v)) && Number(v) > 0 && Number(v) < 65536,
  DATABASE_PATH: (v) => typeof v === "string" && v.length > 0,
  SESSION_SECRET: (v) => typeof v === "string" && v.length >= 32,
};

function loadConfig(source) {
  // একটি ভুলে না থেমে সব ভুল একসাথে জমা করা
  const bad = Object.keys(rules).filter((key) => !rules[key](source[key]));
  if (bad.length > 0) throw new Error(`Invalid config: ${bad.join(", ")}`);
  return Object.freeze({ ...source, PORT: Number(source.PORT) });
}

function boot(name, source) {
  console.log(`--- boot with ${name}`);
  try {
    const config = loadConfig(source);
    console.log(`listening on port ${config.PORT} (${config.NODE_ENV})`);
  } catch (err) {
    console.log(`${err.message} -> exit code 1, no port opened`);
  }
}

boot("brokenEnv", brokenEnv);
boot("goodEnv", goodEnv);

৭ · Health check — বেঁচে আছি, আর কাজ নিতে পারি

Server একা চলে না। বাইরের ব্যবস্থা নিয়মিত জানতে চায়, আপনি ঠিক আছেন তো? এই ছোট endpoint-ই health check. প্রশ্ন কিন্তু দুটি, আর তাদের উত্তরের ফলও আলাদা।

// Liveness: process বেঁচে আছে। বাইরের কিছু দেখে না।
app.get('/healthz', (req, res) => res.json({ status: 'alive' }));

// Readiness: এখন কি নতুন request নিতে পারি?
app.get('/readyz', (req, res) => {
  if (state.shuttingDown) {
    return res.status(503).json({ status: 'draining' });
  }
  try {
    db.ping(); // SELECT 1
    res.json({ status: 'ready', database: 'ok' });
  } catch (err) {
    log.warn({ reason: err.message }, 'readiness: database down');
    res.status(503).json({ status: 'not-ready', database: 'down' });
  }
});

এই ল্যাবে ছোট database হিসেবে Node-এর node:sqlite ব্যবহার করা হয়েছে; Prisma আসবে পর্ব ৩৯-এ। সত্যিকারের run-এ চলন্ত অবস্থায় database বন্ধ করে দুটি endpoint ডাকা হলো:

/healthz 200 {"status":"alive"}
/readyz 200 {"status":"ready","database":"ok"}
── database বন্ধ করা হলো ──
/healthz 200 {"status":"alive"}
{"level":"warn","time":"2026-11-01T16:33:40.407Z","requestId":"28206835-2c2a-4a68-a4f8-e486be042198","reason":"database is not open","msg":"readiness: database down"}
/readyz 503 {"status":"not-ready","database":"down"}

৮ · Graceful shutdown — দরজা বন্ধ, ভেতরের কাজ শেষ

নতুন version চালাতে পুরোনো process থামাতেই হয়। হঠাৎ থামালে কী হয়? সত্যিকারের run-এ /slow নামের ৮০০ ms-এর একটি কাজ চলাকালীন process-কে সরাসরি শেষ করা হলো (Windows-এ এই কাজটি শর্তহীন):

client error: ECONNRESET
child exit: code null signal SIGTERM

ক্রেতার request মাঝপথে কেটে গেল। Order লেখা হয়েছে কি না, কেউ জানে না। সমাধান graceful shutdown: দোকান বন্ধের সময় আগে শাটার অর্ধেক নামানো, নতুন ক্রেতা না নেওয়া, ভেতরের ক্রেতার কাজ শেষ করা, তারপর তালা।

Linux-এ platform প্রথমে SIGTERM পাঠায়, সময় শেষে SIGKILL, যা ধরা যায় না। ক্রমটিই আসল কথা। server.close() আগে ডাকলে load balancer তখনও জানে না, আর নতুন request গিয়ে ধাক্কা খায়। তাই আগে readiness 503, একটু অপেক্ষা, তারপর close. একেই বলে connection draining.

const shutdown = (signal) => {
  if (state.shuttingDown) return;
  state.shuttingDown = true; // এখন থেকে /readyz দেবে 503
  log.info({ signal }, 'shutdown: readiness now 503');

  const force = setTimeout(() => {
    log.error('shutdown: timed out, forcing exit');
    process.exit(1);
  }, 10_000);
  force.unref();

  setTimeout(() => {
    log.info('shutdown: closing server');
    // চলমান request শেষে ফাঁকা হওয়া keep-alive সংযোগও বন্ধ করা
    const sweep = setInterval(() => server.closeIdleConnections(), 100);
    server.close(() => {
      clearInterval(sweep);
      db.close();
      log.info('shutdown: clean exit');
      clearTimeout(force);
      process.exitCode = 0;
    });
  }, config.SHUTDOWN_DRAIN_MS);
};
process.on('SIGTERM', shutdown);
process.on('SIGINT', shutdown);

এবার ধাপে ধাপে দেখুন। সংখ্যাগুলো ল্যাবের একটি run থেকে: drain ৩০০ ms, আর /slow একটি request আগে থেকেই চলছে। এই run-এর সময় মেশিনভেদে বদলাবে। ল্যাবের এই run Windows-এ, তাই SIGTERM সেখানে আসল signal নয়, process.emit দিয়ে অনুকরণ করা। আসল signal পাঠানো Linux run এই পর্বে আলাদা করে আছে।

1// স্বাভাবিক অবস্থা2on SIGTERM:3  state.shuttingDown = true;4  // /readyz এখন 5035  wait(SHUTDOWN_DRAIN_MS);6  server.close();7  // চলমান request শেষ8  db.close(); exit 0;

এবার সত্যিকারের signal, পাতাতেই। নিচের process নিজেই নিজেকে SIGTERM পাঠাচ্ছে।

const http = require("node:http");
const wait = (ms) => new Promise((done) => setTimeout(done, ms));
let draining = false;
const server = http.createServer(async (req, res) => {
  if (req.url === "/readyz") {
    res.statusCode = draining ? 503 : 200;
    return res.end(draining ? "draining" : "ready");
  }
  await wait(200); // একটি ধীর কাজ, যেমন order লেখা
  res.end("order saved");
});
process.on("SIGTERM", () => {
  console.log("SIGTERM received, readiness goes 503");
  draining = true;
  setTimeout(() => {
    console.log("no new connections now");
    const sweep = setInterval(() => server.closeIdleConnections(), 20);
    server.close(() => { clearInterval(sweep); console.log("clean exit"); });
  }, 60);
});
server.listen(0, "127.0.0.1", async () => {
  const url = `http://127.0.0.1:${server.address().port}`;
  const ask = (path) => fetch(url + path).then((r) => r.text())
    .then((text) => console.log(`${path}: ${text}`))
    .catch((err) => console.log(`${path}: ${err.cause.code}`));
  await ask("/readyz");
  ask("/order");
  await wait(30);
  process.kill(process.pid, "SIGTERM");
  await wait(10);
  await ask("/readyz");
  await wait(100);
  await ask("/readyz");
});

/readyz: ready
SIGTERM received, readiness goes 503
/readyz: draining
no new connections now
/readyz: ECONNREFUSED
/order: order saved
clean exit

পুরো Express অ্যাপেও আসল kill -TERM চালানো হয়েছে (Linux, Node 24.15.0, drain ১০০০ ms, UUID ছোট করা):

$ kill -TERM <server pid>
$ curl readyz during drain
{"status":"draining"} 503
$ slow response:
{"report":"done"}
server exit code: 0
--- server log
{"level":"info","time":"2026-11-01T16:37:34.028Z","signal":"SIGTERM","msg":"shutdown: readiness now 503"}
{"level":"info","time":"2026-11-01T16:37:34.630Z","requestId":"c25a1613…","msg":"slow report finished"}
{"level":"info","time":"2026-11-01T16:37:34.631Z","req":{"method":"GET","url":"/slow"},"requestId":"c25a1613…","res":{"statusCode":200},"responseTime":801,"msg":"request completed"}
{"level":"info","time":"2026-11-01T16:37:35.028Z","msg":"shutdown: closing server"}
{"level":"info","time":"2026-11-01T16:37:35.028Z","msg":"shutdown: clean exit"}

হিসাব: কতক্ষণ অপেক্ষা করবেন

ধরে নেওয়া সংখ্যা: load balancer ৫ সেকেন্ড পরপর দেখে, ২ বার ব্যর্থ হলে সরায়। সবচেয়ে ধীর request ৮ সেকেন্ড। পরিষ্কারের কাজ ২ সেকেন্ড। Platform SIGKILL-এর আগে সময় দেয় ৩০ সেকেন্ড; Kubernetes-এর default-ও এটি, তবে আপনার পরিবেশ মিলিয়ে নিন।

ঘড়ির হিসাবে ১০ সেকেন্ড অপেক্ষার পরই close. আর জোর করে থামানোর timer (আমাদের কোডের force) ২০ সেকেন্ডের বেশি, কিন্তু ৩০-এর কম হতে হবে। উদাহরণের ল্যাব কোডে এই মান কম রাখা হয়েছে, কারণ সেখানে কাজ ছোট।

৯ · Metrics — এক নজরে অ্যাপের নাড়ি

Log জবাব দেয়, “এই request-এ কী ঘটল?” Metrics জবাব দেয়, “এখন সব মিলিয়ে কেমন চলছে?” হাসপাতালের রোগীর ফাইল আর মনিটরের নাড়ির সংখ্যার মধ্যে যে তফাত। ন্যূনতম তিনটি সংখ্যা দিয়ে শুরু করুন: request-এর হার, error-এর হার, আর সময় (latency). prom-client package Prometheus-এর পড়ার মতো আকারে এগুলো দেয়।

import { Registry, Counter, Histogram } from 'prom-client';

export const registry = new Registry();
export const httpRequests = new Counter({
  name: 'http_requests_total', help: 'HTTP requests',
  labelNames: ['method', 'route', 'status'], registers: [registry],
});
export const httpDuration = new Histogram({
  name: 'http_request_duration_seconds', help: 'HTTP latency',
  labelNames: ['route'], buckets: [0.05, 0.1, 0.5, 1], registers: [registry],
});

একটি ছোট middleware প্রতিটি response শেষে এই সংখ্যাগুলো বাড়ায়। আর GET /metrics সেগুলো লেখা আকারে দেয়। সত্যিকারের run-এর অংশ (prom-client 15.1.3):

# TYPE http_requests_total counter
http_requests_total{method="GET",route="/orders/:id",status="200"} 5
http_requests_total{method="GET",route="/orders/:id",status="404"} 1
http_requests_total{method="POST",route="/login",status="200"} 1
…
# TYPE http_request_duration_seconds histogram
http_request_duration_seconds_bucket{le="0.05",route="/orders/:id"} 6
http_request_duration_seconds_bucket{le="+Inf",route="/orders/:id"} 6
http_request_duration_seconds_sum{route="/orders/:id"} 0.1680047
http_request_duration_seconds_count{route="/orders/:id"} 6

ছোট হিসাব: /orders/:id-এর গড় সময় = 0.1680047 ÷ 6 ≈ 0.028 s, অর্থাৎ ২৮ ms. Histogram ৬টির সবকটিকেই ০.০৫ সেকেন্ডের ঘরে রেখেছে। আর error হার: ৬টির ১টি 404, তবে 404 সবসময় server-এর দোষ নয়, তাই error ধরুন 5xx-কে।

এখানে শুধু অ্যাপের ভেতরের অংশ দেখলাম। Error tracking, uptime আর alert পর্ব ৮৩-এ আসবে। আর অপারেশনের গভীর দিক আছে Cloud & DevOps কোর্সে: Metrics ও Prometheus, Centralized logging, Tracing আর Alerting ও SLO.

১০ · AI-এর যুগে log আর config

“Express-এ logging যোগ করে দাও” বললে AI দ্রুত কোড দেবে, আর সেটি চলবেও। সমস্যা হলো, এই বিষয়ের ভুল চলার সময় চোখে পড়ে না। Password log-এ গেলে কোনো error আসে না। পড়ে একদিন, অনেক পরে।

AI-এর লেখা কোড মেলানোর চেকলিস্ট

• নকল password আর token পাঠিয়ে পুরো log-এ খুঁজে দেখেছি, কোথাও খোলা নেই
• প্রতিটি package আর option আমার version-এর official docs-এ পেয়েছি
• একটি env মান মুছে চালিয়েছি, server পরিষ্কার বার্তা দিয়ে থেমেছে, আর বার্তায় secret-এর মান নেই
• Database বন্ধ করে /healthz 200 আর /readyz 503 দেখেছি
• Linux-এ ধীর request চলাকালীন SIGTERM দিয়েছি, request শেষ হয়েছে, exit code 0
• Diff পড়েছি, আর repository-তে কোনো .env বা আসল key যায়নি