Metadata-Version: 2.4
Name: kontiki-tui
Version: 1.0.0
Summary: Terminal UI to monitor Kontiki services, registry events, and logs.
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: kontiki,tui,textual,monitoring,amqp
Author: The Kontiki Authors
Requires-Python: >=3.11,<4.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Monitoring
Requires-Dist: kontiki (>=1.9.0)
Requires-Dist: pyyaml (>=6.0.3,<7.0.0)
Requires-Dist: rich (>=14.3.3,<15.0.0)
Requires-Dist: textual
Project-URL: Homepage, https://github.com/kontiki-org/kontiki-tui
Project-URL: Issues, https://github.com/kontiki-org/kontiki-tui/issues
Project-URL: PyPI, https://pypi.org/project/kontiki-tui/
Project-URL: Repository, https://github.com/kontiki-org/kontiki-tui
Description-Content-Type: text/markdown

# KontikiTUI

> **Part of the Kontiki suite** — a compact open-source stack for startups and
> small teams that need ops without the heavy stack.
>
> Full suite overview → https://kontiki-org.github.io/
>
> Ops demo → [kontiki-monitor Quickstart](https://github.com/kontiki-org/kontiki-monitor#quickstart--demo-app--telegram).


## Overview

**KontikiTUI** is a small terminal UI for monitoring [Kontiki](https://github.com/kontiki-org/kontiki)
systems via the Kontiki service registry and log files.

It is built with [Textual](https://textual.textualize.io/), a Python TUI framework.

It is “engineering‑tool” oriented:

- quick view of **running services** (status, last heartbeat, degraded reason, host/pid, version),
- inspect **events** and **exceptions** recorded by the registry,
- read **logs** without leaving the terminal.

---

## Tabs

- **Services**: registered services with status, last heartbeat, degraded reason,
  host/pid, and version (Kontiki ≥1.9.0). Selecting a row shows the
  configuration/metadata in JSON.

  Defaults to the **business** registration group via the session **Group** Select
  on each monitoring tab (`all` / `business` / `platform` / …). Changing it in one
  tab updates all tabs. Missing/blank Registry `group` counts as business.
  Instance column shows the Kontiki short id (12 hex), not the full UUID.

  ![Services tab](assets/services.png)

- **Events**: events tracked by the registry, with local filters (`Field`/`Value`/`Limit`).
  Domain publishes and RPC calls are shown (`rpc:<remote_method>` when there is no
  `event_type`). Hides registry bookkeeping and TUI observer traffic.
  Filtered by the same session Group Select (registry jointure).
  Deregistered instances fall back to `business`.

  ![Events tab](assets/events.png)

- **Exceptions**: exceptions from the registry exception tracker, with the same local filtering approach.
  Also filtered by the session Group Select. The `context` payload is shown compactly.

  ![Exceptions tab](assets/exceptions.png)

- **Logs**: reads configured log files from `logs.directory` and displays them in the UI.
  Uses `lnav` when available; otherwise it falls back to a Python reader.
  When services use Kontiki ≥1.8.1 (`logging.directory` in their config), log files
  are named `{service_name}-{short_instance_id}.log` and filtered by the session
  Group Select. `ServiceRegistry-*.log` is never included (observer / registry
  process noise). Files that do not follow Kontiki naming are always shown.

  ![Logs tab](assets/logs.png)

- **Settings**: edit `~/.config/kontiki_tui.yaml` (the app reloads configuration on save).

  ![Settings tab](assets/settings.png)

---

## Requirements

- **Optional**: [lnav](https://lnav.org/) for richer log filtering; without it, a built-in Python reader is used

## Quickstart

### Install from PyPI

```bash
pip install kontiki-tui
kontiki-tui
```

([package on PyPI](https://pypi.org/project/kontiki-tui/))

### Install from source (Poetry)

```bash
make install
make run
```

### Test stack (RabbitMQ + registry + example services)

In one terminal:

```bash
make stack-up
```

In another terminal:

```bash
make run
```

Launch examples to view events and exceptions
```
make run-rpc-example
make run-simple-event-example
```

To stop:

```bash
make stack-down
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

