Diagnostics.Trace

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

Argument	Attribute	Description
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.

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

• TraceLevel.Critical 
• TraceLevel.Error
• TraceLevel.Warning
• TraceLevel.Information
• TraceLevel.Verbose

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.

Related articles

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

Related functions

Other functions related to Diagnostics.Trace are:

• Diagnostics.ActivityId
• Diagnostics.CorrelationId
• Error.Record

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