---
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.

## 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>" }
```