Diagnostic logging in Business Connectivity Services overview (SharePoint Foundation 2010)

Article
07/22/2014

Applies to: SharePoint Foundation 2010

You can troubleshoot issues related to Microsoft Business Connectivity Services on servers that are running Microsoft SharePoint Foundation 2010 by using event logs and trace logs on either client or server. Also, each entry to the event log or trace log has an associated Activity ID that can be used to track a problem from the 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 (https://go.microsoft.com/fwlink/?LinkId=184971).

In this article:

Diagnostic logging in Business Connectivity Services

For solutions that are based on Microsoft Business Connectivity Services, diagnostic logging occurs on servers that are running Microsoft SharePoint Foundation. 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.

About Activity IDs

A unique GUID value called an Activity ID is generated 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 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.

Diagnostic logging on servers

By default, Microsoft Business Connectivity Services logging is enabled on SharePoint Foundation servers. The default logging levels are:

For the event log: Critical and Error
For the trace log: Medium

Should diagnostic logging of Microsoft Business Connectivity Services become disabled, enable it by selecting Business Connectivity Services on the Diagnostic Logging page in SharePoint Foundation 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.

For more information about logging in SharePoint Foundation 2010, such as how to set the location of the log files, see Configure diagnostic logging (SharePoint Foundation 2010).

You can use Windows PowerShell to view the event logs on the server by and you can export the logs, for example to a spreadsheet program. For more information, see View diagnostic logs (SharePoint Foundation 2010).

Microsoft Business Connectivity Services output two categories to the trace log on SharePoint Foundation 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”.

Example: using diagnostic logging

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.

Share via