Skip to content

Commit 6883779

Browse files
Draft resource authoring design guide
This change drafts the conceptual documentation for guidance on how to author DSC resources from a design perspective. It does not include any specific guidance from a code or language perspective. Instead, it focuses on the high level concepts and on defining the resource manifest and instance JSON Schema. This change is a mirror of the one submitted to the source repository: - PowerShell/DSC#1027
1 parent a094449 commit 6883779

File tree

10 files changed

+1161
-1
lines changed

10 files changed

+1161
-1
lines changed
Lines changed: 326 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,326 @@
1+
---
2+
description: >-
3+
Considerations and guidance for emitting messages from a DSC resource.
4+
ms.date: 08/15/2025
5+
title: Emitting messages from a DSC resource
6+
---
7+
8+
# Emitting messages from a DSC resource
9+
10+
DSC uses a messaging system to provide runtime information to users. By default, DSC emits messages
11+
as strings to stderr with ANSI console coloring for the timestamp, message level, and line number.
12+
You can use the [--trace-format](../../../reference/cli/index.md#--trace-format) option to have DSC
13+
emit the messages to stderr without console coloring or as JSON Lines.
14+
15+
DSC supports consuming and surfacing messages from resources to provide context and helpful
16+
information to users.
17+
18+
This document provides an overview of the messaging system and guidance for how a resource should
19+
integrate with DSC to emit useful messages.
20+
21+
## DSC message levels
22+
23+
Messages in DSC are categorized by their level. The following list shows the valid message levels
24+
from highest to lowest level.
25+
26+
- `error` - messages at this level indicate critical problems.
27+
- `warn` (default) - messages at this level provide important information that may affect usage
28+
and behavior.
29+
- `info` - messages at this level provide useful but less important information about operational
30+
behavior.
31+
- `debug` - messages at this level surface verbose information primarily useful for troubleshooting
32+
and investigating.
33+
- `trace` - messages at this level surface extremely verbose and low-level information for
34+
troubleshooting and investigating.
35+
36+
> [!WARNING]
37+
> The `trace` level output emits all JSON input/output that DSC processes during execution. DSC
38+
> doesn't sanitize the JSON before emitting it. This trace level is only intended for developer
39+
> use. Never redirect `trace` level output to storage as it might contain sensitive information.
40+
41+
Users can configure the trace level for DSC by specifying the
42+
[--trace-level](../../../reference/cli/index.md#--trace-level) command option, setting the
43+
[DSC_TRACE_LEVEL](../../../reference/cli/index.md#environment-variables) environmental variable, or
44+
by modifying the settings for DSC.
45+
46+
The trace level defines the minimum message type to emit when using DSC. Because the default trace
47+
level is `warn`, DSC only emits error and warning messages by default. The following table shows
48+
how the trace level determines which messages DSC emits:
49+
50+
| Trace level | Emitted message levels |
51+
|:-----------:|:------------------------------------------|
52+
| `error` | `error` |
53+
| `warn` | `error`, `warn` |
54+
| `info` | `error`, `warn`, `info` |
55+
| `debug` | `error`, `warn`, `info`, `debug` |
56+
| `trace` | `error`, `warn`, `info`, `debug`, `trace` |
57+
58+
## DSC message output
59+
60+
By default, DSC emits trace messages to stderr with ANSI console coloring.
61+
62+
When a user specifies the [--trace-format](../../../reference/cli/index.md#--trace-format) option
63+
as `plaintext`, DSC emits the messages in the same format but without console colors.
64+
65+
When a user specifies the format as `json`, DSC emits each message as a JSON Line to stderr.
66+
67+
When the [--trace-level](../../../reference/cli/index.md#--trace-level) option is set to `debug` or
68+
`trace`, DSC includes additional information about where in _DSC's code_ the message was emitted.
69+
70+
### Console message output
71+
72+
When the trace level is set to `info`, `warn`, or `eror`, DSC emits messages from resources to
73+
stderr with the following syntax:
74+
75+
```Syntax
76+
<timestamp> <level> PID <pid>: <resource-message>
77+
```
78+
79+
- `<timestamp>` is the ISO8601 timestamp for when DSC emitted the message from the resource. It
80+
doesn't represent the timestamp for when the _resource emitted_ the message.
81+
- `<level>` is the all-caps representation of the messaging level: `ERROR`, `WARN`, `INFO`,
82+
`DEBUG`, or `TRACE`.
83+
- `<pid>` is the process ID for the process DSC spawned to invoke the resource.
84+
- `<resource-message>` is the string value of the message emitted by the resource.
85+
86+
For example:
87+
88+
```console
89+
2025-08-15T14:42:53.970726Z WARN PID 29072: Message from resource
90+
```
91+
92+
When the trace level is set to `debug` or `trace`, DSC emits messages from resources to stderr with
93+
the following syntax:
94+
95+
```Syntax
96+
<timestamp> <level> <dsc-source-module>: <dsc-source-line>: PID <pid>: <resource-message>
97+
```
98+
99+
- `<timestamp>` is the ISO8601 timestamp for when DSC emitted the message from the resource. It
100+
doesn't represent the timestamp for when the _resource emitted_ the message.
101+
- `<level>` is the all-caps representation of the messaging level: `ERROR`, `WARN`, `INFO`,
102+
`DEBUG`, or `TRACE`.
103+
- `<dsc-source-module>` indicates where in the DSC source code the message was emitted from, using
104+
Rust module path syntax.
105+
- `<dsc-source-line>` indicates which line in the DSC source code the message was emitted from.
106+
- `<pid>` is the process ID for the process DSC spawned to invoke the resource.
107+
- `<resource-message>` is the string value of the message emitted by the resource.
108+
109+
For example:
110+
111+
```console
112+
2025-08-15T14:57:02.218913Z WARN dsc_lib::dscresources::command_resource: 901: PID 34460: Message from resource
113+
```
114+
115+
### JSON message output
116+
117+
When the trace format is `json` and the trace level is set to `info`, `warn`, or `eror`, DSC emits
118+
messages from resources to stderr as JSON Line objects with the following properties:
119+
120+
- `timestamp` - the ISO8601 timestamp for when DSC emitted the message from the resource. It
121+
doesn't represent the timestamp for when the _resource emitted_ the message.
122+
- `level` - is the all-caps representation of the messaging level: `ERROR`, `WARN`, `INFO`,
123+
`DEBUG`, or `TRACE`.
124+
- `fields` - is an object with the `message` string subproperty containing the message from the
125+
resource. The message is prefixed with `PID <pid>:` where `<pid>` is the process ID for the
126+
process DSC spawned to invoke the resource.
127+
128+
For example:
129+
130+
```json
131+
{
132+
"timestamp": "2025-08-18T19:47:43.376148Z",
133+
"level": "WARN",
134+
"fields": {
135+
"message": "PID 1508: Message from resource"
136+
}
137+
}
138+
```
139+
140+
When the trace format is `json` and the trace level is set to `debug` or `trace`, DSC emits
141+
messages from resources to stderr as JSON Line objects with the following properties:
142+
143+
- `timestamp` - the ISO8601 timestamp for when DSC emitted the message from the resource. It
144+
doesn't represent the timestamp for when the _resource emitted_ the message.
145+
- `level` - is the all-caps representation of the messaging level: `ERROR`, `WARN`, `INFO`,
146+
`DEBUG`, or `TRACE`.
147+
- `fields` - is an object with the `message` string subproperty containing the message from the
148+
resource. The message is prefixed with `PID <pid>:` where `<pid>` is the process ID for the
149+
process DSC spawned to invoke the resource.
150+
- `target` - indicates where in the DSC source code the message was emitted from, using
151+
Rust module path syntax.
152+
- `line_number` - indicates which line in the DSC source code the message was emitted from.
153+
154+
For example:
155+
156+
```json
157+
{
158+
"timestamp": "2025-08-18T20:37:55.100565Z",
159+
"level": "WARN",
160+
"fields": {
161+
"message": "PID 16160: Message from resource"
162+
},
163+
"target": "dsc_lib::dscresources::command_resource",
164+
"line_number": 921
165+
}
166+
```
167+
168+
## How DSC consumes messages from resources
169+
170+
DSC processes lines of text emitted to stderr by a resource using the following procedure:
171+
172+
1. If the emitted line is JSON, DSC deserializes it and checks whether it defines a level property:
173+
174+
- If the object defines the `error` property, DSC emits an error-level message, using the value
175+
of `error` as the message text.
176+
- If the object defines the `warn` property, DSC emits a warning-level message, using the value
177+
of `warn` as the message text.
178+
- If the object defines the `info` property, DSC emits an info-level message, using the value of
179+
`info` as the message text.
180+
- If the object defines the `debug` property, DSC emits a debug-level message, using the value
181+
of `debug` as the message text.
182+
- If the object defines the `trace` property, DSC emits a trace-level message, using the value
183+
of `trace` as the message text.
184+
185+
If the object doesn't define any of the level properties, DSC emits a trace-level message, using
186+
the emitted line as the message text without unwrapping the JSON.
187+
1. If DSC can't parse the line as JSON, DSC emits a trace-level message, using the line as the
188+
message text.
189+
190+
DSC always prefixes the message text with the `PID <pid>:` prefix, where `<pid>` is the ID for the
191+
process DSC spawned to invoke the resource.
192+
193+
### Emitting structured data
194+
195+
Currently, DSC only supports emitting string messages at the defined levels. DSC can't bubble up
196+
additional structured data with the message due to limitations in the tracing library DSC uses.
197+
Instead, to send structured data, use the following convention:
198+
199+
1. Create a JSON object representing your data:
200+
201+
```json
202+
{
203+
"key1": true,
204+
"key2": "key2 value"
205+
}
206+
```
207+
208+
1. Convert the JSON to an escaped string representation of the data as compressed JSON:
209+
210+
```json
211+
"{\"key1\":true,\"key2\":\"key2 value\"}"
212+
```
213+
214+
1. Emit a message with the appropriate level as a JSON Line:
215+
216+
```json
217+
{"info":"{\"key1\":true,\"key2\":\"key2 value\"}"}
218+
```
219+
220+
This convention requires the caller to unwrap the emitted data from the trace that DSC emits.
221+
222+
## Emitting error messages
223+
224+
By default, DSC recognizes failures for resource operations by inspecting the exit code your
225+
resource returns for an operation invocation. If your manifest defines useful
226+
[exit codes](./exit-codes.md), DSC can provide a human-readable synopsis for why the operation
227+
failed.
228+
229+
Resources should emit error messages prior to returning a nonzero exit code to provide more
230+
detailed information that a user can reference for troubleshooting.
231+
232+
To emit a `error` level message from your resource, emit a JSON Line to stderr with a single
233+
property, `error`, where the value is a string representing the message you want to emit.
234+
235+
For example:
236+
237+
```json
238+
{"error":"Message contents"}
239+
```
240+
241+
## Emitting warning messages
242+
243+
Resources should emit warning messages to indicate non-critical issues and information about the
244+
resource's behavior to the user.
245+
246+
Consider emitting warning messages under the following guidelines:
247+
248+
- Emit a warning message when your resource is aware of an important concern that won't cause the
249+
execution of the current operation to fail but may affect other operations.
250+
- Emit a warning message when your resource needs to inform a user about effects of an operation
251+
that aren't obvious or expected by default.
252+
253+
To emit a `warn` level message from your resource, emit a JSON Line to stderr with a single
254+
property, `warn`, where the value is a string representing the message you want to emit.
255+
256+
For example:
257+
258+
```json
259+
{"warn":"Message contents"}
260+
```
261+
262+
## Emitting info messages
263+
264+
Resources should emit info messages to provide non-critical information about the resource's
265+
behavior to the user.
266+
267+
Consider emitting info messages under the following guidelines:
268+
269+
- Emit an info message when you want to surface context or information to a user about the behavior
270+
of the resource.
271+
- Don't emit info messages for low-level details about the internals of your resource.
272+
273+
To emit a `info` level message from your resource, emit a JSON Line to stderr with a single
274+
property, `info`, where the value is a string representing the message you want to emit.
275+
276+
For example:
277+
278+
```json
279+
{"info":"Message contents"}
280+
```
281+
282+
## Emitting debug messages
283+
284+
Resources can emit debug messages to help users and integrating developers troubleshoot resource
285+
behavior.
286+
287+
Consider emitting debug messages under the following guidelines:
288+
289+
- Emit a debug message when you want to provide context for troubleshooting the resource.
290+
- Emit debug messages consistently. If you emit a debug message indicating the start of an internal
291+
function or loop, also emit a debug message when that internal operation ends.
292+
293+
To emit a `debug` level message from your resource, emit a JSON Line to stderr with a single
294+
property, `debug`, where the value is a string representing the message you want to emit.
295+
296+
For example:
297+
298+
```json
299+
{"debug":"Message contents"}
300+
```
301+
302+
## Emitting trace messages
303+
304+
Generally, resources shouldn't emit trace messages. If you need to provide more detailed
305+
information than implied by debug messages, emit that information as trace messages.
306+
307+
Consider emitting trace messages under the following guidelines:
308+
309+
- Emit trace messages to provide extremely low-level information about the internal processing of
310+
the resource.
311+
- Emit trace messages for maintainers and integrating developers to use when investigating and
312+
troubleshooting resource behavior.
313+
314+
To emit a `trace` level message from your resource, emit a JSON Line to stderr with a single
315+
property, `trace`, where the value is a string representing the message you want to emit.
316+
317+
For example:
318+
319+
```json
320+
{"trace":"Message contents"}
321+
```
322+
323+
## Related content
324+
325+
- [Designing a DSC resource](./index.md)
326+
- [Defining exit codes for a DSC resource](./exit-codes.md)

0 commit comments

Comments
 (0)