Package io.kroxylicious.proxy.router

Interface Router

public interface Router
A router decides which route should handle a given incoming Kafka request.

Router implementations use the RouterContext to send requests down named routes and to deliver a response back to the client. A single incoming request may result in multiple outgoing requests to different routes (e.g. fan-out), with the router composing the final response.

Observability guidelines for router implementations

The runtime automatically logs and measures the following on behalf of all router implementations:

  • Which route each request was sent to (at TRACE level, with route key)
  • Request/response correlation
  • Per-route request counts, error counts, and latency (as Micrometer metrics)
  • Error conditions such as unknown routes and router failures

Router implementations should not duplicate the above. Instead, implementations should log:

  • Routing rationale at DEBUG: explain why a particular route was chosen when the logic is non-trivial. Always include RouterContext.sessionId() for correlation with runtime logs.
  • Configuration at INFO during initialisation: log once from RouterFactory.createRouter(io.kroxylicious.proxy.router.RouterFactoryContext, I) to describe the router's configuration.
  • Response mutation at DEBUG: if the router modifies responses (e.g. version capping in API_VERSIONS), log the modification since it changes protocol behaviour visible to clients.
  • Recovered errors at WARN: if the router catches exceptions internally and recovers, log them with conditional stack traces (include the full stack trace only when DEBUG is enabled).

Router implementations must not:

  • Log Kafka message content (may contain sensitive data).
  • Log at INFO or above on every request (reserve INFO+ for lifecycle events; per-request logging at that level causes excessive volume in production).

  • Method Summary

    Modifier and Type
    Method
    Description
    default void
    close()
    Called by the runtime when the client connection is torn down.
    CompletionStage<RouterResponse>
    onRequest(org.apache.kafka.common.protocol.ApiKeys apiKey, short apiVersion, org.apache.kafka.common.message.RequestHeaderData header, org.apache.kafka.common.protocol.ApiMessage request, RouterContext context)
    Called for each incoming client request that is dynamically routed.
    default Map<org.apache.kafka.common.protocol.ApiKeys,String>
    staticRoutes()
    Declares API keys that are always forwarded to a fixed named route without deserialisation.