107 lines
2.5 KiB
Markdown
107 lines
2.5 KiB
Markdown
---
|
|
name: ottyl
|
|
description: Query and configure a running ottyl observability instance (logs, params, metrics, dashboards) via its MCP server.
|
|
---
|
|
|
|
# ottyl
|
|
|
|
ottyl turns a piped command's stdout into a searchable log timeline plus ad-hoc metrics and
|
|
dashboards, served from a single process. This doc covers how an agent connects to and drives a
|
|
*running* instance.
|
|
|
|
## Find a session
|
|
|
|
Each `ottyl` process registers itself under a name (random, e.g. `comic-gazelle`, unless started
|
|
with `--name <name>`). List known sessions:
|
|
|
|
```
|
|
ottyl sessions
|
|
# comic-gazelle port=51423 pid=8421
|
|
```
|
|
|
|
## Connect an MCP client
|
|
|
|
Start the MCP server (a separate short-lived process) pointed at that session, and register it
|
|
with your MCP client (e.g. Claude Code's `.mcp.json`):
|
|
|
|
```
|
|
ottyl mcp --session comic-gazelle
|
|
# or, if you already know the port:
|
|
ottyl mcp --port 51423
|
|
```
|
|
|
|
This exposes six tools, each a thin proxy onto the target instance's HTTP API.
|
|
|
|
## Get the latest SKILL.md
|
|
|
|
This file is compiled into the `ottyl` binary, so a copy you have on disk can lag behind the
|
|
version a running instance actually serves (e.g. after an upgrade). A running instance always
|
|
serves its own current copy read-only over HTTP — fetch it directly rather than trusting a stale
|
|
local file:
|
|
|
|
```
|
|
curl http://localhost:<port>/SKILL.md
|
|
```
|
|
|
|
Use the port from `ottyl sessions` (or the `--port`/`--session` you passed to `ottyl mcp`). There
|
|
is no CLI subcommand for this and no way to update it at runtime — the served content only changes
|
|
when the binary is rebuilt with a new `SKILL.md`.
|
|
|
|
## Tools
|
|
|
|
### `query_logs`
|
|
Count or read log lines matching a FilterBar query.
|
|
|
|
```json
|
|
{ "filter": "regex(\"error\")", "count_only": true }
|
|
```
|
|
|
|
### `declare_param`
|
|
Extract a named value from matching log lines.
|
|
|
|
```json
|
|
{
|
|
"name": "status_code",
|
|
"message_match_regex": "status=(\\d+)",
|
|
"capture_group": "1",
|
|
"kind": "number"
|
|
}
|
|
```
|
|
|
|
### `declare_metric`
|
|
Bucket event counts/values by label, derived from matching log lines.
|
|
|
|
```json
|
|
{
|
|
"name": "errors_total",
|
|
"message_match_regex": "level=error",
|
|
"label_params": ["status_code"]
|
|
}
|
|
```
|
|
|
|
### `create_dashboard`
|
|
Create an empty dashboard in a profile (defaults to the active profile).
|
|
|
|
```json
|
|
{ "name": "Errors" }
|
|
```
|
|
|
|
### `add_panel`
|
|
Add a panel to a dashboard, or update one in place by `panel_id`.
|
|
|
|
```json
|
|
{
|
|
"dashboard_id": "<id from create_dashboard>",
|
|
"title": "Errors over time",
|
|
"promql": "rate(errors_total[5m])",
|
|
"chart_type": "line"
|
|
}
|
|
```
|
|
|
|
### `get_dashboard`
|
|
Read a dashboard's current panels.
|
|
|
|
```json
|
|
{ "dashboard_id": "<id>" }
|
|
```
|