Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
7.6 KB
Raw Blame
/**
 * Env-gated wire-level SQL trace for benchmarks (`GBRAIN_SQL_TRACE=<file.jsonl>`,
 * docs/eval/managed-sync-catchup.md). Every postgres.js pool (module singleton,
 * instance pool, read and direct pools) passes its options through
 * `traceSqlOptions`, so `executeRaw`, `tx.unsafe`, the engine-sql adapter and
 * tagged templates are all seen at the socket. Each Sync or simple Query sent
 * and its ReadyForQuery reply is one record: one database round trip, including
 * the describe round trip an unprepared parameterized statement pays. Records
 * carry the statement text (never parameter values), start, duration, process,
 * pool, client connection and backend pid; `application_name` names the process
 * so `pg_stat_activity` lock samples can be attributed. TLS connections are not
 * decodable and are recorded once as `kind: "tls_untraced"`.
 *
 * Off (the default) it returns the options object untouched: no socket wrapper,
 * no per-query work.
 */
import { appendFileSync } from 'node:fs';
import net from 'node:net';

interface Pending { sql: string; kind: 'execute' | 'describe' | 'simple' | 'connect'; t: number; err?: string; flush?: boolean }
interface TraceConnection {
  id: number; backend: number; prepared: Map<string, string>; text: string; executed: boolean; pending: Pending[];
  out: Buffer | null; startup: boolean; opaque: boolean;
  inHeader: Buffer; inType: number; inLeft: number; inBody: Buffer[] | null;
}

let connections = 0;
/** Unwritten records by trace file: each pool's records go to the file it was created with. */
const buffered = new Map<string, string[]>();
let flushOnExit = false;
const clock = () => performance.timeOrigin + performance.now();
const SSL_REQUEST = 80877103;
const KEEP_BODY = new Set([0x4b, 0x45, 0x5a, 0x54, 0x6e]);

function cstring(buf: Buffer, at: number): [string, number] {
  const end = buf.indexOf(0, at);
  return end < 0 ? [buf.toString('utf8', at), buf.length] : [buf.toString('utf8', at, end), end + 1];
}

function emit(file: string, record: Record<string, unknown>): void {
  let lines = buffered.get(file);
  if (!lines) buffered.set(file, lines = []);
  lines.push(JSON.stringify(record));
  if (!flushOnExit) { flushOnExit = true; process.on('exit', flushAll); setInterval(flushAll, 1000).unref(); }
  if (lines.length >= 500) flush(file);
}
function flushAll(): void {
  for (const file of [...buffered.keys()]) flush(file);
}
function flush(file: string): void {
  const pending = buffered.get(file);
  if (!pending?.length) return;
  const lines = pending.join('\n') + '\n';
  buffered.delete(file);
  try { appendFileSync(file, lines); } catch { /* a trace that cannot be written never fails the traced process */ }
}

function outgoing(c: TraceConnection, chunk: Buffer): void {
  let buf = c.out ? Buffer.concat([c.out, chunk]) : chunk;
  c.out = null;
  while (!c.opaque) {
    if (c.startup) {
      if (buf.length < 8) break;
      const len = buf.readInt32BE(0);
      if (buf.readInt32BE(4) === SSL_REQUEST) { c.opaque = true; break; }
      if (buf.length < len) break;
      c.startup = false; buf = buf.subarray(len); continue;
    }
    if (buf.length < 5) break;
    const total = 1 + buf.readInt32BE(1);
    if (buf.length < total) break;
    const type = buf[0]; const body = buf.subarray(5, total);
    if (type === 0x50) { const [name, at] = cstring(body, 0); c.text = cstring(body, at)[0]; c.prepared.set(name, c.text); }
    else if (type === 0x42) { const [, at] = cstring(body, 0); c.text = c.prepared.get(cstring(body, at)[0]) ?? c.text; }
    else if (type === 0x45) c.executed = true;
    else if (type === 0x51) c.pending.push({ sql: cstring(body, 0)[0], kind: 'simple', t: clock() });
    else if (type === 0x53) { c.pending.push({ sql: c.text, kind: c.executed ? 'execute' : 'describe', t: clock() }); c.executed = false; }
    else if (type === 0x48) c.pending.push({ sql: c.text, kind: 'describe', t: clock(), flush: true });
    buf = buf.subarray(total);
  }
  if (!c.opaque && buf.length) c.out = Buffer.from(buf);
}

function message(c: TraceConnection, type: number, body: Buffer, file: string, label: string, pool: string): void {
  if (type === 0x4b) c.backend = body.readInt32BE(0);
  else if (type === 0x45 && c.pending[0]) {
    for (let at = 0; at < body.length && body[at] !== 0;) {
      const field = body[at]!; const [value, next] = cstring(body, at + 1); at = next;
      if (field === 0x43) { c.pending[0].err = value; break; }
    }
  } else if (type === 0x5a || (type === 0x54 || type === 0x6e) && c.pending[0]?.flush) {
    const done = c.pending.shift();
    if (!done) return;
    const end = clock();
    emit(file, { t: Math.round(done.t * 1000) / 1000, ms: Math.round((end - done.t) * 1000) / 1000, pid: process.pid, label, pool,
      conn: c.id, backend: c.backend, kind: done.kind, sql: done.sql.length > 2000 ? done.sql.slice(0, 2000) : done.sql, ...(done.err ? { err: done.err } : {}) });
  }
}

function incoming(c: TraceConnection, chunk: Buffer, file: string, label: string, pool: string): void {
  let at = 0;
  while (at < chunk.length && !c.opaque) {
    if (c.inLeft === 0) {
      const take = Math.min(5 - c.inHeader.length, chunk.length - at);
      c.inHeader = Buffer.concat([c.inHeader, chunk.subarray(at, at + take)]); at += take;
      if (c.inHeader.length < 5) return;
      c.inType = c.inHeader[0]!; c.inLeft = c.inHeader.readInt32BE(1) - 4; c.inHeader = Buffer.alloc(0);
      c.inBody = KEEP_BODY.has(c.inType) ? [] : null;
      if (c.inLeft === 0) { message(c, c.inType, Buffer.alloc(0), file, label, pool); continue; }
    }
    const take = Math.min(c.inLeft, chunk.length - at);
    c.inBody?.push(chunk.subarray(at, at + take));
    at += take; c.inLeft -= take;
    if (c.inLeft === 0 && c.inBody) message(c, c.inType, Buffer.concat(c.inBody), file, label, pool);
  }
}

async function tracedSocket(options: { host: string[]; port: number[]; path?: string | false }, file: string, label: string, pool: string): Promise<net.Socket> {
  const opened = clock();
  const socket = options.path ? net.connect(options.path) : net.connect(options.port[0]!, options.host[0]!);
  await new Promise<void>((resolve, reject) => { socket.once('connect', resolve); socket.once('error', reject); });
  const c: TraceConnection = { id: ++connections, backend: 0, prepared: new Map(), text: '', executed: false, pending: [{ sql: '<connect>', kind: 'connect', t: opened }], out: null,
    startup: true, opaque: false, inHeader: Buffer.alloc(0), inType: 0, inLeft: 0, inBody: null };
  const write = socket.write.bind(socket) as (chunk: unknown, ...rest: unknown[]) => boolean;
  socket.write = ((chunk: unknown, ...rest: unknown[]) => {
    if (!c.opaque && Buffer.isBuffer(chunk)) {
      outgoing(c, chunk);
      if (c.opaque) emit(file, { t: clock(), ms: 0, pid: process.pid, label, pool, conn: c.id, backend: 0, kind: 'tls_untraced', sql: '' });
    }
    return write(chunk, ...rest);
  }) as typeof socket.write;
  socket.on('data', (chunk: Buffer) => { if (!c.opaque) incoming(c, chunk, file, label, pool); });
  return socket;
}

/** Returns `options` unchanged unless GBRAIN_SQL_TRACE names a file; then adds the tracing socket and a labelled application_name. */
export function traceSqlOptions<T extends Record<string, unknown>>(options: T, pool: string): T {
  const file = process.env.GBRAIN_SQL_TRACE;
  if (!file) return options;
  const label = process.env.GBRAIN_SQL_TRACE_LABEL || process.argv[2] || 'gbrain';
  return {
    ...options,
    connection: { ...(options.connection as Record<string, unknown> | undefined), application_name: `gbrain:${label}:${process.pid}:${pool}`.slice(0, 63) },
    socket: (o: { host: string[]; port: number[]; path?: string | false }) => tracedSocket(o, file, label, pool),
  };
}