> For the complete documentation index, see [llms.txt](https://docs.lenses.io/latest/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lenses.io/latest/k2k/k2k-standalone-tool/web-ui.md).
# Web UI
The K2K-Tool Web UI allows management of committed offsets.
The K2K Tool provides a web interface that can be accessed when running the `server` command.
{% hint style="danger" %}
Warning: Setting offsets should only be used when the K2K application has been stopped.
If the K2K application is running, the offset reset might not be applied as the application will continue to commit offsets, potentially overwriting the reset operation.
{% endhint %}
## Interface
The web interface consists of:
* **Left Sidebar**: Lists the managed pipelines. Each pipeline offers two views — **K2K Record Replication** and **K2K Offset Mapping**.
* **Centre Content Panel**: The table for the selected view.
* **Information Sidebar** (right): Per-partition detail for the selected topic or consumer group. Drag its left edge to resize it; the width is remembered for later sessions.
Data updates automatically over a WebSocket connection — there is no manual refresh. The first snapshot arrives on connect and later ones follow the refresh interval, bounded by `--websocket-min-refresh-interval`. If the connection drops, the pipeline list stays visible while the UI reconnects; Kafka failures are surfaced as an error in the UI.
Table updates can be paused while the connection stays open, which is useful when reading a value on a busy pipeline.
## Views
### K2K Record Replication
Shows how far the replicator has progressed for the pipeline's K2K consumer group. Topics expand inline to their partitions with committed, last, and lag columns. Topics and lag are sortable, and column headers carry help tooltips. The mapped target topic name is shown for each source topic-partition.
Record replication view, with the information sidebar open on a topic
Lag is computed in the UI from the committed and last offsets. It is never shown as negative, and values come from cached reads, so they may be a few seconds behind.
### K2K Offset Mapping
Available when [offset mapping](/latest/k2k/configuration-reference/offset-mapping.md) is enabled. Lists the consumer groups matched by the pipeline's `groups.consumerGroups` filter, one row per group, with **Committed (source/target)**, **Commit Lag (source/target)**, and **Offset Mapping Lag (estimate)**.
Selecting a group opens the information sidebar, which breaks the same values down per partition and adds the source and target last offsets and the topic name on each side (the target name differs from the source when sink rename rules apply).
The **Offset Mapping Lag (estimate)** column shows `0` when an exact mapping exists for the source committed offset. Otherwise it estimates how far that commit is past the pipeline's last replicated source offset.
Separate filters are available for consumer group name and topic name.
Offset Mapping view, with the information sidebar open on a consumer group
## Actions
| Action | Where | Effect |
| --------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| **Set offsets** | Select a topic in Record Replication | Enter new committed offsets per partition in one dialog. Each partition reports its own success or failure. |
| **Reset** | Partition row | Reset that partition's committed offset. |
| **Reset All** | Above the committed offsets table | Reset all partitions of all topics in the pipeline to offset 0 (earliest). |
Reset dialogs warn you to stop all replicator instances for the pipeline before continuing. If an instance is still running, it may overwrite the change.
## Run
### Pipelines and server
| flag/short | description | default | required |
| -------------------------- | ---------------------------------------------------------------------------------------------- | --------- | --------------------------------- |
| `--file` / `-f` | Comma-separated list of file(s) that define one k2k pipeline. Can be specified multiple times. | - | Yes, unless `--dir` is specified |
| `--dir` | List of directories to watch for pipeline files. Can be specified multiple times. | - | Yes, unless `--file` is specified |
| `--defaults` / `-d` | File containing defaults for the k2k app. Can be specified multiple times. | - | No |
| `--host` / `-h` | Host the server will accept requests from. | `0.0.0.0` | No |
| `--port` / `-p` | Port the server will accept requests from. | `8080` | No |
| `--template-engine` / `-g` | Enable or disable the template engine (`enabled` or `disabled`). | `enabled` | No |
| `--verbosity` | Sets the log verbosity. One of `off`, `error`, `info`, `debug`, `trace`. | - | No |
### Background refresh
The server keeps cached views of cluster health, topic end offsets, and committed consumer group offsets, refreshed in the background. Lengthen these intervals to reduce admin API load against the clusters — particularly on managed offerings that throttle admin requests — at the cost of slightly staler numbers in the UI.
| flag/short | description | default | required |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | -------- |
| `--healthcheck-timeout` / `-e` | Duration to wait for a health check to complete. | `5s` | No |
| `--healthcheck-interval` / `-H` | Duration between background health checks against the configured clusters. | `30s` | No |
| `--topic-offset-interval` / `-O` | Duration between background source topic end-offset refreshes for managed pipelines. | `1.5s` | No |
| `--topic-offset-batch-size` / `-B` | Maximum number of topic-partitions fetched per end-offset request batch. | `100` | No |
| `--consumer-group-offset-interval` / `-G` | Duration between background committed consumer group offset refreshes for offset-mapping pipelines. | `5s` | No |
| `--kafka-fetch-jitter` / `-J` | Fraction of the base interval added as random delay between Kafka fetch cycles. `0` disables; `0.2` adds up to 20%. Must be between `0` and `1`. | `0` | No |
| `--watcher-interval` / `-w` | Duration between checks for new files in the managed directories. | `10s` | No |
| `--websocket-min-refresh-interval` / `-R` | Minimum duration between WebSocket snapshot updates. Client refresh values below this are raised to the minimum. | `500ms` | No |
Use `--kafka-fetch-jitter` when running several `k2k-tool` servers against the same clusters, so their background refresh cycles do not align into bursts.
Transient Kafka errors do not stop background refresh: a failed fetch is logged and skipped so the rest of that cycle still runs, and health status resets to pending until the next successful check. Consumer groups and topic partitions that no longer exist are dropped from the live view.
### Examples
```bash
# Start server with a single pipeline file
k2k-tool server -f /path/to/pipeline.k2k.yml
# Start server watching a directory
k2k-tool server --dir /pipelines
# Start server with a pipeline defined over multiple files and custom port
k2k-tool server -f /path/to/pipeline1.k2k.yml,/path/to/pipeline2.k2k.yml -p 9090
# Reduce admin API load on a throttled managed cluster
k2k-tool server --dir /pipelines -O 10s -G 30s -H 60s -J 0.2
```
## HTTP API
The `server` command serves the UI and a JSON API on the same host and port.
| Method | Path | Purpose |
| ------ | --------------------------------------- | --------------------------------------------------------------- |
| `GET` | `/` | Web UI |
| `GET` | `/api/health` | Cached cluster health. `200` when healthy, `503` when not |
| `GET` | `/api/pipelines` | Names of the managed pipelines |
| `GET` | `/api/groups?group=&pipeline=` | Consumer group state, optionally filtered by group and pipeline |
| `POST` | `/api/pipelines/{pipeline}/group/reset` | Reset all partitions of all topics to offset 0 |
| `PUT` | `/api/pipelines/{pipeline}/group` | Set specific committed offsets (JSON body) |
| `GET` | `/api/ws?refresh=` | WebSocket stream of live snapshots |
`/api/health` is suitable as a Kubernetes liveness or readiness probe, since it returns `503` while any configured cluster is unreachable:
```yaml
readinessProbe:
httpGet:
path: /api/health
port: 8080
```
The reset and set endpoints change committed offsets on the target Kafka cluster — the same warning about stopping replicator instances first applies.
### WebSocket stream
A client subscribes to **one** data stream at a time and receives snapshots for that type only:
| Operation | Snapshot contents |
| ------------------------ | ----------------------------------------------------------- |
| `subscribeGroups` | K2K consumer group offsets (record replication) |
| `subscribeOffsetMapping` | `offsetMappingGroups` — offset-mapping consumer group state |
The first snapshot is sent immediately on connect. Later snapshots follow the `refresh` query parameter, which defaults to `--websocket-min-refresh-interval` when the client omits it and is raised to that minimum when the client requests something shorter. Unknown subscription operations are logged and ignored rather than closing the connection.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.lenses.io/latest/k2k/k2k-standalone-tool/web-ui.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
