Tracing and logging

Use tracing to troubleshoot a plug-in or custom workflow activity (custom code). Tracing helps developers by recording runtime information, which aids in diagnosing the cause of code failures. Tracing supports synchronous or asynchronous execution.

A service named ITracingService records runtime tracing information for Microsoft Dataverse. Custom code can provide information to this service, which can be recorded in three different places:

Trace log

The system writes trace log records to the PluginTraceLog Table. The trace settings mentioned in Enable trace logging control the writing of these records.

You can find this data in model-driven applications by navigating to Settings and choosing the Plug-in Trace Log tile. The tile is visible only if your assigned security role grants access to the trace log table records.

You might find it easier to view this data by using the Web API in your browser, as shown in the example in Use Tracing, or by using the Plugin Trace Viewer community tool.

Important

Trace logging takes up organization storage space, especially when it generates many traces and exceptions. Only turn on trace logging for debugging and troubleshooting, and turn it off when you're done.
Error dialog

A synchronous registered plug-in or custom workflow activity that returns an exception from the platform results in an error dialog box in the web application presented to the signed-in user. The user can select the Download Log File button in the dialog to view the log containing exception and trace output.
System job

For asynchronous registered plug-in or custom workflow activities that return an exception, the tracing information appears in the Details area of the System Job form in the web application.

Enable trace logging

Whether trace logs are written depends on the value of the Organization table PluginTraceLogSetting column value. You can enable trace logging by programmatically updating the PluginTraceLogSetting value.

A second method to enable trace logging is through the legacy web application. Go to Settings > Administration > System Settings. In the Customization tab, locate the drop-down menu labeled Enable logging to plug-in trace log and select one of the available options. For more information, see Settings in Unified Interface apps and Settings in legacy web client apps.

A third option can be found in the Plug-in Registration tool. After connecting the tool to your organization (environment), select Settings > Logging to Plug-in Trace Log and then select one of the available options.

Value	Option	Description
0	Off	Writing to the trace log is disabled. No PluginTraceLog records are created. However, custom code can still call the Trace(String, Object[]) method even though no log is written.
1	Exceptions	Trace information is written to the log if an exception is passed back to the platform from custom code.
2	All	Trace information is written to the log upon code completion or an exception is passed back to the platform from the custom code.

If the trace logging setting is set to Exception and your custom code returns an exception back to the platform, a trace log record is created and tracing information is also written to one other location. For custom code that executes synchronously, the information is presented to the user in an error dialog box, otherwise, for asynchronous code, the information is written to the related system job.

Write to the tracing service

Before writing to the tracing service, you must first extract the tracing service object from the passed execution context. Afterwards, add Trace(String, Object[]) calls to your custom code where appropriate passing any relevant diagnostic information in that method call.

//Extract the tracing service for use in debugging plug-ins.
ITracingService tracingService =
    (ITracingService)serviceProvider.GetService(typeof(ITracingService));

// Use the tracing service 
tracingService.Trace("Write your message here.");

Next, build and deploy the plug-in or custom workflow activity. During execution of the custom code, the information provided in the Trace method calls is written to a trace log table record by ITracingService, if supported by your organization and enabled, and might also be made available to the user in a Web dialog or system job as described in the previous section. Tracing information written to the trace log is configured in the trace settings. For more information, see Enable trace logging.

Note

If your custom code executes within a database transaction, and an exception occurs that causes a transaction rollback, all table data changes by your code are undone. However, the PluginTraceLog records remain after the rollback completes.

Additional information about the tracing service

The ITracingService batches the information it receives through the Trace method. It writes the information to a new PluginTraceLog record after the custom code runs successfully or throws an exception.

Each Trace call is logged as a new line in the PluginTraceLog MessageBlock column. You can write only 10 KB of text. To meet this limit, the system removes older trace lines so that only the most recent lines are saved.

PluginTraceLog records have a finite lifetime. A bulk deletion background job runs once per day to delete records that are older than 24 hours from creation. To prevent excessive database growth, Microsoft might disable logging to Plug-in Trace Log if the plugintracelogbase table exceeds 100 GB in size.

Caution

While you can disable this job or adjust the frequency at which it occurs, failing to set it back to the original setting can cause performance problems.

Community tools

Plugin Trace Viewer

Plugin Trace Viewer is a tool that the XrmToolBox community developed. For community-developed tools, see the Community tools for Dataverse article.

Note

Microsoft doesn't provide support for community tools. If you have questions about the tool, contact the publisher. For more information, see XrmToolBox.

Зворотний зв’язок

Чи була ця сторінка корисна?

Last updated on 2026-08-21