Troubleshooting Office files and custom solutions with the telemetry log

Use the Telemetry Log for Office 2013 to determine compatibility issues with Office 2013 and solutions built for previous versions of Office.

The following article describes the Telemetry Log and how to use it. For more information about specific results displayed in the Telemetry Log, see Compatibility issues in Office.

Over the course of many releases, Microsoft has provided tools and frameworks for customizing, automating, and extending Office. This has enabled businesses and users to build solutions or add-ins for Office applications to improve their productivity and efficiency. These solutions can range in complexity from simple Visual Basic for Applications (VBA) macros to robust .NET Framework customizations. Many users who have these solutions rely on them to complete business-critical tasks and may not even know that they are using a customization that is added to their Office applications.

With such a proliferation of Office solutions, upgrading versions of Office can be complex. Enterprises and users do not know whether their important and valuable solutions are completely compatible with the new version. Their solutions might use features and computer code that are available in previous versions of Office that have been deprecated in later versions. If a solution that uses a deprecated feature is loaded into the "host" application, the solution might behave differently, cause an error, fail to load, or cause the host application to fail.

The Telemetry Log for Office 2013, a tool built upon Excel 2013, helps developers and experienced users diagnose compatibility issues by displaying events that occur within select Office 2013 applications. Using this tool, users can determine potential issues with add-ins that they use in their work environment, giving enterprise decision-makers the information that they need to decide whether to upgrade to Office 2013. The Telemetry Log also gives detailed feedback about specific changes or deprecations in the object models for the Office 2013 applications, which helps developers quickly identify and refactor problematic code or controls. IT professionals can view trends in solution health across multiple clients by using the Telemetry Dashboard for Office 2013, a companion tool to the Telemetry Log.

For more information, see Deploy Office Telemetry Dashboard.

How the Telemetry Log works

When an Office file or solution is loaded, used, closed, or raises an error in one of the selected Office 2013 applications, the application adds a record in a local data store (a database on the same computer) that includes information about the event. The record includes a title for the event, the application that logged the event, the time, the name of the file or solution, the severity, and a short description of any errors that may have occurred. When refreshed, the Telemetry Log workbook displays a list of the records contained in the local data store.

Selected Office 2013 applications have a run-time logging API that creates a record in the local data store every time that a file or solution raises one of the following events:

• OnLoad: A record is logged in the local data store when a file or solution is loaded into specific Office 2013 applications. The run-time error logging records the file name, location, and other information in the local data store when an OnLoad event is raised.

• OnClose: A record is logged when a file or solution is closed within the application. The record includes the name of the solution or file, its location, and the application that logged the event.

• OnError: A record is logged when an error is found in a solution for certain Office 2013 applications. The record includes the name of the solution or file and the run-time failure or compatibility issue that the user encountered. When possible, errors are mapped to known compatibility issues and are displayed as such in the Telemetry Log.

The Telemetry Log displays information about a large list of files and solution types for a selection of Office 2013 applications. The type of files and solutions that are monitored by the run-time logging APIs vary by application. See the Table 1 for more information about what kinds of solutions are monitored.

Table 1. Types of Office files and solutions tracked in Telemetry Log

Using the Office Telemetry Log

When you install Office 2013, the Telemetry Log is installed, the local data store is created on the same computer, and the run-time logging APIs are enabled in the Office 2013 applications previously listed. However, a solution or file must be loaded or opened in the application before the Telemetry Log can start to monitor it.

Use the following procedure to display the recorded Office issues in the Telemetry Log.

To use the Telemetry Log

1. To open the Telemetry Log, do one of the following:

   • On Windows 7: On the Start menu, choose All Programs. Then, in the list of programs, expand Microsoft Office 2013, expand Office 2013 Tools, and then click Office 2013 Telemetry Log.

     A new workbook in Excel 2013 opens. The workbook has three worksheets titled Events System info, and Guide.

   • On Windows 8: Swipe up to display the AppBar, choose All Apps, and then choose Office 2013 Telemetry Log.

     A new workbook in Excel 2013 opens. The workbook has three worksheets titled Events System info, and Guide.

2. To view an up-to-date list of events, on the Events worksheet, at the top of the worksheet, choose Refresh.

3. To view the event data that is collected from Office 2013 applications, review the table displayed on the Events worksheet.

4. To review information about the computer on which Office 2013 and Telemetry Log are installed, review the information displayed on the System Info worksheet.

The Telemetry Log displays some simple information about the recorded events. Each record displayed in the Telemetry Log contains a title and lists the severity of the event displayed. For errors, the records also include a description of the error together with steps to address the issue. Keep in mind that not all of the records displayed represent errors caused by Office solutions; the Telemetry Log also shows when solutions and files are loaded or closed successfully.

For example, the issue titled "OM Hidden: Comment.Initial Property" appears if a solution or macro-enabled file opened in Word 2013 attempts to get the initials of a commenter who is associated with a comment. Word 2013 features an improved commenting experience that does not display commenter initials by default. The APIs associated with the older commenting model have been hidden in the Word 2013 object model but remain available for backwards-compatibility. The "OM Hidden: Comment.Initial" issue in the indicates the file that attempted to use the API, the application that raised the event (Word 2013), the time and date of the event, and short description about the error and how to fix it.

Figure 1. Office Telemetry Log

In the Telemetry Log, a level of severity is displayed together with the known issues. From the previous example, an issue in which a part of the object model has been hidden most often has an "Informative" level of severity. On the other hand, other known issues might be more serious and require more immediate action. The severity of the issues displayed in the Telemetry Log can be one of the following:

• Information The issue may not have an immediate effect on application compatibility, but the user may have to take an action later. Many issues of the "OM hidden" type have this severity level.
• Warning The issue could cause data loss or result in reduced visual fidelity.
• Critical The issue could cause significant loss of functionality or lead the application to crash.

Table 2. Types of events displayed in the Telemetry Log

Use the following table (Table 2) to interpret the records that are displayed in the Telemetry Log.

Conclusion

The Telemetry Log provides large enterprises, individual users, and developers with a simple tool for monitoring their critical Office solutions. By identifying problematic Office solutions before a large-scale upgrade, businesses can more reasonably predict the cost of adopting Office 2013.

See also

• Office Developer Center
• Compatibility issues in Office
• Deploy Office Telemetry Dashboard