# Add Structured JSON Logging to a Tokio Server

Yes. An agent switches your Tokio server's tracing output to JSON lines, adds a per-connection span with the peer address, keeps RUST_LOG filtering and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-structured-logging/tokio/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how the server logs before changing a line. In a Tokio server like tokio-rs/mini-redis, `Cargo.toml` depends on `tracing` and on `tracing-subscriber` with only the `env-filter` feature, and `src/bin/server.rs` installs the subscriber in `set_up_logging`: without the optional `otel` feature it is one call, `tracing_subscriber::fmt::try_init()`, which prints human-readable lines and reads `RUST_LOG`; with `otel` it builds a `Registry` with an OpenTelemetry layer, an `EnvFilter` and a plain `fmt::Layer`. The library already logs structurally in places: `src/server.rs` writes `debug!(?cmd)` for every parsed command inside `Handler::run`, which is marked `#[instrument(skip(self))]`, and each command's `apply` in `src/cmd/` is instrumented the same way and logs `debug!(?response)`. What is missing is the context: `skip(self)` leaves the `run` span with no fields, and the accept loop in `Listener::run` drops the peer address with `Ok((socket, _))`, so a line from a busy server says which command ran but never which client sent it.

The change keeps the shape the maintainers chose and adds what is missing. In `set_up_logging` the agent builds the subscriber through `tracing_subscriber::fmt()` with an `EnvFilter` that takes `RUST_LOG` and falls back to `info`, and switches the formatter to `.json()` when an environment variable such as `LOG_FORMAT=json` is set, with `flatten_event(true)` so a field like `cmd` is a top-level key rather than nested under `fields`, and `with_current_span(true)` so each line carries the span it was emitted in. The `json` feature is added to `tracing-subscriber` in `Cargo.toml`, and the `otel` path gains the same JSON option on its `fmt::Layer`. In `Listener::run` the accept loop reads `socket.peer_addr()` before spawning the handler task and wraps the task in `info_span!("connection", peer = %peer)` through `Instrument`, with a `debug!` at open and close, so every command line inherits the peer address in its `spans` list without touching `Handler::run` or the `cmd` modules.

Built and run with `LOG_FORMAT=json RUST_LOG=debug`, the server then writes one object per line: an `INFO` line for `accepting inbound connections` with `target` `mini_redis::server`, then for a client that sends `SET foo bar` and `GET foo` a `connection opened` line whose `span` holds the client's address and `connection` name, a line with `"cmd":"Set(Set { key: \"foo\", value: b\"bar\", expire: None })"` whose `spans` list reads `connection`, `run`, a line from `mini_redis::cmd::set` with `"response":"Simple(\"OK\")"` under `apply`, the matching pair for the `GET`, and `connection closed`. Without the variable the output is the same readable format as before, so `RUST_LOG=debug cargo run --bin mini-redis-server`, the line the README gives, still prints what it printed.

To check it, the agent runs `cargo build` and `cargo build --features otel`, then `cargo test` and `cargo test --features otel` as `.github/workflows/ci.yml` does, since the integration tests in `tests/server.rs` start the server through `server::run` on a random port and read raw frames, which a logging change must not disturb. It runs the binary with the variable set and a short client script that sends two commands, pipes the output through `jq` to show each line parses, and runs `cargo fmt --all --check`, the workflow's last step. The captured lines go into the pull request as they were written.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add structured JSON logging to this Tokio server. Read Cargo.toml for the tracing crates and their features, the binary's logging setup including any optional telemetry path, and where the library creates spans and logs fields; note any span that skips its fields and any place the peer address is discarded. Build the subscriber with an EnvFilter that reads RUST_LOG and falls back to info, switch the formatter to JSON lines with flattened event fields and the current span when an environment variable asks for it, and keep the readable format otherwise. Wrap each connection's task in a span that carries the peer address so every log line from that connection inherits it, without changing the command handlers. Run the builds and tests the CI workflow runs, including any feature variants, run the server with JSON on and a short client that sends two commands, show each output line parsing as JSON, run the formatter check, and open a pull request with the commands, their output and the captured log lines.",
  "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 changes `Cargo.toml`, `Cargo.lock`, the binary's logging setup and the accept loop in the server module, and no command handler. Its description shows the build and test output for both feature variants, the formatter check, and the JSON lines a two-command client produced, with the `spans` list visible on each so a reviewer can see the peer address reaching the command lines.

A reviewer checks the environment variable's name and default against the deployment's log pipeline and whether `flatten_event` matches what that pipeline indexes. After merging, a log collector receives one parseable object per line with the client address, the span path and the command on every entry, and a developer at a terminal still gets the readable lines the README promises.

## Run it on every Tokio server in the terminal

A developer who has just grepped a plain-text log for a client address sends this body from their own machine with the repository in `resources` and reads the pull request from the console when the webhook on their API key reports the run. A team with several Tokio services sends one request per repository, each with a `request_id` that is a UUID v5 of the repository's full name, so a script run twice returns the runs already started rather than a second set of pull requests.

Each run reads its own setup: a service that already uses a `Registry` with layers gets the JSON formatter as a layer beside the others, and one that already carries a request id in a span gets the peer address added to that span rather than a new one.

## Why run it on Rush?

Switching a formatter is one line; the value is in the audit around it, which spans skip their fields, where the peer address is dropped, which feature flags change the subscriber, and in proving the result by running the server and reading its output as JSON. The agent does that in its own sandbox, with the tests the CI workflow runs and the captured lines kept in the run's record, so the pull request shows the log a collector will receive rather than describing it.

It also keeps the maintainers' choices: the readable format stays the default, the telemetry feature keeps its layer stack, and the command modules stay untouched because the span wraps the task above them. Several services with several subscriber setups get several pull requests, each fitted to its own logging path.

## Frequently asked questions

### Will my terminal output change?

No. JSON is on only when the environment variable asks for it, and the readable formatter with `RUST_LOG` filtering stays the default, so the command the README gives prints what it printed. The pull request shows both outputs.

### Why wrap the connection task instead of adding a field to the handler's span?

The handler's `run` span is declared with `skip(self)` and the command spans are inside it, so a span above the task reaches every line from that connection at once, including the command handlers, without editing any of them. The JSON `spans` list shows the path from `connection` down to `apply`.

### Does it work with the OpenTelemetry feature?

Yes. The telemetry path already builds a `Registry` with a `fmt::Layer`, and the JSON option is applied to that layer in the same way, so the OTLP export and the JSON lines run side by side. The agent builds and tests with the feature on, as CI does.

### What about the tests?

The integration tests start the server through its `run` function and read raw frames from a socket, so a change to the subscriber and the span does not touch them. The agent runs the full suite with and without the optional feature to show that.

## More Tokio jobs

- [Add TLS to a Tokio TCP Server](https://getrush.ai/run/add-tls/tokio/)
- [Upgrade Cargo Dependencies Weekly for a Tokio Service](https://getrush.ai/run/upgrade-cargo-dependencies/tokio/)
- [Write Unit Tests for a Tokio Service](https://getrush.ai/run/write-unit-tests/tokio/)

## The same job on other stacks

- [Add Structured Logging to a tRPC API](https://getrush.ai/run/add-structured-logging/trpc/)
- [Add Structured JSON Logging to a Vapor App](https://getrush.ai/run/add-structured-logging/vapor/)
- [Add Structured Logging to an Actix Web App](https://getrush.ai/run/add-structured-logging/actix/)

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