Diagnostics.Trace is a Power Query M function that writes a trace message, if tracing is enabled, and returns a specified value. The function returns the given value after the trace message has been written.
Compatible with: Power BI Service Power BI Desktop Excel Microsoft 365
Diagnostics.Trace( traceLevel as number, message as any, value as any, optional delayed as nullable logical, ) as any
|traceLevel||Specifies the TraceLevel.Type that indicates a message’s urgency.|
|message||Defines the text written to the trace log.|
|value||Determines the function’s return value.|
|delayed||optional||Decides if the value returned is immediate or requires a zero-parameter function call.|
The Diagnostics.Trace function in Power Query M allows users to insert messages into the M engine’s trace log. It’s essential to note that due to M’s lazy evaluation nature, this function will only execute if the related expression is assessed.
Users can specify a TraceLevel.Type, such as
These determine the message’s urgency. When a specific trace level is set, all messages at that level and higher severity are logged.
message parameter defines the text written to the trace log, while the
value parameter determines the function’s return. Additionally, the
delayed parameter decides if the value returned is immediate or requires a zero-parameter function call.
Writes a trace
message, if tracing is enabled, and returns
value. An optional parameter
delayed specifies whether to delay the evaluation of
value until the message is traced.
Let’s see some examples of how to use the Diagnostics.Trace function.
To trace the message before invoking Text.From function and return the result.
// Output: "123" Diagnostics.Trace( TraceLevel.Information, "TextValueFromNumber", () => Text.From( 123 ), true )
Whereas the above function performs the tracing on a function you can also reference another query. Imagine you want to get diagnostics information for a query called ‘Calendar’, you can adjust the code to:
Diagnostics.Trace( TraceLevel.Information, "CalendarCreation", Calendar, true )
Using the Delayed Parameter
You can also use the delayed parameter. This parameter specifies whether to delay the evaluation of
value until the message is traced. By specifying false, the value is executed immediately.
Diagnostics.Trace( TraceLevel.Error, "Couldn't find entity: x", error "message", false )
When you execute this query, you’ll get the accurate error message as expected. However, if you navigate to the Log tab to see the recorded messages, you’ll notice that no messages have been saved. This happens because the error is generated during the
Diagnostics.Trace call itself, meaning the message is never actually output for the trace.
Learn more about Diagnostics.Trace in the following articles:
- Power BI Diagnostics, Trace Logs And Query Execution Times (Again)
By using the Diagnostics.Trace() function, Chris Webb demonstrates a way of logging query execution times, offering a workflow for tuning and assessing query performance. » Read more
- TripPin part 8 – Adding diagnostics
This article explains how you can use Diagnostics.Trace as helper function to add trace information to help debug your connector, » Read more
Other functions related to Diagnostics.Trace are: