All jobs

Add Structured Logging to a Socket.IO Server

Yes. An agent replaces console output in your Socket.IO server with pino JSON lines for connections, messages, recovery and workers, tests it and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads the whole server, which in an app laid out like socketio/chat-example is one file. index.js forks one worker per availableParallelism() from the cluster primary with PORT set to 3000 + i, calls setupPrimary() from @socket.io/cluster-adapter, and in each worker opens chat.db with sqlite, creates a messages table with a unique client_offset, serves index.html from Express, and builds the Server with connectionStateRecovery: {} and the cluster adapter. The chat message handler inserts the content with its client offset, treats errno === 19 (a SQLITE_CONSTRAINT on a repeated offset) as an already-delivered message and acknowledges it, and otherwise emits the message with result.lastID. A reconnecting socket whose state could not be recovered replays rows above socket.handshake.auth.serverOffset. The one log line is console.log on server.listen; the catch blocks swallow their errors with a comment. package.json is type: module with socket.io ^4.7.2, express ^4.18.2, sqlite ^5.0.1 and sqlite3 ^5.1.6, which package-lock.json resolves to 4.7.2, 4.18.2, 5.0.1 and 5.1.6, a single start script and no tests; .codesandbox/Dockerfile runs it on node:20.

The agent adds pino and writes logger.js, which creates one logger with level from LOG_LEVEL and base fields for the process: pid, the cluster worker id when there is one, and port. In development (NODE_ENV not production) it attaches pino-pretty as a transport, which pino runs in a worker thread; in production the lines go to stdout as JSON for whatever collects them. The primary logs each fork and gains a cluster.on('exit') handler that logs the worker id, exit code and signal, which the current code does not watch at all. Each worker logs server.listen with its port, replacing the only console.log.

The Socket.IO events are the point, and each line carries ids rather than content. io.on('connection') logs socket.id, socket.recovered, the client's serverOffset and socket.handshake.address at info; socket.on('disconnect', reason) logs the reason. In the chat message handler the successful insert logs id and the byte length of the content at info, the SQLITE_CONSTRAINT path logs the duplicate clientOffset at debug, and the other failure, which the code now ignores, logs the error at error with its errno and code. The replay path logs how many rows it sent and from which offset, and its catch logs the error instead of swallowing it. Engine-level failures are reachable too: io.engine.on('connection_error', err) logs err.code, err.message and err.context, which is where a bad handshake or a transport error shows up. Message text is never logged, and the pull request says so.

With no test runner in the repository the agent uses Node's built-in node:test, available on the Node 20 the sandbox image names, and adds socket.io-client as a dev dependency. To make the worker testable it moves the per-worker setup into app.js, exporting a createApp({ db, logger }) that returns app, server and io, and leaves the cluster wiring in index.js. The test opens an in-memory SQLite, passes a pino instance writing to an array, starts the server on port 0, connects a client, sends chat message with an offset twice, and asserts that the lines include one connection with recovered: false, one insert with an id, one debug duplicate, and no field containing the message text. It adds a test script and runs npm test and npm start in the sandbox, pasting a few pretty-printed and a few raw JSON lines into the pull request.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add structured logging to this Socket.IO and Express chat server. Read package.json, package-lock.json, index.js, index.html, .codesandbox/Dockerfile and .gitignore first. Add pino and a logger.js that sets the level from LOG_LEVEL, adds pid, cluster worker id and port as base fields, and uses pino-pretty as a transport outside production. Move the per-worker setup into app.js exporting createApp({ db, logger }) that returns app, server and io, keeping the cluster primary in index.js. Log worker forks and exits in the primary, listen in each worker, connection with socket id, recovered flag, client serverOffset and address, disconnect with its reason, the insert with its id and content length, the SQLITE_CONSTRAINT duplicate at debug, any other insert error at error with errno and code, the replay count and offset, and engine connection_error events. Never log message text. Add socket.io-client as a dev dependency and a node:test suite that starts the server on port 0 with an in-memory database and a pino instance writing to an array, sends the same message twice and asserts the lines. Add a test script, run npm test and npm start, and open a pull request that quotes the output and shows a few log lines in both formats.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

The pull request adds logger.js, app.js and test/logging.test.js, and changes index.js (the cluster primary with its exit handler, the worker calling createApp), package.json (pino, pino-pretty, socket.io-client, the test script) and package-lock.json. Its description quotes the node --test output and shows the lines one connection, one message and one duplicate produce, first pretty-printed and then as the raw JSON production would emit.

A reviewer checks the level of each line against their volume (a busy chat makes the per-message info line the loudest thing in the log, and dropping it to debug is a one-word change), that the base fields are enough to tell workers apart in their collector, and that the connection_error handler does not log anything a client controls beyond code and message.

The protocol is untouched: the client in index.html sends the same chat message event with the same offset and acknowledgement, and recovery works as before. Only the server's output changes.

Run it on every new Socket.IO service

The usual regression is a console.log added during a debugging session that stays. An automation on the Project with a schedule trigger set to every: 1d runs read-only with a prompt that searches the server files for console. calls and for catch blocks with no logging, and comments on the latest commit with the file and line of each. It runs as the member who last changed it, and its max_runs_per_hour is shared across its triggers.

For a new service that needs the same treatment, a handler on your own server sends this body to POST /o/{org}/sessions with that repository in resources and a request_id that is a UUID v5 of the repository's full name, so running the onboarding script twice starts one run per service rather than two. Each run's run.completed arrives at the key's webhook_url with its pull request URL.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

Logging decisions are about what the lines look like under real traffic, so the agent starts the clustered server in its own sandbox, connects a client, sends messages, kills a worker and keeps the resulting lines in the run's record. A reviewer reads the JSON a collector would receive rather than a description of fields.

A chat server is rarely alone; presence, notifications and the API next to it all want the same base fields and levels so one query in the log tool spans them. One run per repository applies the same logger.js shape to each, with that service's own events, and opens one pull request each.

Frequently asked questions

Why pino?

It writes one JSON object per line with no formatting cost on the request path, moves pretty-printing to a worker thread, and takes base fields once at creation, which is exactly what the cluster primary and workers need. The repository has no logger today, so there is nothing to migrate from.

Does it log what people type?

No. The message line carries the row id and the content's byte length, the duplicate line carries the client offset, and the test asserts that no emitted line contains the text it sent. Content belongs in chat.db, not in logs.

What happens to the swallowed errors?

They are logged now. The insert catch keeps treating SQLITE_CONSTRAINT as a delivered duplicate, and logs any other error with its errno and code before letting the client retry; the replay catch logs the error instead of a comment.

Why split index.js into app.js?

The file runs the cluster primary at import time, so a test cannot load it without forking workers. createApp takes the database and the logger as arguments, which is what lets the test use an in-memory SQLite and capture lines in an array.

Does pino-pretty run in production?

No. The transport is attached only when NODE_ENV is not production, and pino-pretty is a dev dependency. Production writes raw JSON to stdout, which is what log collectors expect.

More Socket.IO jobs

The same job on other stacks

Keep reading