All jobs

Add Request ID Logging to a Ktor Server

Yes. An agent installs Ktor's CallId and CallLogging plugins, echoes X-Request-Id, puts the id in every Logback line through the MDC, 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 how the server is assembled before it installs a plugin. In a service shaped like the postgres sample of ktorio/ktor-samples, build.gradle.kts applies io.ktor.plugin 3.6.0 with Kotlin 2.4.20, depends on ktor-server-core-jvm, ktor-server-content-negotiation-jvm, ktor-serialization-kotlinx-json-jvm, ktor-server-netty-jvm, ktor-server-config-yaml, logback-classic 1.5.21 and the postgresql 42.7.8 driver, with ktor-server-test-host-jvm and kotlin-test-junit for tests, on a Java 17 toolchain. application.yaml names the module com.example.PostgresApplicationKt.module on port 8080. PostgresApplication.kt calls configureSerialization() and then configureRouting(connectToPostgres(embedded = false)), which opens a JDBC connection from the values in postgres.yaml at startup. plugins/Routing.kt serves POST /articles, GET, PUT and DELETE /articles/{id} through ArticleService, and logback.xml prints %d [%thread] %-5level %logger{36} - %msg%n at trace level. There is no src/test directory.

It adds ktor-server-call-id-jvm and ktor-server-call-logging-jvm to the dependencies and writes plugins/Monitoring.kt with a configureMonitoring() function. CallId reads X-Request-Id from the request, generates a UUID when the header is missing, rejects a value that is empty or longer than a sane limit through verify, and writes the id back on the response with replyToHeader(HttpHeaders.XRequestId), so a client or gateway that sent its own id gets it back and one that did not can still quote the server's. CallLogging is installed with callIdMdc("call-id"), which puts the id into the SLF4J MDC for the whole call, and a filter so only /articles traffic is logged at INFO. logback.xml gains [%X{call-id}] after the level, so every line written during a request, including JDBC errors from ArticleService, carries the same id.

PostgresApplication.kt calls configureMonitoring() before configureRouting, so the plugins are in place before the first route. In Routing.kt the catch (cause: DbElementInsertException) branch responds 500 and logs nothing today; the agent adds a call.application.log.error there, which is now stamped with the id, so a failed insert can be found from the id a client reports. Because module() connects to Postgres as soon as it loads, the new test does not load the module: src/test/kotlin/com/example/CallIdTest.kt uses testApplication with its own application { configureSerialization(); configureMonitoring(); routing { get("/ping") { call.respondText("pong") } } } block. It asserts that a request with X-Request-Id: abc-123 gets abc-123 back, that a request without one gets a UUID-shaped header, and that an empty header is replaced rather than echoed. The test needs no database and runs under ./gradlew test.

Before pushing, the agent runs ./gradlew build, which is what the repository's build-all.sh runs for each sample in the Build All Samples workflow, starts Postgres with the databaseInstance task and ./gradlew run, sends two requests with curl -i, and pastes the response headers and the matching log lines into the pull request so a reviewer sees the id travel from header to log.

Start it with one API call

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

{
  "agent": "codex",
  "input": "Add request id logging to this Ktor server and open a pull request. Read build.gradle.kts, gradle.properties, src/main/resources/application.yaml, src/main/resources/logback.xml, src/main/kotlin/com/example/PostgresApplication.kt, src/main/kotlin/com/example/plugins/Routing.kt and src/main/kotlin/com/example/service/ArticleService.kt first. Add ktor-server-call-id-jvm and ktor-server-call-logging-jvm. Create src/main/kotlin/com/example/plugins/Monitoring.kt with configureMonitoring(): install CallId reading X-Request-Id, generating a UUID when absent, verifying the value is non-empty and bounded in length, and replying with the id on the response; install CallLogging with callIdMdc(\"call-id\") and a filter for /articles paths. Add [%X{call-id}] to the logback pattern. Call configureMonitoring() before configureRouting() in PostgresApplication.kt. In Routing.kt log the DbElementInsertException with call.application.log.error before responding 500. Add src/test/kotlin/com/example/CallIdTest.kt using testApplication with its own application block that installs serialization and monitoring and a /ping route, without loading module() or Postgres: assert a sent X-Request-Id is echoed, a missing one yields a UUID, and an empty one is replaced. Run ./gradlew build, then start Postgres with the databaseInstance task and ./gradlew run, and paste two curl -i responses and their log lines in the pull request. Do not change ArticleService queries or the Article model.",
  "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 that adds two dependencies to build.gradle.kts, a new plugins/Monitoring.kt, one line in PostgresApplication.kt, one log call in Routing.kt, a changed pattern in logback.xml and the first test in the repository, CallIdTest.kt. The description shows a curl -i response with X-Request-Id echoed, a second with a generated UUID, and the INFO lines from CallLogging carrying the same ids in brackets, plus the ./gradlew build result.

On a repository with the Build All Samples workflow, the pull request runs build-all.sh, which builds and tests every sample on the workflow's JDK, so a dependency that does not resolve or a failing CallIdTest shows there. The Detekt scan runs on the new Kotlin file as well.

A reviewer checks that the verify rule accepts the ids their gateway sends, that the MDC key call-id matches the field their log pipeline indexes, that logging is at INFO only for /articles so health probes stay quiet, and that the test does not need Postgres. Then they map the field in their log search.

Run it on every Ktor service onboarded to the log pipeline

A platform team moving services onto a shared log pipeline sends one POST /o/{org}/sessions per repository with this prompt and that repository in resources. Each run reads its own build.gradle.kts and module, so a service that already has CallLogging gets CallId and the MDC key added to it instead of a second plugin, and each run opens its own pull request.

Give the API key a webhook_url and Rush POSTs run.completed when each turn ends, with the session_url to read the pull request and the pasted log lines from.

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

Why run it on Rush?

A request id is only useful if it reaches every log line and comes back to the caller, and both halves are easy to half-do: install CallLogging without callIdMdc and the id is logged once, or forget replyToHeader and the client has nothing to quote. In a Rush sandbox the agent starts the real server, sends requests with and without the header, and keeps the responses and the log lines in the run's record, so the pull request shows the id in both places.

The sample has no tests and its module connects to Postgres on load; the agent works around that by testing the plugins in their own testApplication block, and proves it by running ./gradlew build before pushing. The same request works unchanged on every Ktor service a team owns.

Frequently asked questions

Does the test need Postgres running?

No. module() opens a JDBC connection on load, so the test does not call it. CallIdTest builds its own testApplication with configureSerialization(), configureMonitoring() and a /ping route, which is enough to assert the header and MDC behaviour.

What if the client sends an id I do not trust?

CallId runs the verify block on every incoming value and generates a fresh UUID when it fails. The pull request rejects empty values and over-long ones; tighten the rule to a UUID pattern if your gateway always sends one.

Will every request be logged?

CallLogging is installed with a filter for /articles paths at INFO, so a health check or static request writes nothing. The MDC value is set for every call regardless, so any log line the handlers write carries the id.

Does this change the log format for existing lines?

Only by adding [%X{call-id}] after the level in logback.xml. Lines written outside a request, such as startup, show empty brackets. If your pipeline wants JSON instead, the repository's structured-logging sample shows logstash-logback-encoder, which the agent can switch to on request.

More Ktor jobs

The same job on other stacks

Keep reading