Debugging SharePoint Issues and ULS Log Files

I often see administrators and developers new to SharePoint find debugging difficult and complex.

When working with SharePoint, log files are your friend.  In large on-premise farms, locating issues within large log files can be time consuming and sometimes difficult. When I am presented with an error that contains a correlation ID, I first resort to PowerShell instead of a ULS Viewer.

Three PowerShell cmdlets that are your friend are: New-SPLogFile, Get-SPLogEvent and Merge-SPLogFile.

Before you can use these cmdlets in your PowerShell scripts, make sure to load the SharePoint PowerShell snapin.

if((Get-PSSnapin -Name Microsoft.SharePoint.PowerShell -ErrorAction SilentlyContinue) -eq $null)
{
    Add-PSSnapin Microsoft.SharePoint.PowerShell -ErrorAction SilentlyContinue
}

New-SPLogFile

The New-SPLogFile cmdlet ends the current log file and starts a new log file. This cmdlet can be of significant help if you can reproduce your issue. Simply call New-SPLogFile, reproduce your issue then run New-SPLogFile again. The resulting small(er) log file can then be interrogated for the correlation id and issues.

Use this cmdlet to reduce the log file being inspected before calling Get-SPLogEvent, Merge-SPLogFile or opening in the ULS viewer.

New-SPLogFile
# Duplicate the error
New-SPLogFile

Get-SPLogEvent

The Get-SPLogEvent cmdlet will retrieve specific events from a ULS Log File.  For example, the following call will retrieve all entries that occurred during a specified time range:

Get-SPLogEvent -StartTime "12/04/2007 17:00" -EndTime "12/04/2007 18:00"

If you wish to retrieve ULS entries associated with a specific correlation ID, you can use the following:

Get-SPLogEvent | ? {$_.Correlation -eq "<Correlation ID>"} | Select Area, Category, Level, EventID, Message

Where <Correlation ID> is the id you wish to filter.

If you wish to display the results in a nicely formatted list, add Format-List:

Get-SPLogEvent | ? {$_.Correlation -eq "<Correlation ID>"} | Select Area, Category, Level, EventID, Message | Format-List

Be patient when running the Get-SPLogEvent cmdlet as it can take quite a long time to traverse through all the ULS log files.

I have a diagnostics PowerShell library that contains many functions that simplify diagnosing issues, writing log files, etc.  One of the functions in this library is my Get-SPLogEventByCorrelationID.  Which simply calls the Get-SPLogEvent cmdlet and filters the results by a specified correlation ID.

function Get-SPLogEventByCorrelationID
{
    [CmdletBinding()]
    Param([Parameter(Mandatory=$true)]
        [string]$CorrelationID
    )
    $logEntries = Get-SPLogEvent | ? {$_.Correlation -eq $CorrelationID} | Select Area, Category, Level, EventID, Message
    return($logEntries)
}

For more information on using the Get-SPLogEvent cmdlet, see the following:

• TechNet – Get-SPLogEvent
• Viewing and filtering of ULS logs using powershell in Sharepoint 2013 – written by Kusal Pokala

Merge-SPLogFile

The Merge-SPLogFile cmdlet combines ULS log entries, from all servers in a SharePoint farm, to a single (specified) log file.

The following example will merge all ULS log files for the last hour:

Merge-SPLogFile -Path "C:\Logs\FarmMergedLog.log" -Overwrite

If you wish to merge all ULS log events for a specific correlation ID, you can use the following call:

Merge-SPLogFile -Path "C:\Logs\FarmMergedLog.log" -Correlation "<Correlation ID>" -Overwrite

Where <Correlation ID> is the id you wish to filter.

As with the Get-SPLogFile, I have included some common functions in my diagnostics library.  One that I use on a regular basis is Merge-SPLogFileByCorrelationID

function Merge-SPLogFileByCorrelationID
{
    [CmdletBinding()]
    Param(
        [Parameter(Mandatory=$true)]
            [string]$CorrelationID,
        [Parameter(Mandatory=$false)]
            [bool]$Overwrite=$false,
        [Parameter(Mandatory=$false)]
            [int]$LeadingSpaceCount=0
)

    $ls = "".PadRight($LeadingSpaceCount," ")
    $diagConfig = Get-SPDiagnosticConfig
    $ulsLogLocation = $diagConfig.LogLocation + "\MergeLog-Correlation (" + $CorrelationID + ").log"
    Write-Verbose ([string]::Format("$ls- Writing merged logs to file [{0}].", $ulsLogLocation))
    if($Overwrite)
    {
        Merge-SPLogFile -Path $ulsLogLocation -Correlation $CorrelationID -Overwrite
    }
    else
    {
        Merge-SPLogFile -Path $ulsLogLocation -Correlation $CorrelationID
    }
}

Other References

• TechNet – View diagnostic logs in SharePoint 2013
• MSDN – Logging For SharePoint Developers
• ULS Viewer Download

Conclusion

With a little knowledge and tools, you can become efficient at debugging issues in SharePoint.  If you would like a copy of my diagnostic script, please contact me; I will be happy to send it to you.

Happy SharePointing!