# Add Structured JSON Logging to a Ktor Server

Yes. An agent switches a Ktor app's Logback output to JSON with the Logstash encoder, adds a call id to every request line, tests it, and opens a pull request.

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

## What the agent does

The agent reads the application as it is. In a server shaped like the `kweet` sample in ktorio/ktor-samples it opens `build.gradle.kts` and finds the `io.ktor.plugin` at 3.6.0 on Kotlin 2.4.20, a Gradle 9.2.1 wrapper, `jvmToolchain(17)`, `ktor-server-call-logging` and `ktor-server-default-headers` among the server artifacts, `logback-classic` at the `logback_version` from `gradle.properties`, and tests on `ktor-server-test-host-jvm` with mockk. It reads `src/main/resources/logback.xml`, which has one `ConsoleAppender` with a plain pattern of timestamp, thread, level, logger and message at `INFO`, and `src/main/kotlin/io/ktor/samples/kweet/KweetApplication.kt`, where `mainWithDependencies` installs `CallLogging` with no configuration, so every request is logged as a single pattern line nobody can query by field.

The repository already contains the answer in another sample: `structured-logging` in the same monorepo depends on `net.logstash.logback:logstash-logback-encoder` at 9.0 and its `logback.xml` uses `LogstashEncoder` on the console appender. The agent follows that, adding the same artifact to `kweet/build.gradle.kts` and rewriting `logback.xml` so the console appender's encoder is `LogstashEncoder`, keeping the root level at `INFO`. Each log line becomes one JSON object with `@timestamp`, `level`, `logger_name`, `thread_name`, `message` and any MDC fields, which is what a log pipeline wants.

The MDC is what turns a request log into something you can follow. In `KweetApplication.kt` the agent configures the `CallLogging` block with `callIdMdc("call_id")` and installs `CallId` from `ktor-server-call-id`, generating an id when the request has no `X-Request-Id` and echoing it in the response header. It adds `mdc("method")` and `mdc("path")` entries from the call's request, so a line for `POST /post-new` or `/kweet/{id}/delete` carries both as fields. The hand-rolled `securityCode` helper and the Resources routes in `PostNew.kt`, `Delete.kt` and the others are untouched; only the plugin installation block changes.

Tests go next to the existing ones. `src/test/kotlin/KweetApplicationTest.kt` already builds the app with `testApplication` and a relaxed mockk `DAOFacade`, so the agent adds a case that sends `X-Request-Id: test-123` to `/` and asserts the same value comes back in the response header, and a case that a request without one gets a non-empty id. For the JSON shape it adds a small test that attaches a Logback `ListAppender` to the root logger, makes a request, and parses the captured line as JSON to assert `call_id` and `path` are present. It runs `./gradlew test` from the `kweet` directory with the sample's own wrapper, then opens a pull request.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add structured JSON logging to this Ktor server. Add the logstash-logback-encoder dependency and switch the console appender in logback.xml to LogstashEncoder at INFO. Install CallId with a generated id that honours X-Request-Id and echoes it in the response, and configure CallLogging with callIdMdc plus method and path MDC entries. Add tests for the echoed id, a generated id and the JSON fields on a captured log line. Run ./gradlew test and open a pull request.",
  "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

What comes back is a pull request on its own branch. The diff adds one line to `kweet/build.gradle.kts` for the encoder, one for `ktor-server-call-id`, rewrites `src/main/resources/logback.xml` around `LogstashEncoder`, changes the `CallLogging` installation in `KweetApplication.kt` and adds the `CallId` block beside it, and adds three cases to `src/test/kotlin/KweetApplicationTest.kt`. The description pastes one captured JSON log line so a reviewer sees the field names before deciding where to ship them.

The repository's own CI runs the proof again. `.github/workflows/build-all.yml` runs `./build-all.sh` on JDK 24 for every pull request to main, which builds and tests each sample including `kweet`, so the new cases execute there as well as in the sandbox. The session's trajectory at `GET /o/{org}/sessions/{id}/messages` keeps every `./gradlew test` invocation with its output.

Before merging, a reviewer checks that the root level is still `INFO` and no per-logger `trace` crept in from the other sample's config, that the generated id is used only when the caller sent none, and that the `path` MDC entry carries the matched route and not a raw query string that could hold form data. Nothing reaches main until the pull request merges.

## Run it on every service onboarded to the log pipeline

A team that moves its JVM services onto one log pipeline starts one run per repository with `POST /o/{org}/sessions`, this prompt and that repository in `resources`. Each run reads its own `logback.xml` and its own plugin block, so a service that already has `CallId` gets only the encoder and MDC changes, and each opens its own pull request. Send a `request_id` per run so a retry returns the run already started.

Set a `webhook_url` on the API key and every run the key starts posts `run.completed` or `run.failed` when it finishes, with a `session_url` for the result, so a script can collect the pull request links. The key runs at most `max_concurrent` sessions at once, 4 by default; beyond that a session is accepted as `202` with `status: "queued"`, starts oldest first when a slot frees, and holds up none of your other keys.

## Why run it on Rush?

The change is small and the verification is not: a Gradle daemon to warm, a JDK 17 toolchain to resolve, and a test that has to capture a real Logback line and parse it before anyone believes the field names. On Rush the run has its own sandbox with a computer in it, so the agent runs the sample's Gradle 9.2.1 wrapper as often as it needs and your own machine runs nothing.

The result is checkable rather than claimed. The pull request shows the encoder, the plugin block and the tests, the `build-all` workflow runs the sample's suite on the pull request, and the trajectory keeps every Gradle run with its output, including the captured JSON line. Several services mean several sandboxes and several pull requests at once.

## Frequently asked questions

### Why the Logstash encoder rather than a hand-written pattern?

Because a pattern that prints JSON breaks the moment a message contains a quote or a newline. `LogstashEncoder` escapes every field, adds the MDC automatically and is what the `structured-logging` sample in the same repository already uses, so the agent follows the pattern the maintainers chose.

### Does it change what gets logged, or only the format?

Both, slightly. The format becomes one JSON object per line, and each request line gains `call_id`, `method` and `path` fields from the MDC. The root level stays at `INFO`, so the volume is the same as before; only the shape changes.

### Will the id reach the client?

Yes. `CallId` is configured to echo the id in the `X-Request-Id` response header, and to reuse one the client sent, so a support ticket can quote the id and the log line can be found by it. One of the new tests sends `test-123` and asserts it comes back.

### How is the JSON output tested without reading stdout?

The test attaches a Logback `ListAppender` to the root logger for the duration of one request, then takes the captured event, runs it through the same encoder and parses the result as JSON. That proves the field names without depending on console capture in Gradle.

### Which JDK does it build with?

The sample's own: `jvmToolchain(17)` in `build.gradle.kts` and the Gradle 9.2.1 wrapper checked into `kweet/gradle/wrapper`. The repository's `build-all.yml` runs the same build on JDK 24, so the pull request is checked on both.

## More Ktor jobs

- [Dockerize a Ktor Server](https://getrush.ai/run/dockerize-app/ktor/)
- [Review Pull Requests on a Ktor Server](https://getrush.ai/run/review-pull-requests/ktor/)
- [Upgrade Ktor and Gradle Dependencies](https://getrush.ai/run/upgrade-gradle-dependencies/ktor/)

## The same job on other stacks

- [Add Structured Logging to a Leptos Axum App](https://getrush.ai/run/add-structured-logging/leptos/)
- [Add Structured Logging to a Litestar App](https://getrush.ai/run/add-structured-logging/litestar/)
- [Add Structured Logging to a Node.js App from a Linear Issue](https://getrush.ai/run/add-structured-logging/nodejs/)

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