Skip to content

Commit 19a6f7e

Browse files
anthonyiscodingcoderabbitai[bot]
anthonyiscoding
and
coderabbitai[bot]
authored
docs(console): extract how-to content from reference, reduce duplication (#1586)
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
1 parent 3db6573 commit 19a6f7e

4 files changed

Lines changed: 262 additions & 132 deletions

File tree

‎docs/console/index.mdx‎

Lines changed: 63 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -13,29 +13,15 @@ graph LR
1313
B[Browser] -->|HTTP :3113| C
1414
```
1515

16-
## Installation
17-
18-
Install the console binary:
19-
20-
```bash
21-
curl -fsSL https://install.iii.dev/console/main/install.sh | sh
22-
```
23-
24-
Verify the installation:
25-
26-
```bash
27-
iii-console --help
28-
```
29-
3016
## Quick Start
3117

32-
Start the console while your iii engine is running:
18+
The console comes preinstalled with iii, start it with:
3319

3420
```bash
35-
iii-console
21+
iii console
3622
```
3723

38-
Then open your browser to [http://localhost:3113](http://localhost:3113).
24+
Then open your browser to [http://127.0.0.1:3113](http://127.0.0.1:3113).
3925

4026
<Warning title="Engine must be running">
4127
The console connects to a running iii engine instance. Make sure your engine is started before launching the console.
@@ -61,7 +47,7 @@ The Workers page lists every worker process currently connected to the engine, w
6147
| Active | Number of currently in-flight invocations |
6248
| Connected | Time since the worker connected |
6349

64-
Click a worker to open a detail panel showing full metadata, telemetry (language, project, framework), live metrics, and the list of functions the worker has registered.
50+
The worker detail panel shows full metadata, telemetry (language, project, framework), live metrics, and the list of functions the worker has registered.
6551

6652
<img src="/assets/console-workers-detail.png" alt="iii Console Workers page with a selected worker detail panel showing runtime, version, OS, metrics, and registered functions" />
6753

@@ -88,36 +74,19 @@ Use the **search bar** at the top to filter functions by name.
8874

8975
### Invoking Functions
9076

91-
You can invoke any function directly from the console:
92-
93-
1. Click on a function to open its detail panel
94-
2. Enter a JSON payload in the input editor
95-
3. Click **Invoke**
96-
4. View the result or error in real time
97-
98-
This is useful for:
99-
100-
- **Testing** a function during development without wiring up a trigger
101-
- **Debugging** by sending specific payloads to reproduce an issue
102-
- **Ad-hoc operations** like running a migration function manually
103-
104-
For example, to invoke a function `users::getProfile`:
77+
The detail panel includes a JSON editor for invoking functions directly. Enter a payload, click **Invoke**, and view the result inline. The console sends requests via `POST /_console/invoke`.
10578

106-
```json
107-
{
108-
"user_id": "user-123"
109-
}
110-
```
111-
112-
The console sends the payload to the engine via `POST /_console/invoke` and displays the JSON response or error inline.
79+
<Info title="How-to guide">
80+
See [Use the Console](/how-to/use-console#invoke-a-function) for step-by-step instructions.
81+
</Info>
11382

11483
<Info title="Function must be registered">
11584
Only functions that are currently registered and connected via an active worker will appear in the list. If a function is missing, check that its worker process is running.
11685
</Info>
11786

11887
## Triggers
11988

120-
The Triggers page shows every trigger registered with the engine and provides interactive tools to test each trigger type. Triggers are grouped by kind (HTTP, CRON, QUEUE) with a total count badge and per-type filter tabs.
89+
The Triggers page shows every trigger registered with the engine and provides interactive tools to test each trigger type. Triggers are grouped by kind (`http`, `cron`, `event`, `state`) with a total count badge and per-type filter tabs.
12190

12291
<img src="/assets/console-triggers-http-test.png" alt="iii Console Triggers page showing HTTP triggers and the request builder for testing a selected endpoint" />
12392

@@ -128,32 +97,19 @@ The Triggers page shows every trigger registered with the engine and provides in
12897
| Path / Config | HTTP path, cron schedule, or event name |
12998
| Status | Active, Error, or Inactive |
13099

131-
### Testing HTTP Triggers
132-
133-
For HTTP-type triggers, the console provides a built-in request builder:
100+
### Testing Triggers
134101

135-
1. Select the **HTTP method** (GET, POST, PUT, DELETE, PATCH)
136-
2. The **path** is pre-filled from the trigger configuration
137-
3. Add **query parameters** as key-value pairs
138-
4. Enter a **request body** (for POST/PUT/PATCH) as JSON
139-
5. Click **Send** to execute the request
102+
The console provides interactive testing tools for each trigger type:
140103

141-
The response is displayed inline with status code, headers, and body. For example, for a trigger registered at `POST /api/users`:
142-
143-
```json
144-
{
145-
"name": "Alice",
146-
"email": "alice@example.com"
147-
}
148-
```
149-
150-
### Testing Cron Triggers
151-
152-
Cron triggers display their schedule expression (e.g. `0 */5 * * * * *`). You can view the configured schedule and click **Trigger Now** to manually fire the cron job immediately. This is useful for testing scheduled tasks without waiting for the next scheduled run.
153-
154-
### Testing Event Triggers
155-
156-
For event-type triggers, the console provides an event emitter: the event name is pre-filled, you enter a JSON payload, and click **Emit** to publish the event.
104+
| Trigger Type | Testing Tool |
105+
|--------------|--------------|
106+
| HTTP | Request builder with method selection, query params, and JSON body |
107+
| Cron | Schedule viewer with **Trigger Now** button for immediate execution |
108+
| Event | Event emitter with pre-filled event name and JSON payload input |
109+
| State | Update/delete entries in **States** to fire `state:updated` / `state:deleted` triggers |
110+
<Info title="How-to guide">
111+
See [Use the Console](/how-to/use-console#test-an-http-trigger) for step-by-step instructions on testing each trigger type.
112+
</Info>
157113

158114
<Info title="Trigger types">
159115
The available trigger types depend on which workers are loaded in your engine configuration. See [Trigger Types](/architecture/trigger-types) and [Workers](/workers) for the full list.
@@ -174,9 +130,17 @@ Select a group from the left panel to see all its key-value items. Each item sho
174130

175131
### Managing State
176132

177-
- **Add** — Click **Add Item**, enter the scope, key, and JSON value, then save. Persisted via `state::set`.
178-
- **Edit** — Click an existing item, modify the JSON value, and save. Fires `state:updated` triggers if registered.
179-
- **Delete** — Click the delete icon and confirm. Fires `state:deleted` triggers if registered.
133+
The console supports full CRUD operations on state entries:
134+
135+
| Operation | Behavior |
136+
|-----------|----------|
137+
| Add | Persisted via `state::set` |
138+
| Edit | Fires `state:updated` triggers if registered |
139+
| Delete | Fires `state:deleted` triggers if registered |
140+
141+
<Info title="How-to guide">
142+
See [Use the Console](/how-to/use-console#manage-state-entries) for step-by-step instructions.
143+
</Info>
180144

181145
<Info title="State persistence">
182146
State persistence depends on your engine's State worker configuration. With `in_memory` storage, state is lost on engine restart. With `file_based` or `RedisAdapter`, state persists across restarts. See [State Worker](/workers/iii-state) for configuration details.
@@ -215,7 +179,16 @@ The Queues page lists durable queue topics, subscriber counts, queued message co
215179
| Retries | Messages scheduled for retry |
216180
| Dead Letters | Messages that exhausted retry handling |
217181

218-
Click a topic to open the detail panel. The **Overview** tab shows live topic stats and includes a JSON publisher for sending a test message. The **Dead Letters** tab shows failed messages for that topic and supports retrying or deleting individual entries.
182+
The topic detail panel has two tabs:
183+
184+
| Tab | Content |
185+
|-----|---------|
186+
| Overview | Live topic stats and a JSON publisher for sending test messages |
187+
| Dead Letters | Failed messages with retry and delete options |
188+
189+
<Info title="How-to guide">
190+
See [Use the Console](/how-to/use-console#send-a-test-message-to-a-queue) for step-by-step instructions on testing queues and managing dead letters.
191+
</Info>
219192

220193
## Traces
221194

@@ -241,13 +214,15 @@ The Traces page provides full OpenTelemetry trace visualization with multiple vi
241214

242215
### View Modes
243216

244-
Click on a trace to open the detail view with four visualization modes:
217+
The trace detail view provides five visualization modes:
245218

246-
- **Waterfall Chart** — Timeline view showing every span laid out horizontally by start time and duration. This is the default view and is best for understanding the sequential and parallel flow of operations.
247-
- **Flame Graph** — Stack-based visualization where each span is stacked on its parent. Wider bars indicate longer duration. Useful for identifying which operations consume the most time.
248-
- **Service Breakdown** — Groups spans by service name with aggregate statistics: total spans, average duration, and error rate. Useful for identifying which service is the bottleneck.
249-
- **Trace Map** — Topology graph showing how services communicate. Nodes represent services and edges represent span parent-child relationships across service boundaries. Useful for understanding distributed call patterns.
250-
- **Flow** — Node-based execution flow showing parent-child span relationships in the selected trace.
219+
| Mode | Description |
220+
|------|-------------|
221+
| Waterfall Chart | Timeline view with spans laid out by start time and duration. Default view for sequential/parallel flow analysis. |
222+
| Flame Graph | Stack-based view where each span is stacked on its parent. Wider bars indicate longer duration. |
223+
| Service Breakdown | Aggregate statistics grouped by service: total spans, average duration, error rate. |
224+
| Trace Map | Topology graph showing service communication via parent-child span relationships. |
225+
| Flow | Node-based execution flow showing parent-child span relationships. |
251226

252227
<img src="/assets/console-traces-flame-graph.png" alt="iii Console Traces page showing the flame graph view for a selected trace" />
253228

@@ -257,7 +232,7 @@ Click on a trace to open the detail view with four visualization modes:
257232

258233
### Span Details
259234

260-
Click on any span to open the detail panel:
235+
The span detail panel includes the following tabs:
261236

262237
| Tab | Content |
263238
|-----------|-----------------------------------------------------|
@@ -281,6 +256,10 @@ Click on any span to open the detail panel:
281256

282257
Multiple filters are combined with AND logic. Pagination controls at the bottom allow browsing large result sets.
283258

259+
<Info title="How-to guide">
260+
See [Use the Console](/how-to/use-console#inspect-a-trace) for step-by-step instructions on inspecting traces and spans.
261+
</Info>
262+
284263
## Logs
285264

286265
The Logs page provides a viewer for structured OpenTelemetry logs collected by the engine. Logs are displayed in reverse chronological order. Each entry shows a timestamp, severity level, service name, trace/span context, and message. A severity filter toggle, full-text search, and time-range controls let you zero in on specific log entries. The source breakdown at the bottom shows which services are contributing the most log volume.
@@ -291,6 +270,10 @@ The Logs page provides a viewer for structured OpenTelemetry logs collected by t
291270
Log collection requires the Observability worker with `logs_enabled: true`. See [Observability Worker](/workers/iii-observability) for configuration.
292271
</Info>
293272

273+
<Info title="Console vs console output">
274+
The iii Console (this web UI) is separate from the engine's `logs_console_output` setting. The `logs_console_output` option controls whether OTLP logs are also printed to the engine process's stdout — it does not affect the Logs page here.
275+
</Info>
276+
294277
### Log Viewer
295278

296279
| Column | Description |
@@ -300,7 +283,7 @@ The Logs page provides a viewer for structured OpenTelemetry logs collected by t
300283
| Service | The service that produced the log |
301284
| Message | The log body/message content |
302285

303-
Click on a log entry to expand and see the full JSON payload, including attributes, trace/span IDs, and resource metadata.
286+
Expanding a log entry reveals the full JSON payload, including attributes, trace/span IDs, and resource metadata.
304287

305288
### Log Filtering
306289

@@ -354,11 +337,11 @@ The flow diagram uses an auto-layout algorithm (Dagre) to arrange nodes and edge
354337

355338
Edges show the data flow direction between components — from triggers to the functions they invoke, and from functions to the state or queues they interact with.
356339

357-
- **Pan and zoom** — scroll to zoom, drag to pan
358-
- **Click a node** — view its details (function ID, trigger config, etc.)
359-
- **Auto-layout** — the graph arranges itself automatically using a directed-graph layout
340+
The graph uses auto-layout (Dagre) and supports pan, zoom, and node inspection. Layout configuration is saved to the engine's state store and restored on next visit.
360341

361-
Layout configuration is saved to the engine's state store and restored on next visit.
342+
<Info title="How-to guide">
343+
See [Use the Console](/how-to/use-console#navigate-the-flow-graph) for navigation instructions.
344+
</Info>
362345

363346
## Configuration
364347

‎docs/docs.json‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -103,15 +103,15 @@
103103
"how-to/developing-sandbox-workers"
104104
]
105105
},
106+
{
107+
"group": "Console & Observability",
108+
"pages": ["how-to/use-console", "how-to/observability-and-logs"]
109+
},
106110
"how-to/use-iii-in-the-browser",
107111
"how-to/configure-engine",
108-
"how-to/observability-and-logs",
109112
{
110113
"group": "HTTP",
111-
"pages": [
112-
"how-to/expose-http-endpoint",
113-
"how-to/use-http-middleware"
114-
]
114+
"pages": ["how-to/expose-http-endpoint", "how-to/use-http-middleware"]
115115
},
116116
{
117117
"group": "Queues",

‎docs/how-to/observability-and-logs.mdx‎

Lines changed: 13 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,13 @@ description: 'How to use structured logging, configure observability, and inspec
77

88
Make your iii application fully observable: correlate every log entry to the exact trace that produced it, inspect execution timelines to find bottlenecks, and optionally export all telemetry to third-party tools like Grafana, Jaeger, or Datadog.
99

10-
## Why use the iii Logger
10+
## The iii Logger
1111

1212
Every iii SDK ships a `Logger` class that emits logs as OpenTelemetry LogRecords. Each log call automatically captures the active **trace ID** and **span ID**, linking the log entry to the distributed trace that produced it.
1313

14-
Language-native logging functions — `console.log` in Node, `print()` in Python, `tracing::info!` in Rust — write to stdout but are **not connected to traces**. This means you cannot find them in the iii Console's trace detail view, and they are invisible to any OTLP-based observability backend.
14+
<Warning title="Native logging is not trace-correlated">
15+
Language-native logging functions such as `console.log` in Node, `print()` in Python, `tracing::info!` in Rust write to stdout but are not connected to iii traces. This means you cannot find them in the iii Console's trace detail view, and they are invisible to any OTLP-based observability backend.
16+
</Warning>
1517

1618
| Approach | Where it appears | Trace correlation |
1719
|---|---|---|
@@ -277,57 +279,21 @@ graph LR
277279
The `endpoint` field can also be set via the `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable. See the [Observability worker reference](/workers/iii-observability) for the full list of configuration fields and environment variable overrides.
278280
</Info>
279281

280-
## Using iii Console
281-
282-
The iii Console is a web UI for inspecting traces, logs, metrics, and more. It comes included with every iii installation — no separate setup required. It connects to a running iii engine and gives you full operational visibility.
283-
284-
### Launch
285-
286-
Start the console while your engine is running:
287-
288-
```bash
289-
iii-console
290-
```
291-
292-
Open [http://localhost:3113](http://localhost:3113) in your browser.
293-
294-
<Warning>
295-
The console connects to a running iii engine instance. Make sure your engine is started before launching the console. By default it expects the engine at `127.0.0.1:3111`.
296-
</Warning>
297-
298-
### Inspecting traces
299-
300-
Navigate to the **Traces** page to see all collected traces. Each trace shows its root operation, duration, service name, span count, and status.
301-
302-
Click on a trace to open the detail view with four visualization modes:
303-
304-
- **Waterfall Chart** — timeline showing every span by start time and duration. Best for understanding sequential and parallel flow.
305-
- **Flame Graph** — stack-based view where wider bars mean longer duration. Best for spotting time-consuming operations.
306-
- **Service Breakdown** — aggregate stats per service (total spans, average duration, error rate). Best for identifying bottleneck services.
307-
- **Trace Map** — topology graph showing cross-service communication patterns.
308-
- **Flow** — node graph showing parent-child span relationships for the selected trace.
309-
310-
<img src="/assets/console-traces-waterfall.png" alt="iii Console Traces waterfall view showing span timing and selected span details" />
282+
## Viewing Logs in iii Console
311283

312-
<img src="/assets/console-traces-flame-graph.png" alt="iii Console Traces flame graph view showing relative span duration within a trace" />
284+
Once you've instrumented your code with the Logger, view trace-correlated logs in the iii Console.
313285

314-
<img src="/assets/console-traces-map.png" alt="iii Console Traces map view showing service relationships in a selected trace" />
315-
316-
<img src="/assets/console-traces-flow.png" alt="iii Console Traces flow view showing parent-child span relationships as connected nodes" />
317-
318-
### Inspecting logs per trace
286+
<Info title="How-to guide">
287+
See [Use the Console](/how-to/use-console#inspect-a-trace) for step-by-step instructions on navigating traces and viewing span details.
288+
</Info>
319289

320-
Click on any span in the trace view to open the detail drawer. Switch to the **Logs** tab to see every log entry that was emitted during that span's execution. Each entry includes the severity level, timestamp, message, and structured attributes.
290+
Navigate to **Traces**, select a trace, and open the **Logs** tab on any span to see every log entry from that execution — with severity, timestamp, message, and structured attributes you attached.
321291

322292
<img src="/assets/console-logs-detail.png" alt="Trace and log inspection in iii Console with structured log details and context data" />
323293

324-
You can also use the dedicated **Logs** page for a full log viewer with severity filters, full-text search, and time-range controls. If a log entry has a `trace_id`, you can click it to jump directly to the corresponding trace.
325-
326-
### Identifying bottlenecks
327-
328-
Use the waterfall chart to spot long-running spans. Switch to the flame graph to see which operations consume the most time relative to the total trace duration. The service breakdown view aggregates performance stats so you can identify which service needs optimization.
294+
The dedicated **Logs** page provides a full log viewer with severity filters, full-text search, and time-range controls. If a log entry has a `trace_id`, click it to jump directly to the corresponding trace.
329295

330-
For more details on all console features, see the [Console reference](/console/index).
296+
For the full console feature set, see the [Console reference](/console).
331297

332298
## Result
333299

@@ -341,7 +307,7 @@ Your iii application is now fully observable:
341307
## Next steps
342308

343309
<CardGroup cols={2}>
344-
<Card title="Console" href="/console/index" icon="desktop">
310+
<Card title="Console" href="/console" icon="desktop">
345311
Full iii Console feature reference
346312
</Card>
347313
<Card title="OpenTelemetry Integration" href="/advanced/telemetry" icon="signal">

0 commit comments

Comments
 (0)