@shibbirweb/mcp-db-read-only 0.1.0 → 1.0.0

package/dist/ApplicationFactory.js

@@ -16,6 +16,17 @@ import { MySqlDriver } from "./drivers/sql/MySqlDriver.js";
 import { PostgresDriver } from "./drivers/sql/PostgresDriver.js";
 import { SqliteDriver } from "./drivers/sql/SqliteDriver.js";
 import { RowFormatter } from "./formatting/RowFormatter.js";
+import { CallLogger } from "./logging/CallLogger.js";
+import { TextLogChannel } from "./logging/LogChannel.js";
+import { LiveLogViewer } from "./logging/viewer/LiveLogViewer.js";
+import { LiveViewerObserver } from "./logging/viewer/LiveViewerObserver.js";
+import { FolderLogChannel } from "./logging/store/FolderLogChannel.js";
+import { FolderLogStore } from "./logging/store/FolderLogStore.js";
+import { MemoryLogStore } from "./logging/store/MemoryLogStore.js";
+import { JsonLogFormatter, PrettyLogFormatter } from "./logging/LogFormatter.js";
+import { FileSink, StderrSink } from "./logging/LogSink.js";
+import { SilentTracer } from "./logging/StatementTracer.js";
+import { SilentObserver } from "./logging/ToolCallObserver.js";
 import { McpDbServer } from "./server/McpDbServer.js";
 import { DescribeTableTool } from "./tools/browse/DescribeTableTool.js";
 import { GetForeignKeysTool } from "./tools/browse/GetForeignKeysTool.js";
@@ -63,6 +74,11 @@ export class ApplicationFactory {
      * total open connections at MAX_DRIVERS * CONNECTION_LIMIT.
      */
     static MAX_DRIVERS = 8;
+    /**
+     * Set once built, for the call log's client name: the logger has to exist
+     * before the server that will learn the name at handshake.
+     */
+    server = null;
     constructor(configLoader = new EnvironmentConfigLoader(), logger = (message) => console.error(`[mcp-db-ro] ${message}`), versionLoader = new PackageVersionLoader()) {
         this.configLoader = configLoader;
         this.logger = logger;
@@ -86,31 +102,112 @@ export class ApplicationFactory {
             connectTimeoutMs: config.connectTimeoutMs,
             queryTimeoutMs: config.queryTimeoutMs,
         };
-        const cache = new DriverCache(this.createDriverRegistry(tuning), ApplicationFactory.MAX_DRIVERS);
+        const callLog = this.createCallLog(config.logging, registry);
+        const cache = new DriverCache(this.createDriverRegistry(tuning, callLog.tracer), ApplicationFactory.MAX_DRIVERS);
         const connections = new ConnectionManager(registry, cache);
         const drivers = new DriverProvider(registry, cache, QUERY_TOOLS);
-        const tools = this.createTools(connections, drivers);
-        return new McpDbServer(tools, cache, this.logger, this.versionLoader.load());
+        const tools = this.createTools(connections, drivers, callLog.viewerStatus);
+        const server = new McpDbServer(tools, cache, this.logger, callLog.observer, callLog.services, this.versionLoader.load());
+        this.server = server;
+        return server;
+    }
+    /**
+     * The call log when DB_LOG or DB_LOG_FILE asks for it, silent stand-ins
+     * otherwise. One CallLogger plays both roles, observer for the tools and
+     * tracer for the drivers, which is what lets it nest each driver statement
+     * under the call that caused it.
+     */
+    createCallLog(settings, registry) {
+        if (!settings.enabled) {
+            return { observer: new SilentObserver(), tracer: new SilentTracer(), services: [], viewerStatus: () => null };
+        }
+        const channels = [];
+        const services = [];
+        let viewer = null;
+        const outputs = [];
+        const sink = settings.file ? new FileSink(settings.file) : new StderrSink();
+        if (settings.text) {
+            const formatter = settings.format === "json" ? new JsonLogFormatter() : new PrettyLogFormatter();
+            channels.push(new TextLogChannel(sink, formatter));
+            outputs.push(`${settings.format} text to ${sink.description}`);
+        }
+        // The viewer reads the folder when there is one, which also shows the
+        // calls of every other copy of the server saving there, and otherwise
+        // keeps this process's recent entries in memory.
+        let store;
+        if (settings.directory) {
+            const folderStore = new FolderLogStore(settings.directory);
+            store = folderStore;
+            channels.push(new FolderLogChannel(settings.directory, (entry) => folderStore.noteWritten(entry)));
+            outputs.push(`one JSON file per entry in ${settings.directory}`);
+        }
+        else {
+            const memoryStore = new MemoryLogStore(settings.viewerHistory);
+            store = memoryStore;
+            if (settings.viewerPort !== null) {
+                channels.push(memoryStore);
+            }
+        }
+        if (settings.viewerPort !== null) {
+            // Always all interfaces, as configured: reachable from other machines
+            // and from a Docker host without extra settings. The viewer announces
+            // that it has no access control when it starts, which is on the first
+            // tool call rather than here.
+            viewer = new LiveLogViewer("0.0.0.0", settings.viewerPort, store, this.logger);
+            services.push(viewer);
+        }
+        const logger = new CallLogger(channels, () => {
+            const target = registry.getActiveTarget();
+            return target
+                ? `${registry.getActiveName()} (${EngineCatalog.label(target.engine)}) ${target.describe()}`
+                : null;
+        }, this.logger, () => this.clientName());
+        // Said once at startup, because with logging on every query and every
+        // result is being written somewhere, and the operator should know where.
+        this.logger(`call logging on: every tool call, its statements and its full output are written as ${outputs.join(" and ")}`);
+        const fallback = outputs.length > 0 ? outputs.join(" and ") : "nowhere else";
+        const observer = viewer ? new LiveViewerObserver(logger, viewer, fallback, this.logger) : logger;
+        return {
+            observer,
+            tracer: logger,
+            services,
+            viewerStatus: () => (viewer ? this.describeViewer(viewer) : null),
+        };
+    }
+    clientName() {
+        return this.server?.clientName() ?? null;
+    }
+    /** One line for current_connection. */
+    describeViewer(viewer) {
+        const status = viewer.status;
+        switch (status.state) {
+            case "running":
+                return `running at ${status.url}`;
+            case "unavailable":
+                return `unavailable, ${status.reason} (free it or set DB_LOG_PORT to another port)`;
+            case "idle":
+                return "starts on the first tool call";
+        }
     }
     /** One factory per engine. None of them does I/O; drivers connect on first use. */
-    createDriverRegistry(tuning) {
+    createDriverRegistry(tuning, tracer) {
         return new DriverRegistry()
-            .register("mysql", (target) => new MySqlDriver(target, tuning, this.logger))
-            .register("postgres", (target) => new PostgresDriver(target, tuning))
-            .register("sqlite", (target) => new SqliteDriver(target, tuning))
-            .register("mssql", (target) => new MsSqlDriver(target, tuning))
-            .register("clickhouse", (target) => new ClickHouseDriver(target, tuning))
-            .register("mongodb", (target) => new MongoDriver(target, tuning))
-            .register("redis", (target) => new RedisDriver(target, tuning, this.logger))
-            .register("elasticsearch", (target) => new ElasticsearchDriver(target, tuning));
+            .register("mysql", (target) => new MySqlDriver(target, tuning, tracer, this.logger))
+            .register("postgres", (target) => new PostgresDriver(target, tuning, tracer))
+            .register("sqlite", (target) => new SqliteDriver(target, tuning, tracer))
+            .register("mssql", (target) => new MsSqlDriver(target, tuning, tracer))
+            .register("clickhouse", (target) => new ClickHouseDriver(target, tuning, tracer))
+            .register("mongodb", (target) => new MongoDriver(target, tuning, tracer))
+            .register("redis", (target) => new RedisDriver(target, tuning, tracer, this.logger))
+            .register("elasticsearch", (target) => new ElasticsearchDriver(target, tuning, tracer));
     }
-    createTools(connections, drivers) {
+    createTools(connections, drivers, viewerStatus) {
         const names = new NamePolicyRegistry();
         const targetFactory = new ConnectionTargetFactory();
         const rows = new RowFormatter();
         const mongoGuard = new MongoOperatorGuard();
         const tools = [
-            new CurrentConnectionTool(connections),
+            new CurrentConnectionTool(connections, viewerStatus),
             new ListConnectionsTool(connections),
             new ListDatabasesTool(drivers),
             new UseDatabaseTool(connections, names),

package/dist/cli/ViewerCommand.js

@@ -0,0 +1,117 @@
+import { mkdirSync } from "node:fs";
+import { resolve } from "node:path";
+import { FolderLogStore } from "../logging/store/FolderLogStore.js";
+import { LiveLogViewer } from "../logging/viewer/LiveLogViewer.js";
+/**
+ * `mcp-db-read-only viewer --dir <folder> [--port 4800] [--host 0.0.0.0]`
+ *
+ * The live log viewer on its own, with no MCP server, no database and no
+ * credentials: it only reads the log folder that MCP servers configured with
+ * DB_LOG_DIR write into, and serves the same page as DB_LOG_PORT does.
+ *
+ * Run separately, in a terminal, so the servers an MCP client starts stay as
+ * light as they can be and never compete for a port. It shows the calls of
+ * every copy of the server writing to the folder, across restarts.
+ *
+ * Unlike the in-server viewer, it binds at once and exits if it cannot: here
+ * a person is watching the terminal, so a clear error and a non-zero exit is
+ * the useful answer to a taken port, where inside an MCP server it would have
+ * cost the chat its tools.
+ */
+export class ViewerCommand {
+    output;
+    env;
+    static DEFAULT_PORT = 4800;
+    static DEFAULT_HOST = "0.0.0.0";
+    static USAGE = [
+        "Usage: mcp-db-read-only viewer --dir <folder> [--port <port>] [--host <address>]",
+        "",
+        "Serves the live log viewer for a log folder written by MCP servers run with DB_LOG_DIR.",
+        "",
+        `  --dir, -d    The log folder (required; DB_LOG_DIR is used when omitted)`,
+        `  --port, -p   Port to listen on (default ${ViewerCommand.DEFAULT_PORT})`,
+        `  --host       Address to listen on (default ${ViewerCommand.DEFAULT_HOST}, every interface)`,
+        "  --help, -h   Show this help",
+        "",
+        "The viewer has no access control: anyone who can reach the port can read the log.",
+    ].join("\n");
+    constructor(output = {
+        out: (message) => process.stdout.write(`${message}\n`),
+        error: (message) => process.stderr.write(`${message}\n`),
+    }, env = process.env) {
+        this.output = output;
+        this.env = env;
+    }
+    /** Pure: argument text in, options or an exit out. */
+    parse(args) {
+        let directory = this.env.DB_LOG_DIR ?? "";
+        let port = ViewerCommand.DEFAULT_PORT;
+        let host = ViewerCommand.DEFAULT_HOST;
+        for (let index = 0; index < args.length; index += 1) {
+            const [flag, inline] = args[index].split(/=(.*)/s, 2);
+            const value = () => inline ?? args[++index];
+            switch (flag) {
+                case "--help":
+                case "-h":
+                    return { kind: "exit", code: 0, message: ViewerCommand.USAGE };
+                case "--dir":
+                case "-d":
+                    directory = value() ?? "";
+                    break;
+                case "--port":
+                case "-p": {
+                    const text = value() ?? "";
+                    const parsed = Number(text);
+                    if (!/^\d+$/.test(text) || parsed < 1 || parsed > 65535) {
+                        return { kind: "exit", code: 2, message: `--port must be a number from 1 to 65535, got "${text}".\n\n${ViewerCommand.USAGE}` };
+                    }
+                    port = parsed;
+                    break;
+                }
+                case "--host":
+                    host = value() ?? "";
+                    break;
+                default:
+                    return { kind: "exit", code: 2, message: `Unknown option "${args[index]}".\n\n${ViewerCommand.USAGE}` };
+            }
+        }
+        if (!directory) {
+            return { kind: "exit", code: 2, message: `--dir is required: the folder your MCP servers write with DB_LOG_DIR.\n\n${ViewerCommand.USAGE}` };
+        }
+        if (!host) {
+            return { kind: "exit", code: 2, message: `--host needs an address.\n\n${ViewerCommand.USAGE}` };
+        }
+        return { kind: "run", options: { directory: resolve(directory), port, host } };
+    }
+    /** @returns the exit code: 0 after a clean shutdown, non-zero when it could not start. */
+    async run(args) {
+        const parsed = this.parse(args);
+        if (parsed.kind === "exit") {
+            (parsed.code === 0 ? this.output.out : this.output.error)(parsed.message);
+            return parsed.code;
+        }
+        const { directory, port, host } = parsed.options;
+        // Created if missing, owner-only, so the viewer can be started before the
+        // first call is ever logged.
+        mkdirSync(directory, { recursive: true, mode: 0o700 });
+        const viewer = new LiveLogViewer(host, port, new FolderLogStore(directory), (message) => this.output.out(message));
+        const status = await viewer.ensureRunning();
+        if (status.state !== "running") {
+            const reason = status.state === "unavailable" ? status.reason : "it could not start";
+            this.output.error(`Could not start the viewer: ${reason}. Free that port, or choose another with --port.`);
+            await viewer.stop();
+            return 1;
+        }
+        // The in-server viewer never holds its process open; here it is the
+        // whole point of the process.
+        viewer.holdProcessOpen();
+        this.output.out(`Reading ${directory}. Press Ctrl+C to stop.`);
+        return new Promise((done) => {
+            const stop = () => {
+                void viewer.stop().then(() => done(0));
+            };
+            process.once("SIGINT", stop);
+            process.once("SIGTERM", stop);
+        });
+    }
+}

package/dist/config/EnvironmentConfigLoader.js

@@ -1,3 +1,4 @@
+import { resolve } from "node:path";
 import { ConnectionProfile } from "../domain/ConnectionProfile.js";
 import { ConnectionTargetFactory } from "../connections/ConnectionTargetFactory.js";
 /**
@@ -30,6 +31,7 @@ export class EnvironmentConfigLoader {
     targetFactory;
     static DEFAULT_QUERY_TIMEOUT_MS = 30000;
     static DEFAULT_CONNECT_TIMEOUT_MS = 10000;
+    static DEFAULT_VIEWER_HISTORY = 500;
     constructor(env = process.env, targetFactory = new ConnectionTargetFactory()) {
         this.env = env;
         this.targetFactory = targetFactory;
@@ -46,9 +48,65 @@ export class EnvironmentConfigLoader {
             defaultProfileName: this.env.DB_DEFAULT_PROFILE || this.env.MYSQL_DEFAULT_PROFILE || null,
             queryTimeoutMs: this.readTimeout(this.env.DB_QUERY_TIMEOUT_MS ?? this.env.MYSQL_QUERY_TIMEOUT_MS, EnvironmentConfigLoader.DEFAULT_QUERY_TIMEOUT_MS),
             connectTimeoutMs: this.readTimeout(this.env.DB_CONNECT_TIMEOUT_MS ?? this.env.MYSQL_CONNECT_TIMEOUT_MS, EnvironmentConfigLoader.DEFAULT_CONNECT_TIMEOUT_MS),
+            logging: this.readLogging(warnings),
             warnings,
         };
     }
+    /**
+     * DB_LOG=true logs text to stderr; DB_LOG_FILE=/path logs text to that
+     * file. DB_LOG_DIR=/folder saves every entry as its own JSON file there.
+     * Each of the three turns logging on by itself, and they combine.
+     * DB_LOG_FORMAT picks pretty (the default) or json for the text output.
+     *
+     * Relative paths are made absolute here, against the directory the server
+     * was started in, so the startup message names the real location.
+     */
+    readLogging(warnings) {
+        const file = this.env.DB_LOG_FILE ? resolve(this.env.DB_LOG_FILE) : null;
+        const directory = this.env.DB_LOG_DIR ? resolve(this.env.DB_LOG_DIR) : null;
+        const stderr = ["true", "1", "yes", "on"].includes((this.env.DB_LOG ?? "").toLowerCase());
+        const text = stderr || file !== null;
+        const enabled = text || directory !== null;
+        const requested = (this.env.DB_LOG_FORMAT ?? "").toLowerCase();
+        let format = "pretty";
+        if (requested === "json") {
+            format = "json";
+        }
+        else if (requested && requested !== "pretty") {
+            warnings.push(`DB_LOG_FORMAT="${this.env.DB_LOG_FORMAT}" is not pretty or json, using pretty.`);
+        }
+        return { enabled, text, file, directory, format, ...this.readViewer(enabled, warnings) };
+    }
+    /**
+     * DB_LOG_PORT starts the live browser viewer, but only while logging is on:
+     * the viewer shows the call log, so without one it has nothing to show, and
+     * it says so rather than silently doing nothing.
+     */
+    readViewer(loggingEnabled, warnings) {
+        const history = this.readCount(this.env.DB_LOG_HISTORY, EnvironmentConfigLoader.DEFAULT_VIEWER_HISTORY);
+        const raw = this.env.DB_LOG_PORT;
+        if (!raw) {
+            return { viewerPort: null, viewerHistory: history };
+        }
+        const port = Number(raw);
+        if (!/^\d+$/.test(raw) || port < 1 || port > 65535) {
+            warnings.push(`DB_LOG_PORT="${raw}" is not a port from 1 to 65535, so the live viewer is off.`);
+            return { viewerPort: null, viewerHistory: history };
+        }
+        if (!loggingEnabled) {
+            warnings.push("DB_LOG_PORT is set but call logging is off. Set DB_LOG_DIR, DB_LOG=true or DB_LOG_FILE to use the live viewer.");
+            return { viewerPort: null, viewerHistory: history };
+        }
+        return { viewerPort: port, viewerHistory: history };
+    }
+    /** A non-negative integer, or the fallback. 0 is allowed and means none. */
+    readCount(value, fallback) {
+        if (value === undefined || value === "") {
+            return fallback;
+        }
+        const parsed = Number(value);
+        return Number.isInteger(parsed) && parsed >= 0 ? parsed : fallback;
+    }
     /**
      * DB_PROFILES: `{"name": "url"}` or `{"name": {"url": "...", "password": "..."}}`.
      *

package/dist/drivers/BaseDriver.js

@@ -7,11 +7,16 @@ import { UnsupportedOperationError } from "../errors/UnsupportedOperationError.j
  * The two optional capabilities, indexes and foreign keys, default to a
  * refusal here, so an engine without them needs no code to say so, and an
  * engine that has them overrides the one method.
+ *
+ * Every statement a driver sends goes through `traced`, which reports it to
+ * the call log when logging is on and is a plain call when it is off.
  */
 export class BaseDriver {
     target;
-    constructor(target) {
+    tracer;
+    constructor(target, tracer) {
         this.target = target;
+        this.tracer = tracer;
     }
     async listIndexes(_name) {
         throw new UnsupportedOperationError(this.label, "indexes to list");
@@ -19,6 +24,10 @@ export class BaseDriver {
     async listForeignKeys(_name) {
         throw new UnsupportedOperationError(this.label, "foreign keys");
     }
+    /** Run one statement through the tracer, labelled with this engine. */
+    traced(text, params, run, describe) {
+        return this.tracer.trace(this.label, { text, params }, run, describe);
+    }
     get label() {
         return EngineCatalog.label(this.target.engine);
     }

package/dist/drivers/document/MongoDriver.js

@@ -25,8 +25,8 @@ export class MongoDriver extends BaseDriver {
     static SYSTEM_DATABASES = new Set(["admin", "local", "config"]);
     static SCHEMA_SAMPLE_SIZE = 100;
     client;
-    constructor(target, tuning, stages = new MongoStageAllowlist(), sampler = new MongoSchemaSampler()) {
-        super(target);
+    constructor(target, tuning, tracer, stages = new MongoStageAllowlist(), sampler = new MongoSchemaSampler()) {
+        super(target, tracer);
         this.tuning = tuning;
         this.stages = stages;
         this.sampler = sampler;
@@ -34,7 +34,8 @@ export class MongoDriver extends BaseDriver {
     }
     async verify() {
         const { client } = await this.client.get();
-        await client.db(this.target.database || "admin").command({ ping: 1 });
+        const database = this.target.database || "admin";
+        await this.traced(`${database}.ping`, undefined, () => client.db(database).command({ ping: 1 }), () => "ok");
     }
     close() {
         return this.client.close();
@@ -45,7 +46,7 @@ export class MongoDriver extends BaseDriver {
      */
     async listDatabases() {
         const { client } = await this.client.get();
-        const result = await client.db("admin").admin().listDatabases({ nameOnly: true, authorizedDatabases: true });
+        const result = await this.traced("admin.listDatabases", { nameOnly: true, authorizedDatabases: true }, () => client.db("admin").admin().listDatabases({ nameOnly: true, authorizedDatabases: true }), (answer) => `${answer.databases.length} databases`);
         return result.databases.map((entry) => ({
             name: entry.name,
             system: MongoDriver.SYSTEM_DATABASES.has(entry.name),
@@ -53,22 +54,18 @@ export class MongoDriver extends BaseDriver {
     }
     async listObjects(pattern, limit) {
         const database = await this.database();
-        const collections = await database
-            .listCollections({}, { nameOnly: true, authorizedCollections: true })
-            .toArray();
+        const collections = await this.traced(`${database.databaseName}.listCollections`, undefined, () => database.listCollections({}, { nameOnly: true, authorizedCollections: true }).toArray());
         return new GlobPattern(pattern).apply(collections.map((entry) => entry.name).sort(), limit);
     }
     /** The inferred shape of a sample, plus any JSON Schema validator the collection declares. */
     async describeObject(name) {
         const database = await this.database();
-        const [info] = await database.listCollections({ name }).toArray();
+        const [info] = await this.traced(`${database.databaseName}.listCollections`, { name }, () => database.listCollections({ name }).toArray());
         if (!info) {
             throw new ObjectNotFoundError(this.objectNoun, name);
         }
-        const documents = await database
-            .collection(name)
-            .aggregate([{ $sample: { size: MongoDriver.SCHEMA_SAMPLE_SIZE } }], { maxTimeMS: this.tuning.queryTimeoutMs })
-            .toArray();
+        const sampling = [{ $sample: { size: MongoDriver.SCHEMA_SAMPLE_SIZE } }];
+        const documents = await this.traced(`${database.databaseName}.${name}.aggregate`, sampling, () => database.collection(name).aggregate(sampling, { maxTimeMS: this.tuning.queryTimeoutMs }).toArray());
         return {
             collection: name,
             sampled_documents: documents.length,
@@ -79,7 +76,7 @@ export class MongoDriver extends BaseDriver {
     async listIndexes(name) {
         await this.assertCollection(name);
         const database = await this.database();
-        return database.collection(name).indexes();
+        return this.traced(`${database.databaseName}.${name}.indexes`, undefined, () => database.collection(name).indexes());
     }
     async sample(name, limit) {
         await this.assertCollection(name);
@@ -95,7 +92,8 @@ export class MongoDriver extends BaseDriver {
             skip: request.skip,
             maxTimeMS: this.tuning.queryTimeoutMs,
         });
-        return this.toJson(bson, await cursor.toArray());
+        const documents = await this.traced(`${database.databaseName}.${collection}.find`, request, () => cursor.toArray());
+        return this.toJson(bson, documents);
     }
     /**
      * Reads at most `limit + 1` documents and closes the cursor, so a pipeline
@@ -112,32 +110,31 @@ export class MongoDriver extends BaseDriver {
             batchSize: limit + 1,
         });
         const rows = [];
-        try {
-            for await (const document of cursor) {
-                rows.push(document);
-                if (rows.length > limit) {
-                    break;
+        await this.traced(`${database.databaseName}.${collection}.aggregate`, pipeline, async () => {
+            try {
+                for await (const document of cursor) {
+                    rows.push(document);
+                    if (rows.length > limit) {
+                        break;
+                    }
                 }
             }
-        }
-        finally {
-            await cursor.close();
-        }
+            finally {
+                await cursor.close();
+            }
+            return rows;
+        });
         return { rows: this.toJson(bson, rows.slice(0, limit)), truncated: rows.length > limit };
     }
     async count(collection, filter) {
         const { bson } = await this.client.get();
         const database = await this.database();
-        return database
-            .collection(collection)
-            .countDocuments(this.fromJson(bson, filter), { maxTimeMS: this.tuning.queryTimeoutMs });
+        return this.traced(`${database.databaseName}.${collection}.countDocuments`, filter, () => database.collection(collection).countDocuments(this.fromJson(bson, filter), { maxTimeMS: this.tuning.queryTimeoutMs }));
     }
     async distinct(collection, field, filter) {
         const { bson } = await this.client.get();
         const database = await this.database();
-        const values = await database
-            .collection(collection)
-            .distinct(field, this.fromJson(bson, filter), { maxTimeMS: this.tuning.queryTimeoutMs });
+        const values = await this.traced(`${database.databaseName}.${collection}.distinct`, { field, filter }, () => database.collection(collection).distinct(field, this.fromJson(bson, filter), { maxTimeMS: this.tuning.queryTimeoutMs }));
         return this.toJson(bson, values);
     }
     async database() {
@@ -146,7 +143,7 @@ export class MongoDriver extends BaseDriver {
     }
     async assertCollection(name) {
         const database = await this.database();
-        const found = await database.listCollections({ name }, { nameOnly: true }).toArray();
+        const found = await this.traced(`${database.databaseName}.listCollections`, { name }, () => database.listCollections({ name }, { nameOnly: true }).toArray());
         if (found.length === 0) {
             throw new ObjectNotFoundError(this.objectNoun, name);
         }

package/dist/drivers/keyvalue/RedisDriver.js

@@ -25,8 +25,8 @@ export class RedisDriver extends BaseDriver {
     /** Long strings are cut in samples; the length is reported so nothing is hidden silently. */
     static MAX_STRING_PREVIEW = 4096;
     client;
-    constructor(target, tuning, logger, guard = new RedisCommandFlagsGuard()) {
-        super(target);
+    constructor(target, tuning, tracer, logger, guard = new RedisCommandFlagsGuard()) {
+        super(target, tracer);
         this.tuning = tuning;
         this.logger = logger;
         this.guard = guard;
@@ -111,9 +111,12 @@ export class RedisDriver extends BaseDriver {
                 return { key: name, type, note: "No sample reader for this type; use redis_command." };
         }
     }
+    /**
+     * The guard's COMMAND INFO lookups go through `call` too, so the log shows
+     * the server being asked before the command itself is sent.
+     */
     async command(name, args) {
-        const client = await this.client.get();
-        const call = (command, ...rest) => client.call(command, ...rest);
+        const call = (command, ...rest) => this.call(command, ...rest);
         const subcommand = this.isContainer(name) ? args[0]?.toUpperCase() : undefined;
         await this.guard.assertReadOnly(call, name, subcommand);
         return call(name, ...args);
@@ -172,9 +175,21 @@ export class RedisDriver extends BaseDriver {
     isContainer(name) {
         return ["OBJECT", "MEMORY", "XINFO"].includes(name);
     }
+    /** Every command this driver sends passes through here, so every one is traced. */
     async call(command, ...args) {
         const client = await this.client.get();
-        return client.call(command, ...args);
+        return this.traced([command, ...args].join(" "), undefined, () => client.call(command, ...args), RedisDriver.describeReply);
+    }
+    /** Arrays by length, short scalars by value, so `GET` and `DBSIZE` read naturally in the log. */
+    static describeReply(reply) {
+        if (Array.isArray(reply)) {
+            return `${reply.length} item${reply.length === 1 ? "" : "s"}`;
+        }
+        if (reply === null) {
+            return "nil";
+        }
+        const text = String(reply);
+        return text.length <= 40 ? text : `${text.length} characters`;
     }
     databaseIndex() {
         const parsed = Number.parseInt(this.target.database, 10);

package/dist/drivers/search/ElasticsearchDriver.js

@@ -18,10 +18,10 @@ export class ElasticsearchDriver extends BaseDriver {
     tuning;
     fetcher;
     family = "search";
-    constructor(target, tuning, 
+    constructor(target, tuning, tracer, 
     // Wrapped so fetch is never invoked with this driver as its receiver.
     fetcher = (input, init) => fetch(input, init)) {
-        super(target);
+        super(target, tracer);
         this.tuning = tuning;
         this.fetcher = fetcher;
     }
@@ -80,13 +80,17 @@ export class ElasticsearchDriver extends BaseDriver {
     }
     async send(request, timeoutMs = this.tuning.queryTimeoutMs) {
         const { method, path, body } = this.route(request);
-        const response = await this.fetcher(`${this.baseUrl()}${path}`, {
-            method,
-            headers: this.headers(),
-            body: body === undefined ? undefined : JSON.stringify(body),
-            signal: AbortSignal.timeout(timeoutMs),
-        });
-        const text = await response.text();
+        // Traced as the request line, with the body as its parameters. The
+        // authorization header is never part of what is traced.
+        const { response, text } = await this.traced(`${method} ${path}`, body, async () => {
+            const answer = await this.fetcher(`${this.baseUrl()}${path}`, {
+                method,
+                headers: this.headers(),
+                body: body === undefined ? undefined : JSON.stringify(body),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            return { response: answer, text: await answer.text() };
+        }, (result) => `HTTP ${result.response.status}`);
         const parsed = text ? this.parse(text) : null;
         if (response.status === 404 && request.kind !== "cluster" && request.kind !== "indices") {
             throw new ObjectNotFoundError(this.objectNoun, request.index);

package/dist/drivers/sql/ClickHouseDriver.js

@@ -29,8 +29,8 @@ export class ClickHouseDriver extends BaseDriver {
      */
     static MAX_RESULT_ROWS = 10000;
     client;
-    constructor(target, tuning) {
-        super(target);
+    constructor(target, tuning, tracer) {
+        super(target, tracer);
         this.tuning = tuning;
         this.client = new LazyResource(() => this.open(), (opened) => opened.client.close());
     }
@@ -77,13 +77,15 @@ export class ClickHouseDriver extends BaseDriver {
     }
     async run(sql, params) {
         const { client, settings } = await this.client.get();
-        const result = await client.query({
-            query: sql,
-            format: "JSONEachRow",
-            query_params: params,
-            clickhouse_settings: settings,
+        return this.traced(sql, params, async () => {
+            const result = await client.query({
+                query: sql,
+                format: "JSONEachRow",
+                query_params: params,
+                clickhouse_settings: settings,
+            });
+            return (await result.json());
         });
-        return (await result.json());
     }
     async assertExists(database, table) {
         const rows = await this.run("SELECT 1 AS found FROM system.tables WHERE database = {database:String} AND name = {table:String}", { database, table });
@@ -133,11 +135,8 @@ export class ClickHouseDriver extends BaseDriver {
      * attaching any is exactly what a read-only account refuses.
      */
     async negotiateSettings(client) {
-        const result = await client.query({
-            query: "SELECT toUInt8(getSetting('readonly')) AS readonly",
-            format: "JSONEachRow",
-        });
-        const rows = (await result.json());
+        const probe = "SELECT toUInt8(getSetting('readonly')) AS readonly";
+        const rows = (await this.traced(probe, undefined, async () => (await client.query({ query: probe, format: "JSONEachRow" })).json()));
         const level = Number(rows[0]?.readonly ?? 0);
         const limits = {
             max_execution_time: Math.max(1, Math.ceil(this.tuning.queryTimeoutMs / 1000)),