@aryasaatvik/motel 0.5.2 → 0.5.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/AGENTS.md +20 -17
  2. package/README.md +53 -4
  3. package/package.json +3 -2
package/AGENTS.md CHANGED
@@ -130,27 +130,30 @@ The repo is wired up with `@effect/language-service` as a `tsconfig.json` `plugi
130
130
  - Health: `http://127.0.0.1:27686/api/health`
131
131
 
132
132
  ## Env Vars
133
- - `MOTEL_OTEL_ENABLED`: defaults to `false` (set to `true` to emit self-traces for debugging motel itself)
134
- - `MOTEL_OTEL_SERVICE_NAME`: defaults to `motel-otel-tui`; a nonblank explicit value also selects the initial TUI service, overriding the remembered selection (unset or blank values keep the remembered selection)
133
+ Integer settings treat blank, non-numeric, and non-positive values as unset. `src/config.ts` resolves the base URL as `MOTEL_OTEL_BASE_URL`, then `MOTEL_OTEL_QUERY_URL`, then `MOTEL_OTEL_COLLECTOR_URL`, then `http://127.0.0.1:27686`. Host and port follow that URL unless set (`src/config.ts` uses port 80 when the URL has no port). The managed daemon in `src/daemon.ts` stops at `MOTEL_OTEL_QUERY_URL` and uses port 27686 when its URL has no port, then writes that listen address into the server's base URL, query URL, host, port, and exporter URLs. The server's database file is `MOTEL_OTEL_DB_PATH`, or `telemetry.sqlite` in the runtime directory, independent of the listen address.
134
+ - `MOTEL_OTEL_ENABLED`: defaults to `false`. Blank, `0`, `false`, `no`, and `off` stay off; any other value makes the TUI and CLI export motel's own traces and logs.
135
+ - `MOTEL_OTEL_SERVICE_NAME`: defaults to `motel-otel-tui`. A nonblank value is the exporter service name, the CLI default service, and the initial TUI service. Blank keeps the remembered TUI service.
135
136
  - `MOTEL_OTEL_BASE_URL`: defaults to `http://127.0.0.1:27686`
136
- - `MOTEL_OTEL_HOST`: defaults to `127.0.0.1`
137
- - `MOTEL_OTEL_PORT`: defaults to `27686`
138
- - `MOTEL_OTEL_EXPORTER_URL`: defaults to `http://127.0.0.1:27686/v1/traces`
139
- - `MOTEL_OTEL_LOGS_EXPORTER_URL`: defaults to `http://127.0.0.1:27686/v1/logs`
140
- - `MOTEL_OTEL_QUERY_URL`: defaults to `http://127.0.0.1:27686`
141
- - `MOTEL_OTEL_DB_PATH`: defaults to `${XDG_STATE_HOME:-~/.local/state}/motel/telemetry.sqlite` (one shared DB per machine; daemon log + lock + instance registry live in the same directory)
142
- - `MOTEL_RUNTIME_DIR`: overrides the daemon log, lock, and instance-registry directory (primarily for isolated tests and custom managed instances)
143
- - `MOTEL_OTEL_TRACE_LOOKBACK_MINUTES`: defaults to `1440` (24h)
144
- - `MOTEL_OTEL_TRACE_LIMIT`: defaults to `100`
145
- - `MOTEL_OTEL_LOG_LIMIT`: defaults to `80`
137
+ - `MOTEL_OTEL_QUERY_URL`: base URL fallback when `MOTEL_OTEL_BASE_URL` is unset. The configured query URL is the resolved base URL.
138
+ - `MOTEL_OTEL_COLLECTOR_URL`: base URL fallback when both URLs above are unset. The managed daemon leaves it unused.
139
+ - `MOTEL_OTEL_HOST`: defaults to the base URL hostname (`127.0.0.1`)
140
+ - `MOTEL_OTEL_PORT`: defaults to the base URL port (`27686`; `80` from `src/config.ts` when the URL has no port)
141
+ - `MOTEL_OTEL_EXPORTER_URL`: defaults to the base URL plus `v1/traces`
142
+ - `MOTEL_OTEL_LOGS_EXPORTER_URL`: defaults to the base URL plus `v1/logs`
143
+ - `MOTEL_RUNTIME_DIR`: defaults to `${XDG_STATE_HOME:-~/.local/state}/motel` (default database, daemon log, lock, and instance registry; primarily overridden for isolated tests and custom managed instances)
144
+ - `MOTEL_OTEL_DB_PATH`: defaults to `$MOTEL_RUNTIME_DIR/telemetry.sqlite` (one shared DB per machine)
145
+ - `MOTEL_URL`: when set, the MCP client uses this base URL instead of the instance registry
146
+ - `MOTEL_OTEL_TRACE_LOOKBACK_MINUTES`: defaults to `1440` (24h) for service discovery and store queries that omit a lookback. HTTP list and search routes send their own `lookback` (default 60 minutes, maximum 1440).
147
+ - `MOTEL_OTEL_TRACE_LIMIT`: defaults to `100` for the TUI and CLI. HTTP list routes send their own `limit`.
148
+ - `MOTEL_OTEL_LOG_LIMIT`: defaults to `80` for TUI service logs, TUI trace logs, and CLI log commands. HTTP log routes send their own `limit`.
146
149
  - `MOTEL_OTEL_RETENTION_HOURS`: defaults to `168` (7d)
147
- - `MOTEL_OTEL_MAX_DB_SIZE_MB`: defaults to `1024` (size-based retention cap)
148
- - `MOTEL_OTEL_RETENTION_TRACE_BATCH`: defaults to `100` completed traces per cleanup pass
149
- - `MOTEL_OTEL_RETENTION_LOG_BATCH`: defaults to `5000` logs per cleanup pass
150
+ - `MOTEL_OTEL_MAX_DB_SIZE_MB`: defaults to `1024` (active-data target, not a hard file cap)
151
+ - `MOTEL_OTEL_RETENTION_TRACE_BATCH`: defaults to `100` completed traces marked per cleanup pass
152
+ - `MOTEL_OTEL_RETENTION_LOG_BATCH`: defaults to `5000` logs marked per cleanup pass
150
153
  - `MOTEL_OTEL_QUERY_CAPACITY`: defaults to `8` outstanding queries per runtime (maximum `64`)
151
154
  - `MOTEL_OTEL_QUERY_DEADLINE_MS`: defaults to `5000` including queue and startup time (maximum `30000`)
152
- - `MOTEL_OTEL_RETENTION_ROW_BATCH`: defaults to `1000` physical rows per cleanup pass
153
- - `MOTEL_OTEL_RETENTION_INTERVAL_SECONDS`: defaults to `10`
155
+ - `MOTEL_OTEL_RETENTION_ROW_BATCH`: defaults to `1000` rows deleted per cleanup pass, split across traces and logs. Bounds row count, not the size of one field.
156
+ - `MOTEL_OTEL_RETENTION_INTERVAL_SECONDS`: defaults to `10` after an idle pass. Cleanup that is still making progress waits 100 ms.
154
157
 
155
158
  ## TUI Keys
156
159
  - `?`: toggle shortcut help
package/README.md CHANGED
@@ -42,7 +42,7 @@ npm install -g @aryasaatvik/motel
42
42
  Don't have Bun?
43
43
 
44
44
  ```bash
45
- curl -fsSL https://bun.sh/install | bash
45
+ curl -fsSL https://bun.sh/install | bash -s "bun-v1.4.4"
46
46
  ```
47
47
 
48
48
  `motel` starts the local OTLP ingest server on
@@ -50,7 +50,7 @@ curl -fsSL https://bun.sh/install | bash
50
50
  the keyboard cheat sheet, or `c` to copy paste-ready setup instructions
51
51
  for any Effect/OTEL app you want to trace.
52
52
 
53
- Requirements: [Bun](https://bun.sh/) matching `package.json` `engines.bun` (`>=1.3.0`).
53
+ Requirements: [Bun](https://bun.sh/) matching `package.json` `engines.bun` (`>=1.4.4`).
54
54
 
55
55
  ### macOS service from the maintained checkout
56
56
 
@@ -90,12 +90,61 @@ The store retains seven days of telemetry by default and targets a 1 GB
90
90
  active-data ceiling using bounded background batches. Recent data is preserved while
91
91
  the oldest completed traces and logs are removed first. Configure the policy
92
92
  with `MOTEL_OTEL_RETENTION_HOURS`, `MOTEL_OTEL_MAX_DB_SIZE_MB`,
93
- `MOTEL_OTEL_RETENTION_TRACE_BATCH`, `MOTEL_OTEL_RETENTION_LOG_BATCH`, and
94
- `MOTEL_OTEL_RETENTION_INTERVAL_SECONDS`. Existing databases created without
93
+ `MOTEL_OTEL_RETENTION_TRACE_BATCH`, `MOTEL_OTEL_RETENTION_ROW_BATCH`,
94
+ `MOTEL_OTEL_RETENTION_LOG_BATCH`, and
95
+ `MOTEL_OTEL_RETENTION_INTERVAL_SECONDS`.
96
+ Existing databases created without
95
97
  incremental auto-vacuum are never silently rewritten at startup; deleted pages
96
98
  are reused, but shrinking such a historical file requires an explicit offline
97
99
  SQLite `VACUUM` chosen by the user.
98
100
 
101
+ ## Configuration
102
+
103
+ Processes that load `src/config.ts` resolve one base URL, in order:
104
+ `MOTEL_OTEL_BASE_URL`, `MOTEL_OTEL_QUERY_URL`, `MOTEL_OTEL_COLLECTOR_URL`,
105
+ then `http://127.0.0.1:27686`. The query URL is that base URL. Host is
106
+ `MOTEL_OTEL_HOST`, or the base URL hostname. Port is `MOTEL_OTEL_PORT` when
107
+ it is a positive integer, otherwise the base URL port, otherwise 80. Trace
108
+ and log exporter URLs default to that base with `v1/traces` and `v1/logs`.
109
+
110
+ `motel start`, and the daemon the TUI launches, build the listen address
111
+ from `MOTEL_OTEL_BASE_URL`, then `MOTEL_OTEL_QUERY_URL`, then
112
+ `http://127.0.0.1:27686`. A missing port becomes 27686. The spawned server
113
+ receives that listen address as its base URL, query URL, host, port, and
114
+ exporter URLs (the listen origin plus `/v1/traces` and `/v1/logs`). The
115
+ database file is resolved separately: `MOTEL_OTEL_DB_PATH`, or
116
+ `telemetry.sqlite` in the runtime directory.
117
+
118
+ Integer settings treat blank, non-numeric, and non-positive values as unset.
119
+ `MOTEL_OTEL_QUERY_CAPACITY` is capped at 64 and
120
+ `MOTEL_OTEL_QUERY_DEADLINE_MS` at 30000.
121
+
122
+ | Variable | Default | What it does |
123
+ | --- | --- | --- |
124
+ | `MOTEL_OTEL_BASE_URL` | `http://127.0.0.1:27686` | Resolved base URL and query URL. First choice in the fallback above. |
125
+ | `MOTEL_OTEL_QUERY_URL` | unset | Base URL when `MOTEL_OTEL_BASE_URL` is unset. The query URL equals the resolved base URL. |
126
+ | `MOTEL_OTEL_COLLECTOR_URL` | unset | Base URL only when both URLs above are unset. The managed daemon leaves it unused. |
127
+ | `MOTEL_OTEL_HOST` | base URL hostname (`127.0.0.1`) | Hostname the server binds. |
128
+ | `MOTEL_OTEL_PORT` | base URL port (`27686`) | Port the server binds. `src/config.ts` uses 80 when the URL has no port; the managed daemon uses 27686. |
129
+ | `MOTEL_OTEL_SERVICE_NAME` | `motel-otel-tui` | Name on motel's own exporter, and the CLI default service. A nonblank value is also the TUI's initial service. Blank keeps the remembered TUI service. |
130
+ | `MOTEL_OTEL_ENABLED` | `false` | Export motel's own traces and logs from the TUI and CLI. Blank, `0`, `false`, `no`, and `off` stay off; any other value turns it on. |
131
+ | `MOTEL_OTEL_EXPORTER_URL` | base URL + `/v1/traces` | Where that self-export posts spans. |
132
+ | `MOTEL_OTEL_LOGS_EXPORTER_URL` | base URL + `/v1/logs` | Where that self-export posts logs. |
133
+ | `MOTEL_RUNTIME_DIR` | `${XDG_STATE_HOME:-~/.local/state}/motel` | State directory: default database, daemon log, lock, and instance registry. |
134
+ | `MOTEL_OTEL_DB_PATH` | `$MOTEL_RUNTIME_DIR/telemetry.sqlite` | SQLite file. One shared database per machine unless this is set. |
135
+ | `MOTEL_URL` | unset | Base URL for the MCP client. When set, discovery uses it instead of the instance registry. |
136
+ | `MOTEL_OTEL_TRACE_LOOKBACK_MINUTES` | `1440` | Age window, in minutes, for service discovery and for store queries that omit a lookback. HTTP list and search routes send their own `lookback` (default 60 minutes, maximum 1440). |
137
+ | `MOTEL_OTEL_TRACE_LIMIT` | `100` | Trace count for the TUI and for CLI trace commands that omit a limit. HTTP list routes send their own `limit`. |
138
+ | `MOTEL_OTEL_LOG_LIMIT` | `80` | Log count for TUI service logs, TUI trace logs, and CLI log commands. HTTP log routes send their own `limit`. |
139
+ | `MOTEL_OTEL_QUERY_CAPACITY` | `8` (maximum 64) | Outstanding readonly queries per runtime. Overload is HTTP 503 `QUERY_OVERLOADED`. |
140
+ | `MOTEL_OTEL_QUERY_DEADLINE_MS` | `5000` (maximum 30000) | Queue plus startup deadline for one readonly query. Expiry is HTTP 504 `QUERY_DEADLINE`. |
141
+ | `MOTEL_OTEL_RETENTION_HOURS` | `168` | Age cutoff for completed traces and for logs. |
142
+ | `MOTEL_OTEL_MAX_DB_SIZE_MB` | `1024` | Active-data target in MB: `(page_count - freelist_count) * page_size`. Not a hard file-size cap. |
143
+ | `MOTEL_OTEL_RETENTION_TRACE_BATCH` | `100` | Completed traces marked per cleanup pass. |
144
+ | `MOTEL_OTEL_RETENTION_ROW_BATCH` | `1000` | Rows deleted per cleanup pass, split across traces and logs. Bounds row count, not the size of one field. |
145
+ | `MOTEL_OTEL_RETENTION_LOG_BATCH` | `5000` | Logs marked per cleanup pass. |
146
+ | `MOTEL_OTEL_RETENTION_INTERVAL_SECONDS` | `10` | Delay after an idle cleanup pass. Cleanup that is still making progress waits 100 ms. |
147
+
99
148
  ## How agents connect
100
149
 
101
150
  Agents with the `motel-debug` skill installed will automatically use
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aryasaatvik/motel",
3
- "version": "0.5.2",
3
+ "version": "0.5.3",
4
4
  "description": "A local OpenTelemetry ingest + TUI viewer for development, backed by SQLite.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -26,8 +26,9 @@
26
26
  "workspaces": [
27
27
  "web"
28
28
  ],
29
+ "packageManager": "bun@1.4.4",
29
30
  "engines": {
30
- "bun": ">=1.3.0"
31
+ "bun": ">=1.4.4"
31
32
  },
32
33
  "publishConfig": {
33
34
  "access": "public",