Diagnostics.Trace

Updated on

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

Syntax

Diagnostics.Trace(
   traceLevel as number,
   message as any,
   value as any,
   optional delayed as nullable logical,
) as any
ArgumentAttributeDescription
traceLevelSpecifies the TraceLevel.Type that indicates a message’s urgency.
messageDefines the text written to the trace log.
value Determines the function’s return value.
delayedoptionalDecides if the value returned is immediate or requires a zero-parameter function call.

Description

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.

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

Examples

Let’s see some examples on 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:

Other functions related to Diagnostics.Trace are:

BI Gorilla Youtube Channel

Contribute » | Contributors: Rick de Groot
Microsoft documentation: https://learn.microsoft.com/en-us/powerquery-m/diagnostics-trace