Configuring ULS via PowerShell
The options for ULS configuration
provided by Central Admin are great, but a few additional options are
not available in the browser, and configuring each filtering category
manually can be frustrating. Fortunately, PowerShell comes to the
rescue! All of the options available via Central Admin (and then some)
are exposed in PowerShell cmdlets, opening up the possibility of
scripting, remote management through PowerShell, and more.
The PowerShell cmdlets for managing ULS are
divided into two groups of commands. The first group of cmdlets is for
managing the ULS event filtering categories and is fairly
straightforward. Get-SPLogLevel
will display the current severity filters for the various logging
categories, but be prepared for this command to return several screens
of data. You can filter the results down to only what you are looking
for by using the command’s Identity parameter, passing it a string in the "Area:Name"
format. For instance, if you wanted to see only the setting for the
Administration subcategory of area Access Services, the command would
be as follows:
Get-SPLogLevel -Identity "Access Services:Administration"
Figure 3
shows the output of that command. You can also use an asterisk to
specify all the subcategories of a given area, such as the following:
"Access Services:*"
Notice that, unlike the corresponding Central
Admin page, the output from this cmdlet doesn’t indicate whether any
values have been changed from their defaults, so you still have to rely
on the Central Admin page for that information. You can set a new
logging level for one or more categories with Set-SPLogLevel and reset a category to the default level with Clear-SPLogLevel. Both of these cmdlets accept the same type of Identity filtering shown earlier for Get-SPLogLevel.
The second group of commands enables additional
control of the Event Log flood protection, and of the trace log path
and retention options. The cmdlet Get-SPDiagnosticConfig
will return the currently configured values. You may recognize a few of
the values (such as LogLocation or LogDiskSpaceUsageGB) from the
Central Admin configuration, but additional options are exposed as
well. For instance, LogCutInterval specifies the number of minutes that
ULS will use a log file before starting a new one, and there are
additional threshold and interval values to tune the Event Log flood
protection.
Now that you know what options are available, you can set them with the Set-SPDiagnosticConfig cmdlet. For instance, Set-SPDiagnosticConfig -LogCutInterval 15Set-SPDiagnosticConfig -EventLogFloodProtectionTriggerPeriod 3 would cause ULS to look for five of the same events within a three-minute window, rather than the default two-minute window. would cause ULS to move to a new log file every 15 minutes, and
Two additional cmdlets can be very useful for troubleshooting. New-SPLogFile
manually triggers the creation of a new log file, which can be useful
when you want to re-create an issue but not have to sort through
hundreds of previous log entries. This is very helpful if you want to
isolate the events from a specific operation into a known ULS log file.
This might be for your own use or if you’ve been asked to send the ULS
log to someone who is helping you troubleshoot a problem. You can run New-SPLogFile
right before reproducing the issue. After you’ve reproduced it, and it
has spewed some events in the ULS log, wait a couple of minutes for
everything to flush out, then run New-SPLogFile again.
Because SharePoint 2013 servers work as a team,
you never know for sure if the key to solving the issue you’re fighting
lies in a log file on another server in your farm. Merge-SPLogFile
is used to merge all the ULS logs from all the machines in your farm
into one large, trouble-finding file. With no parameters, it will
schedule a timer job on each member of the farm to take its last hours’
worth of logs and copy them to a single file on the machine where you
ran Merge-SPLogFile. Because
it’s timer job-based, you have to be patient; it takes a couple of
minutes to be completely populated. Once it is full you can open it and
follow all the events in the farm on all the servers. In most cases, an
hour is way too many events. You really only need the last five or ten
minutes’ worth. Fortunately, you have several ways to prune the results
of Merge-SPLogFile. You can filter by user, category, level, or time.
One of the handiest ways is to get the last 10 minutes’ worth of
events. To do that you would use the following command:
Merge-SPLogFile –Path E:\Logs\BigFile.txt –StartTime (Get-Date).AddMinutes(-10)
CORRELATION ID: WHAT IT IS (AND IS NOT)
When an error occurs that results in an
error message being sent back to the browser, it usually includes a
value named “correlation ID” along with the error. There is a common
misconception that a correlation ID value (as shown on an error
message) is a form of error number or error code that inherently means
something; and end users often ask SharePoint administrators what the
error means based on this value. However, correlation IDs are not error
codes, but rather GUIDs assigned by SharePoint to every conversation,
allowing that request to more easily be tracked through the logs. This
enables you to correlate or group events together, making it easy to
find the whole series of events that led up to the issue you’re looking
at.
When ULS writes entries into
the trace logs, it also includes the correlation ID value of the
request that caused that log entry to be generated, so if you know the
correlation ID of the request that generated an error, you can filter
the log for all entries that are tagged with that correlation ID,
enabling you to see the full history of the request from start to
finish. Note that it is also important to have the date and time at
which the error was received, so that you know which log file to look
in when searching for the correlation ID.
