Summary: Administrators can use event logs or trace logs to troubleshoot issues related to Microsoft Business Connectivity Services on servers that are running Microsoft SharePoint Server 2010 and on Microsoft Office 2010 client applications.

Each entry to the event log or trace log has an associated Activity ID that can be used to track a problem from client or server to the external data source.

Note

In addition to the logging methods discussed in this topic, you can use Microsoft System Center Operations Manager Management Pack to monitor a solution that is based on Microsoft Business Connectivity Services. For more information about how to configure System Center Operations Manager Management Pack, see the guide included in the management pack download at Microsoft SharePoint 2010 Products Management Pack (http://go.microsoft.com/fwlink/p/?LinkId=184971).

For solutions that are based on Microsoft Business Connectivity Services, diagnostic logging occurs both on servers that are running SharePoint Server 2010 and on Office 2010 clients. There are two logs: the event log and the trace log. They both record diagnostic information that Microsoft Business Connectivity Services generate. Event logs record error messages. Trace logs contain more in-depth information, such as stack traces and informational messages. In general, trace logs provide more details than event logs.

Each logged item of information includes an Activity ID, which is a unique GUID value. Activity ID values can also be sent to external systems when a Create, Update, or Delete operation occurs on an item. By using Activity IDs, an action can be traced from the server or client to the external data source. For more information about Activity IDs, see About Activity IDs.

You can set the level of diagnostic logging for the event log and for the trace log. This will limit the types and amount of information that will be written to each log. The following tables define the levels of logging available for the event log and trace log:

Event log levels

Level

Definition

None

No logging occurs.

Critical

This message type indicates a serious error that has caused a major failure in the solution.

Error

This message type indicates an urgent condition. All error events should be investigated.

Warning

This message type indicates a potential problem or issue that might require attention. Warning messages should be reviewed and tracked for patterns over time.

Information

Information messages do not require any action, but they can provide valuable data for monitoring the state of your solution.

Verbose

This event log level corresponds to lengthy events or messages.

Trace log levels

Level

Definition

None

No trace logs are written.

Unexpected

This level is used to log messages about events that cause solutions to stop processing. When set to log at this level, the log will only include events at this level.

Monitorable

This level is used to log messages about any unrecoverable events that limit the solution’s functionality but do not stop the application. When set to log at this level, the log will also include critical errors (Unexpected level).

High

This level is used to log any events that are unexpected but which do not stall the processing of a solution. When set to log at this level, the log will include warnings, errors (Monitorable level) and critical errors (Unexpected level).

Medium

When set to this level, the trace log includes everything except Verbose messages. This level is used to log all high-level information about operations that were performed. At this level, there is enough detail logged to construct the data flow and sequence of operations. This level of logging could be used by administrators or support professionals to troubleshoot issues.

Verbose

When set to log at this level, the log includes messages at all other levels. Almost all actions that are performed are logged when you use this level. Verbose tracing produces many log messages. This level is typically used only for debugging in a development environment.

Diagnostic logs are useful both in development and production environments, but requirements for the level of logging will probably differ depending on the kind of environment. When planning for diagnostic logging in Microsoft Business Connectivity Services, consider the business needs and the lifecycle stage of the environment before you set the logging level.

For example, during solution design, you might, for debugging purposes, set both logging levels to Verbose to capture all the messages that are generated about the state of the system. Conversely, in a production environment, you might want to capture only messages in the categories High, Monitorable, and Unexpected for trace logs and the categories Critical and Error for event logs. Doing this will save logging disk space and limit any negative performance effects of logging.

A unique GUID value called an Activity ID is generated on the server and Office client for each Create, Update, or Delete operation on external data in a solution based on Microsoft Business Connectivity Services. Anything related to the operation that is logged in the trace log or event log includes its Activity ID value.

Important

In the event logs and trace log files on the server, Activity ID values are labeled as “CorrelationId” values.

The Activity ID value generated for a Create, Update, or Delete operation is sent to the external system along with other information related to that operation. If the external system has a logging mechanism, this value can be captured and logged on that system. Therefore, if an operation causes entries to the SharePoint server or Office client logs, the same operation can be traced to the external system by using its Activity ID value. This facilitates end-to-end troubleshooting of issues.

Often, an operation such as Create will cause multiple events to be written to the logs. When this happens, the same Activity ID value is used for all events that are logged for the operation. This is useful in troubleshooting issues because the recurring value of the Activity ID facilitates finding all events for a particular operation. Conversely, when the same type of operation occurs repeatedly, a unique Activity ID value is generated for each operation instance. For example, if an item of an external content type is updated twice, each update operation will be associated with a unique Activity ID value.

Tip

In some circumstances, the Business Data Connectivity service will retry an operation if it failed to go through to the external system. In those cases, the same Activity ID will be used for the retried operation.

Should diagnostic logging of Microsoft Business Connectivity Services become disabled, enable it by selecting Business Connectivity Services on the Diagnostic Logging page in SharePoint Server Central Administration. You can also use Windows PowerShell to configure event logs and trace logs on the server. For example, you can change the drive that logging writes to, and you can set the level of verbosity of logging.

Microsoft Business Connectivity Services output two categories to the trace log on SharePoint Server front end Web servers: BDC_Shared_Services and SS_Shared_Service. You can use the Event Viewer to open the trace log, and you can filter on the relevant log entries by searching on “SPS_BusinessData” (for Microsoft Business Connectivity Services outputs) and “SPS_SecureStoreService”.

Event logs and trace logs for Microsoft Business Connectivity Services solutions are available on Microsoft Office 2010 suites clients that use the Microsoft Business Connectivity Services infrastructure. By default Event logging for Microsoft Business Connectivity Services is enabled on clients. However, to protect performance, only errors and critical errors are logged and this setting cannot be changed. Windows client computers include an Event Viewer that you can use to view event logs. For information about how to view event logs for a specific version of Windows, consult the product documentation.

Trace logging is disabled by default on client computers to help enhance performance. You should only enable trace logging on client computers if you are encountering problems that you want to diagnose. For example, if an event log entry indicates an error might be caused by a an activity that is related to Microsoft Business Connectivity Services, then enable trace logging to gather additional data the next time that the event occurs.

The method for enabling trace logging and reading the logs varies depending on the version of Windows on the computer. On client computers that are running Windows 7 or Windows Vista, you can use the Performance Monitor utility to enable tracing to capture Microsoft Business Connectivity Services events. For the steps for enabling Microsoft Business Connectivity Services tracing on computers that are running Windows 7 or Windows Vista, see Use tracing on the client (SharePoint Server 2010). On computers running Windows XP, you enable tracing by running a script that uses the logman command.

The following sample script uses the logman command to enable trace logging:

As on the server, a unique Activity ID value is generated for each Create, Update, or Delete operation on an item in the client. These values are recorded in the logs and sent to external systems along with other information about operations. Also, a solution can be configured so that Activity Id values are displayed in error messages. This facilitates troubleshooting problems encountered by solution users.

Important

Because the required version of the Event Tracing for Windows programming interface on which Activity ID generation is dependent is not available on the Windows XP operating system, Activity ID generation is not supported on clients running Windows XP.

This short, simplified scenario illustrates the use of diagnostic logging in a production environment. An enterprise has deployed a new time card submission solution based on Microsoft Business Connectivity Services. This solution uses an external system to store timecard information for employees, such as vacation time and sick leave, and to interact with employees and the payroll system when employees report absence from work. Employees use a Web Part to interact with the system.

On the server farm, the logging levels are set to the default values for Microsoft Business Connectivity Services:

For the event log: Critical and Error

For the trace log: Medium

In this scenario, an employee submits a value for the number of sick leave hours but neither the employee nor his manager receives a confirming email message reporting that the sick leave time was successfully submitted. The employee calls the internal technical support service and reports the issue.

The support technician recognizes that the time card application is based on Microsoft Business Connectivity Services. She checks the event log but finds no error associated with the identity of the user at the time the user submitted the time card request. She then checks the trace log, where she finds the evidence of the activity: an Update operation associated with the user at the appropriate time. The Update operation in the trace log includes an Activity ID value which the support technician notes.

The support technician knows that logging is also supported on the external system. Using the Activity ID, she locates the item logged on the external system and finds evidence of an error written to the log at the end of the Update operation: the update failed because the employee had used up all of his allotted sick leave time. She also notes that there is no log entry confirming that an email message was generated on the external system immediately at the end of the Update operation. The support technician concludes that there is an error in the logic of the time card application. Although the application properly did not allocate sick time pay when the employee exceeded his allotted amount of hours, it failed to generate an email message informing the employee of the issue. She reports the problem to the development team that created the application and the development team updates the application.