@kne/fastify-app-manager 0.1.8 → 0.1.10

package/libs/utils/env.js

@@ -23,6 +23,22 @@ const hasAppDbConfig = (appEnv = {}) => {
   return !!appEnv.DB_DATABASE;
 };
 
+const DB_DEDICATED_KEY = 'DB_DEDICATED';
+const DB_CONNECTION_KEYS = ['DB_DIALECT', 'DB_HOST', 'DB_PORT', 'DB_DATABASE', 'DB_USERNAME', 'DB_PASSWORD', 'DB_STORAGE'];
+
+// 配好独立库后默认启用；DB_DEDICATED=false 时保留配置但回落共享库
+const isAppDbEnabled = (appEnv = {}) =>
+  hasAppDbConfig(appEnv) &&
+  String(appEnv[DB_DEDICATED_KEY] ?? '')
+    .trim()
+    .toLowerCase() !== 'false';
+
+const omitDbConnection = (appEnv = {}) => {
+  const next = Object.assign({}, appEnv);
+  DB_CONNECTION_KEYS.forEach(key => delete next[key]);
+  return next;
+};
+
 const buildDefaultAppDbEnv = (defaultAppDb = {}) => {
   const dialect = defaultAppDb.dialect || 'sqlite';
   const env = { DB_DIALECT: dialect };
@@ -59,10 +75,11 @@ const buildDefaultAppDbEnv = (defaultAppDb = {}) => {
  */
 const resolveAppDbEnv = ({ passthroughEnvKeys = [], appEnv = {}, defaultAppDb = null, port = null, includePort = false, appName = null, injectTablePrefix = true } = {}) => {
   const base = Object.assign({}, pickHostEnv(passthroughEnvKeys));
-  if (defaultAppDb && !hasAppDbConfig(appEnv)) {
+  const useAppDb = isAppDbEnabled(appEnv || {});
+  if (defaultAppDb && !useAppDb) {
     Object.assign(base, buildDefaultAppDbEnv(defaultAppDb));
   }
-  Object.assign(base, appEnv || {});
+  Object.assign(base, useAppDb ? appEnv || {} : omitDbConnection(appEnv || {}));
   if (includePort && port != null) {
     base.PORT = String(port);
   }
@@ -105,10 +122,17 @@ const isSecretKey = (key, pattern, secretKeys = []) => {
   return isPatternSecretKey(key, pattern);
 };
 
-const maskEnvForResponse = (appEnv = {}, { secretEnvKeyPattern, secretEnvKeys = [] } = {}) => {
+// 由系统写入维护：不在接口中返回，也不接受外部新增 / 修改 / 删除；宿主可通过 systemEnvKeys 选项追加
+const SYSTEM_ENV_KEYS = ['DB_TABLE_PREFIX'];
+
+const isSystemEnvKey = (key, systemEnvKeys = []) => SYSTEM_ENV_KEYS.includes(key) || (systemEnvKeys || []).includes(key);
+
+const omitSystemEnv = (appEnv = {}, systemEnvKeys = []) => Object.fromEntries(Object.entries(appEnv || {}).filter(([key]) => !isSystemEnvKey(key, systemEnvKeys)));
+
+const maskEnvForResponse = (appEnv = {}, { secretEnvKeyPattern, secretEnvKeys = [], systemEnvKeys = [] } = {}) => {
   const masked = {};
   const explicit = normalizeSecretKeys(secretEnvKeys);
-  for (const [key, value] of Object.entries(appEnv || {})) {
+  for (const [key, value] of Object.entries(omitSystemEnv(appEnv, systemEnvKeys))) {
     if (isSecretKey(key, secretEnvKeyPattern, explicit)) {
       masked[key] = value == null || value === '' ? null : SECRET_MASK;
     } else {
@@ -124,10 +148,13 @@ const maskEnvForResponse = (appEnv = {}, { secretEnvKeyPattern, secretEnvKeys =
  * SECRET_MASK => keep existing (when key is secret by pattern or explicit list)
  * other => set
  */
-const applyEnvPatch = (current = {}, patch = {}, { secretEnvKeyPattern, secretEnvKeys = [] } = {}) => {
+const applyEnvPatch = (current = {}, patch = {}, { secretEnvKeyPattern, secretEnvKeys = [], systemEnvKeys = [] } = {}) => {
   const next = Object.assign({}, current);
   const explicit = normalizeSecretKeys(secretEnvKeys);
   for (const [key, value] of Object.entries(patch || {})) {
+    if (isSystemEnvKey(key, systemEnvKeys)) {
+      continue;
+    }
     if (value === null) {
       delete next[key];
       continue;
@@ -143,10 +170,10 @@ const applyEnvPatch = (current = {}, patch = {}, { secretEnvKeyPattern, secretEn
 /**
  * 响应中的密钥键列表 = 显式列表 ∪ 当前 env 中匹配 pattern 的键
  */
-const collectSecretKeys = (appEnv = {}, { secretEnvKeyPattern, secretEnvKeys = [] } = {}) => {
+const collectSecretKeys = (appEnv = {}, { secretEnvKeyPattern, secretEnvKeys = [], systemEnvKeys = [] } = {}) => {
   const explicit = normalizeSecretKeys(secretEnvKeys);
   const fromPattern = Object.keys(appEnv || {}).filter(key => isPatternSecretKey(key, secretEnvKeyPattern));
-  return normalizeSecretKeys([...explicit, ...fromPattern]);
+  return normalizeSecretKeys([...explicit, ...fromPattern]).filter(key => !isSystemEnvKey(key, systemEnvKeys));
 };
 
 const PM2_CONFIG_KEYS = ['exec_mode', 'instances', 'autorestart', 'max_memory_restart', 'max_restarts', 'min_uptime', 'kill_timeout', 'merge_logs'];
@@ -166,11 +193,16 @@ module.exports = {
   normalizeSecretKeys,
   pickHostEnv,
   hasAppDbConfig,
+  DB_DEDICATED_KEY,
+  isAppDbEnabled,
   buildDefaultAppDbEnv,
   resolveAppDbEnv,
   mergeEnv,
   isPatternSecretKey,
   isSecretKey,
+  SYSTEM_ENV_KEYS,
+  isSystemEnvKey,
+  omitSystemEnv,
   maskEnvForResponse,
   applyEnvPatch,
   collectSecretKeys,

package/libs/utils/loadMonitor.js

@@ -0,0 +1,73 @@
+const { EventEmitter } = require('node:events');
+
+// cluster 模式下同名进程有多个实例，按 PM2 进程名汇总为一条负载
+const summarizeProcesses = (processes, { now = Date.now() } = {}) => {
+  const groups = new Map();
+  for (const proc of processes || []) {
+    const name = proc?.name || proc?.pm2_env?.name;
+    if (!name) {
+      continue;
+    }
+    if (!groups.has(name)) {
+      groups.set(name, []);
+    }
+    groups.get(name).push(proc);
+  }
+
+  const result = new Map();
+  for (const [name, list] of groups) {
+    const online = list.filter(proc => proc.pm2_env?.status === 'online');
+    const startedAt = online.map(proc => Number(proc.pm2_env?.pm_uptime)).filter(value => Number.isFinite(value) && value > 0);
+    const cpu = list.reduce((sum, proc) => sum + (Number(proc.monit?.cpu) || 0), 0);
+    result.set(name, {
+      status: online.length ? 'online' : list[0].pm2_env?.status || 'unknown',
+      cpu: Math.round(cpu * 10) / 10,
+      memory: list.reduce((sum, proc) => sum + (Number(proc.monit?.memory) || 0), 0),
+      instances: list.length,
+      pids: online.map(proc => proc.pid).filter(Boolean),
+      uptime: startedAt.length ? Math.max(0, now - Math.min(...startedAt)) : 0,
+      restarts: list.reduce((sum, proc) => sum + (Number(proc.pm2_env?.restart_time) || 0), 0)
+    });
+  }
+  return result;
+};
+
+const createLoadStore = ({ size }) => {
+  const capacity = Math.max(1, Math.floor(size) || 1);
+  const buffers = new Map();
+  const emitter = new EventEmitter();
+  emitter.setMaxListeners(0);
+
+  const push = (name, sample) => {
+    const buffer = buffers.get(name) || [];
+    buffer.push(sample);
+    if (buffer.length > capacity) {
+      buffer.splice(0, buffer.length - capacity);
+    }
+    buffers.set(name, buffer);
+    emitter.emit(`load:${name}`, sample);
+  };
+
+  const history = name => (buffers.get(name) || []).slice();
+
+  const latest = name => {
+    const buffer = buffers.get(name);
+    return buffer && buffer.length ? buffer[buffer.length - 1] : null;
+  };
+
+  const retain = names => {
+    const keep = new Set(names);
+    for (const name of buffers.keys()) {
+      if (!keep.has(name)) {
+        buffers.delete(name);
+      }
+    }
+  };
+
+  return { capacity, push, history, latest, retain, emitter };
+};
+
+module.exports = {
+  summarizeProcesses,
+  createLoadStore
+};

package/libs/utils/logFiles.js

@@ -1,6 +1,11 @@
 const path = require('node:path');
+const zlib = require('node:zlib');
 const fs = require('fs-extra');
 const { EventEmitter } = require('node:events');
+const { convertLinePrefix } = require('./logTime');
+
+const NEWLINE = 0x0a;
+const CHUNK_SIZE = 64 * 1024;
 
 const createLogHub = () => {
   const emitter = new EventEmitter();
@@ -22,38 +27,180 @@ const appendLog = async (filePath, content) => {
   await fs.appendFile(filePath, content.endsWith('\n') ? content : `${content}\n`);
 };
 
-const readLogTail = async (filePath, { perPage = 100, currentPage = 1, beforeLine } = {}) => {
+const lineCache = new Map();
+const gzipLineCache = new Map();
+
+const countNewlines = buffer => {
+  let count = 0;
+  for (let idx = buffer.indexOf(NEWLINE); idx !== -1; idx = buffer.indexOf(NEWLINE, idx + 1)) {
+    count++;
+  }
+  return count;
+};
+
+/** Counts lines incrementally; the file is only rescanned from 0 after rotation (inode change) or truncation. */
+const getLineInfo = async filePath => {
+  let stat;
+  try {
+    stat = await fs.stat(filePath);
+  } catch (e) {
+    lineCache.delete(filePath);
+    return { count: 0, size: 0 };
+  }
+  const cached = lineCache.get(filePath);
+  let { newlines, lastByte, size } = cached && cached.ino === stat.ino && stat.size >= cached.size ? cached : { newlines: 0, lastByte: null, size: 0 };
+  if (stat.size > size) {
+    for await (const chunk of fs.createReadStream(filePath, { start: size, end: stat.size - 1 })) {
+      newlines += countNewlines(chunk);
+      lastByte = chunk[chunk.length - 1];
+    }
+    size = stat.size;
+  }
+  lineCache.set(filePath, { ino: stat.ino, size, newlines, lastByte });
+  return { count: newlines + (size > 0 && lastByte !== NEWLINE ? 1 : 0), size };
+};
+
+const countLines = async filePath => (await getLineInfo(filePath)).count;
+
+/** Reads `take` lines ending `skip` lines before the end of the first `size` bytes; newest first. */
+const readLinesFromEnd = async (filePath, { size, skip, take }) => {
+  const collected = [];
+  let skipped = 0;
+  const accept = buffer => {
+    if (skipped < skip) {
+      skipped++;
+      return true;
+    }
+    collected.push(buffer.toString('utf8').replace(/\r$/, ''));
+    return collected.length < take;
+  };
+
+  const handle = await fs.promises.open(filePath, 'r');
+  try {
+    let pos = size;
+    let carry = Buffer.alloc(0);
+    let first = true;
+    let more = true;
+    while (pos > 0 && more) {
+      const length = Math.min(CHUNK_SIZE, pos);
+      pos -= length;
+      const chunk = Buffer.alloc(length);
+      await handle.read(chunk, 0, length, pos);
+      let data = carry.length ? Buffer.concat([chunk, carry]) : chunk;
+      if (first) {
+        first = false;
+        if (data[data.length - 1] === NEWLINE) {
+          data = data.subarray(0, data.length - 1);
+        }
+      }
+      let end = data.length;
+      let idx = data.lastIndexOf(NEWLINE);
+      while (idx !== -1 && more) {
+        more = accept(data.subarray(idx + 1, end));
+        end = idx;
+        idx = idx > 0 ? data.lastIndexOf(NEWLINE, idx - 1) : -1;
+      }
+      carry = data.subarray(0, end);
+    }
+    if (more && pos === 0 && size > 0) {
+      accept(carry);
+    }
+  } finally {
+    await handle.close();
+  }
+  return collected;
+};
+
+// Splits on `\n` only (same rule as plain files); `onLine` returns false to stop early.
+const scanGzipLines = async (filePath, onLine) => {
+  const input = fs.createReadStream(filePath);
+  const gunzip = zlib.createGunzip();
+  input.pipe(gunzip);
+  let index = 0;
+  let carry = Buffer.alloc(0);
+  try {
+    for await (const chunk of gunzip) {
+      const data = carry.length ? Buffer.concat([carry, chunk]) : chunk;
+      let begin = 0;
+      for (let idx = data.indexOf(NEWLINE); idx !== -1; idx = data.indexOf(NEWLINE, begin)) {
+        if (onLine(data.subarray(begin, idx), index++) === false) {
+          return index;
+        }
+        begin = idx + 1;
+      }
+      carry = data.subarray(begin);
+    }
+    if (carry.length) {
+      onLine(carry, index++);
+    }
+    return index;
+  } finally {
+    input.destroy();
+    gunzip.destroy();
+  }
+};
+
+const countGzipLines = async filePath => {
+  const stat = await fs.stat(filePath);
+  const key = `${stat.mtimeMs}:${stat.size}`;
+  const cached = gzipLineCache.get(filePath);
+  if (cached && cached.key === key) {
+    return cached.count;
+  }
+  const count = await scanGzipLines(filePath, () => true);
+  gzipLineCache.set(filePath, { key, count });
+  return count;
+};
+
+const readGzipRange = async (filePath, start, end) => {
+  const lines = [];
+  await scanGzipLines(filePath, (buffer, index) => {
+    if (index >= start) {
+      lines.push(buffer.toString('utf8').replace(/\r$/, ''));
+    }
+    return index + 1 < end;
+  });
+  return lines.reverse();
+};
+
+const resolvePageRange = (totalCount, { perPage, currentPage, beforeLine }) => {
   const size = Math.min(100, Math.max(1, Number(perPage) || 100));
   const page = Math.max(1, Number(currentPage) || 1);
+  if (beforeLine != null && beforeLine !== '' && Number(beforeLine) > 0) {
+    // 取 line < beforeLine 的尾部 size 行（0-based slice end = beforeLine-1）
+    const end = Math.min(Math.max(0, Number(beforeLine) - 1), totalCount);
+    return { start: Math.max(0, end - size), end };
+  }
+  return {
+    start: Math.max(0, totalCount - size * page),
+    end: Math.max(0, totalCount - size * (page - 1))
+  };
+};
+
+const readLogTail = async (filePath, { perPage = 100, currentPage = 1, beforeLine, timezone } = {}) => {
   if (!(await fs.pathExists(filePath))) {
     return { pageData: [], totalCount: 0, hasMore: false };
   }
-  const text = await fs.readFile(filePath, 'utf8');
-  const lines = text.split(/\r?\n/).filter((line, idx, arr) => !(idx === arr.length - 1 && line === ''));
-  const totalCount = lines.length;
-  let start;
-  let end;
-  if (beforeLine != null && beforeLine !== '' && Number(beforeLine) > 0) {
-    // 取 line < beforeLine 的尾部 size 行（0-based slice end = beforeLine-1）
-    end = Math.min(Math.max(0, Number(beforeLine) - 1), totalCount);
-    start = Math.max(0, end - size);
-  } else {
-    start = Math.max(0, totalCount - size * page);
-    end = Math.max(0, totalCount - size * (page - 1));
+  const compressed = filePath.endsWith('.gz');
+  const info = compressed ? { count: await countGzipLines(filePath) } : await getLineInfo(filePath);
+  const totalCount = info.count;
+  const { start, end } = resolvePageRange(totalCount, { perPage, currentPage, beforeLine });
+  let contents = [];
+  if (end > start) {
+    contents = compressed ? await readGzipRange(filePath, start, end) : await readLinesFromEnd(filePath, { size: info.size, skip: totalCount - end, take: end - start });
   }
-  const pageData = lines.slice(start, end).map((content, i) => ({
-    line: start + i + 1,
-    content
-  }));
   return {
-    pageData: pageData.reverse(),
+    pageData: contents.map((content, i) => ({
+      line: end - i,
+      content: convertLinePrefix(content, timezone)
+    })),
     totalCount,
     hasMore: start > 0
   };
 };
 
-const readLastLines = async (filePath, n = 100) => {
-  const { pageData } = await readLogTail(filePath, { perPage: n, currentPage: 1 });
+const readLastLines = async (filePath, n = 100, { timezone } = {}) => {
+  const { pageData } = await readLogTail(filePath, { perPage: n, currentPage: 1, timezone });
   return pageData.reverse();
 };
 
@@ -61,6 +208,7 @@ module.exports = {
   createLogHub,
   ensureLogFiles,
   appendLog,
+  countLines,
   readLogTail,
   readLastLines
 };

package/libs/utils/logRotate.js

@@ -0,0 +1,162 @@
+const path = require('node:path');
+const zlib = require('node:zlib');
+const { pipeline } = require('node:stream/promises');
+const fs = require('fs-extra');
+const { formatInTz, dateKeyInTz } = require('./logTime');
+
+const LOG_STREAMS = ['out', 'err'];
+const STATE_FILE = '.rotate-state.json';
+const LOG_FILE_RE = /^(out|err)(?:-\d{8}-\d{6}(?:-\d+)?)?\.log(\.gz)?$/;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+const currentFileName = stream => `${stream === 'err' ? 'err' : 'out'}.log`;
+
+const isCurrentFileName = fileName => LOG_STREAMS.some(stream => currentFileName(stream) === fileName);
+
+const badRequest = message => {
+  const err = new Error(message);
+  err.statusCode = 400;
+  return err;
+};
+
+const resolveLogFile = (logsDir, fileName) => {
+  if (typeof fileName !== 'string' || path.basename(fileName) !== fileName || !LOG_FILE_RE.test(fileName)) {
+    throw badRequest(`invalid log file: ${fileName}`);
+  }
+  return path.join(logsDir, fileName);
+};
+
+const readState = async logsDir => {
+  try {
+    return (await fs.readJson(path.join(logsDir, STATE_FILE))) || {};
+  } catch (e) {
+    return {};
+  }
+};
+
+const writeState = (logsDir, state) => fs.writeJson(path.join(logsDir, STATE_FILE), state);
+
+const resolveStartTime = (state, stream, stat) => {
+  const recorded = state[stream] ? new Date(state[stream]) : null;
+  if (recorded && !Number.isNaN(recorded.getTime())) {
+    return recorded;
+  }
+  return stat.birthtimeMs > 0 ? stat.birthtime : stat.mtime;
+};
+
+const uniqueArchivePath = async (logsDir, baseName) => {
+  for (let n = 0; ; n++) {
+    const target = path.join(logsDir, n ? `${baseName}-${n}.log` : `${baseName}.log`);
+    if (!(await fs.pathExists(target)) && !(await fs.pathExists(`${target}.gz`))) {
+      return target;
+    }
+  }
+};
+
+/**
+ * Renames `{stream}.log` to `{stream}-{startTime}.log` when it exceeds maxSize or its start day
+ * (in `timezone`) is before `now`. Caller must reopen the PM2 log handles afterwards.
+ */
+const rotateIfNeeded = async ({ logsDir, stream, maxSize, daily = false, timezone, now = new Date() }) => {
+  const file = path.join(logsDir, currentFileName(stream));
+  let stat;
+  try {
+    stat = await fs.stat(file);
+  } catch (e) {
+    return null;
+  }
+  const state = await readState(logsDir);
+  const startedAt = resolveStartTime(state, stream, stat);
+  const dayChanged = daily && dateKeyInTz(startedAt, timezone) !== dateKeyInTz(now, timezone);
+
+  let reason = null;
+  if (stat.size > 0 && maxSize > 0 && stat.size >= maxSize) {
+    reason = 'size';
+  } else if (stat.size > 0 && dayChanged) {
+    reason = 'daily';
+  }
+
+  if (!reason) {
+    // An empty file carries no content from the old day; restart its clock so today's logs get today's name.
+    if (!state[stream] || (stat.size === 0 && dayChanged)) {
+      state[stream] = (stat.size === 0 && dayChanged ? now : startedAt).toISOString();
+      await writeState(logsDir, state);
+    }
+    return null;
+  }
+
+  const archive = await uniqueArchivePath(logsDir, `${stream}-${formatInTz(startedAt, timezone, 'YYYYMMDD-HHmmss')}`);
+  await fs.rename(file, archive);
+  await fs.ensureFile(file);
+  state[stream] = now.toISOString();
+  await writeState(logsDir, state);
+  return { archive, reason };
+};
+
+const compressArchive = async file => {
+  const target = `${file}.gz`;
+  const stat = await fs.stat(file);
+  await pipeline(fs.createReadStream(file), zlib.createGzip(), fs.createWriteStream(target));
+  await fs.utimes(target, stat.atime, stat.mtime);
+  await fs.remove(file);
+  return target;
+};
+
+const listLogFiles = async logsDir => {
+  let names = [];
+  try {
+    names = await fs.readdir(logsDir);
+  } catch (e) {
+    return [];
+  }
+  const files = [];
+  for (const fileName of names) {
+    const match = LOG_FILE_RE.exec(fileName);
+    if (!match) {
+      continue;
+    }
+    let stat;
+    try {
+      stat = await fs.stat(path.join(logsDir, fileName));
+    } catch (e) {
+      continue;
+    }
+    if (!stat.isFile()) {
+      continue;
+    }
+    files.push({
+      fileName,
+      stream: match[1],
+      size: stat.size,
+      compressed: !!match[2],
+      current: isCurrentFileName(fileName),
+      mtime: stat.mtime
+    });
+  }
+  return files.sort((a, b) => Number(b.current) - Number(a.current) || b.mtime - a.mtime);
+};
+
+const applyRetention = async ({ logsDir, stream, maxFiles, maxDays, now = new Date() }) => {
+  const archives = (await listLogFiles(logsDir)).filter(file => !file.current && (!stream || file.stream === stream));
+  const removed = [];
+  for (const [index, file] of archives.entries()) {
+    const tooMany = maxFiles > 0 && index >= maxFiles;
+    const tooOld = maxDays > 0 && now.getTime() - file.mtime.getTime() > maxDays * DAY_MS;
+    if (tooMany || tooOld) {
+      await fs.remove(path.join(logsDir, file.fileName));
+      removed.push(file.fileName);
+    }
+  }
+  return removed;
+};
+
+module.exports = {
+  LOG_STREAMS,
+  currentFileName,
+  isCurrentFileName,
+  resolveLogFile,
+  rotateIfNeeded,
+  compressArchive,
+  listLogFiles,
+  applyRetention
+};

package/libs/utils/logTime.js

@@ -0,0 +1,132 @@
+const OFFSET_RE = /^([+-])(\d{2}):?(\d{2})$/;
+const LINE_PREFIX_RE = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?=: )/;
+
+const formatterCache = new Map();
+
+const getFormatter = timeZone => {
+  if (!formatterCache.has(timeZone)) {
+    formatterCache.set(
+      timeZone,
+      new Intl.DateTimeFormat('en-US', {
+        timeZone,
+        hourCycle: 'h23',
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit'
+      })
+    );
+  }
+  return formatterCache.get(timeZone);
+};
+
+const parsedCache = new Map();
+
+const parseTimezone = tz => {
+  if (tz && typeof tz === 'object' && (tz.type === 'offset' || tz.type === 'iana')) {
+    return tz;
+  }
+  const value = tz == null ? '' : String(tz).trim();
+  if (!parsedCache.has(value)) {
+    parsedCache.set(value, parseTimezoneValue(value));
+  }
+  return parsedCache.get(value);
+};
+
+const parseTimezoneValue = value => {
+  const match = OFFSET_RE.exec(value);
+  if (match) {
+    const hours = Number(match[2]);
+    const minutes = Number(match[3]);
+    if (hours > 14 || minutes > 59) {
+      throw new Error(`invalid logTimezone: ${value}`);
+    }
+    return { type: 'offset', offsetMinutes: (match[1] === '-' ? -1 : 1) * (hours * 60 + minutes) };
+  }
+  if (!value) {
+    throw new Error('invalid logTimezone: empty');
+  }
+  try {
+    getFormatter(value);
+  } catch (e) {
+    throw new Error(`invalid logTimezone: ${value}`);
+  }
+  return { type: 'iana', name: value };
+};
+
+const getOffsetMinutes = (date, tz) => {
+  const info = parseTimezone(tz);
+  if (info.type === 'offset') {
+    return info.offsetMinutes;
+  }
+  const parts = {};
+  for (const { type, value } of getFormatter(info.name).formatToParts(date)) {
+    parts[type] = value;
+  }
+  const asUtc = Date.UTC(Number(parts.year), Number(parts.month) - 1, Number(parts.day), Number(parts.hour) % 24, Number(parts.minute), Number(parts.second));
+  return Math.round((asUtc - Math.floor(date.getTime() / 1000) * 1000) / 60000);
+};
+
+const pad = (value, length = 2) => String(value).padStart(length, '0');
+
+const formatOffset = minutes => {
+  const abs = Math.abs(minutes);
+  return `${minutes < 0 ? '-' : '+'}${pad(Math.floor(abs / 60))}:${pad(abs % 60)}`;
+};
+
+const formatInTz = (date, tz, pattern = 'YYYY-MM-DDTHH:mm:ss') => {
+  const shifted = new Date(date.getTime() + getOffsetMinutes(date, tz) * 60000);
+  const tokens = {
+    YYYY: pad(shifted.getUTCFullYear(), 4),
+    MM: pad(shifted.getUTCMonth() + 1),
+    DD: pad(shifted.getUTCDate()),
+    HH: pad(shifted.getUTCHours()),
+    mm: pad(shifted.getUTCMinutes()),
+    ss: pad(shifted.getUTCSeconds())
+  };
+  return pattern.replace(/YYYY|MM|DD|HH|mm|ss/g, token => tokens[token]);
+};
+
+const toIsoInTz = (date, tz) => `${formatInTz(date, tz)}${formatOffset(getOffsetMinutes(date, tz))}`;
+
+const dateKeyInTz = (date, tz) => formatInTz(date, tz, 'YYYY-MM-DD');
+
+// PM2 `time: true` prefixes lines in the daemon's local time without an offset; assume it matches this process.
+const convertLinePrefix = (line, tz) => {
+  if (!tz || typeof line !== 'string') {
+    return line;
+  }
+  const match = LINE_PREFIX_RE.exec(line);
+  if (!match) {
+    return line;
+  }
+  const [, y, mo, d, h, mi, s] = match.map(Number);
+  const date = new Date(y, mo - 1, d, h, mi, s);
+  if (Number.isNaN(date.getTime()) || getOffsetMinutes(date, tz) === -date.getTimezoneOffset()) {
+    return line;
+  }
+  return `${formatInTz(date, tz)}${line.slice(match[0].length)}`;
+};
+
+const convertLogText = (text, tz) => {
+  if (!tz || typeof text !== 'string') {
+    return text;
+  }
+  return text
+    .split('\n')
+    .map(line => convertLinePrefix(line, tz))
+    .join('\n');
+};
+
+module.exports = {
+  parseTimezone,
+  getOffsetMinutes,
+  formatOffset,
+  formatInTz,
+  toIsoInTz,
+  dateKeyInTz,
+  convertLinePrefix,
+  convertLogText
+};