Monitoring and Diagnostic logging in Business Connectivity Services overview (SharePoint Server 2010)

Applies to: SharePoint Server 2010

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.

In this article:

• Diagnostic logging in Business Connectivity Services

• About Activity IDs

• Diagnostic logging on servers

• Diagnostic logging on Office 2010 clients

• Example: using diagnostic logging

Diagnostic logging in Business Connectivity Services

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

Trace log levels

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 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.

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.

Diagnostic logging on servers

By default, Microsoft Business Connectivity Services logging is enabled on SharePoint Server 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 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.

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

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

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”.

Diagnostic logging on Office 2010 clients

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:

rem This script will enable logging, directing log messages to a file specified by the "%FILE_NAME%" given by the user.

@setlocal
@echo off
pushd %~dp0
set PATH_NAME=%TEMP%\BCS
set FILE_NAME=%PATH_NAME%\ETWTraceLog
set TRACE_COLLECTION=BCS
::tracelog -start BCS -guid #b8622a02-c377-46b1-b861-38a787a8e44a -b 128 -flags 0xFFFF -level 5 -f "%FILE_NAME%.etl"
md "%PATH_NAME%" 1>nul 2>nul
logman create trace %TRACE_COLLECTION% -p "{b8622a02-c377-46b1-b861-38a787a8e44a}" 0xFFFF 5 -o "%FILE_NAME%.etl" -ets
echo.
echo Business Connectivity Services tracing has been started. To end press any key.
echo.
pause

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.

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.

See Also

Concepts

Use tracing on the client (SharePoint Server 2010)
Monitoring overview (SharePoint Server 2010)
Configure diagnostic logging (SharePoint Server 2010)
Business Connectivity Services overview (SharePoint Server 2010)

Other Resources

Resource Center: Business Connectivity Services in SharePoint Server 2010