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