Skip to content

Commit 184e30e

Browse files
authored
docs: add daemon logging events section (#987)
1 parent 90d842c commit 184e30e

File tree

1 file changed

+69
-0
lines changed

1 file changed

+69
-0
lines changed

docs/docs/advanced/daemon.md

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,8 @@ The `id` field on the request is used to match the request with the response. As
4343

4444
---
4545

46+
# Domains
47+
4648
To organize the accepted requests and its parameters as well as events, there are "domains." A
4749
domain is a group of related requests and events.
4850

@@ -162,3 +164,70 @@ Signals that a dev server has exited.
162164
| applicationId | String | A unique identifier for the dev server instance |
163165
| requestId | String | A unique identifier for the request that started the dev server |
164166
| exitCode | int | The exit code of the dev server process |
167+
168+
### Dev server logging events
169+
170+
The dev server will send logging events to the client as they happen. These events are identified by
171+
"dev_server.logger<Severity\>". See the [Logging events](#logging-events) section for more details.
172+
173+
- **Content**:
174+
175+
| Field | Type | Description |
176+
| ---------------- | ------ | --------------------------------------------------------------- |
177+
| applicationId | String | A unique identifier for the dev server instance |
178+
| requestId | String | A unique identifier for the request that started the dev server |
179+
| workingDirectory | String | The project directory |
180+
| message | String | The log message |
181+
182+
# Logging events
183+
184+
Some operations (eg. starting a dev server) will generate logs. These logs are sent to the client
185+
via logging events. These events are identified by the "logger" prefix on its name followed by its
186+
severity. Its domain is always associated with the operation that generated the log.
187+
188+
For example, this is logger event generate bhy the `dev_server.start` operation
189+
(the content was formatted to improve readability):
190+
191+
```json
192+
[
193+
{
194+
"event": "dev_server.loggerInfo",
195+
"params": {
196+
"applicationId": "cfd5d56a-b855-49a7-9153-a035b1ba1bc4",
197+
"requestId": "2",
198+
"workingDirectory": "/path/to/project",
199+
"message": "The Dart VM service is listening on http://127.0.0.1:8091/fWMHu3sTnYk=/"
200+
}
201+
}
202+
]
203+
```
204+
205+
In this example, it is a logger event with the `info` severity. The `params` field contains the
206+
metadata associated with the event. In this case, the `applicationId` and `requestId` fields
207+
can be used to identify the operation that generated the log.
208+
209+
The available severities are:
210+
211+
| level | identification |
212+
| -------- | ----------------------------------------------------- |
213+
| debug | `loggerDetail` |
214+
| info | `loggerInfo` <br/> `loggerSuccess`<br/> `loggerWrite` |
215+
| warn | `loggerWarning` |
216+
| error | `loggerError` |
217+
| critical | `loggerAlert` |
218+
219+
---
220+
221+
Associated with logging, there is also the progress loggings. These are used to signal the
222+
progress of a long-running operation. For example, when generating server code. These events
223+
are identified by the "progress" prefix on its name. Its domain is always associated with the
224+
operation that generated the log. The identifiers are associated not with severity but with
225+
its progress. The available identifiers are:
226+
227+
| identifier | details |
228+
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
229+
| `progressStart` | Identifies the start of the progress. Its params include `progressId` which can be used to track further events associated with this operation. |
230+
| `progressUpdate` | Identifies an update on the progress. |
231+
| `progressCancel` | Progress was cancelled. Ends the progress. |
232+
| `progressFail` | Progress has failed. Ends the progress. |
233+
| `progressComplete` | Progress has completed. Ends the progress. |

0 commit comments

Comments
 (0)