# 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 Rush](https://cloud.getrush.ai/run/add-structured-logging/socket-io/). Opens 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`

```json
{
  "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.

## 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

- [Add a Typing Indicator to a Socket.IO Chat](https://getrush.ai/run/add-typing-indicator/socket-io/)
- [Convert a Socket.IO Chat Server to TypeScript](https://getrush.ai/run/convert-javascript-to-typescript/socket-io/)
- [Move a Socket.IO Chat From SQLite to PostgreSQL](https://getrush.ai/run/migrate-sqlite-to-postgres/socket-io/)

## The same job on other stacks

- [Add Structured Logging to a Temporal TypeScript Worker](https://getrush.ai/run/add-structured-logging/temporal/)
- [Add Structured JSON Logging to a Tokio Server](https://getrush.ai/run/add-structured-logging/tokio/)
- [Add Structured Logging to a tRPC API](https://getrush.ai/run/add-structured-logging/trpc/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
