Azure provides built-in diagnostics to assist with debugging an App Service web app. In this article you'll learn how to enable diagnostic logging and add instrumentation to your application, as well as how to access the information logged by Azure.
This article uses the Azure Portal, Azure PowerShell, and the Azure Command-Line Interface (Azure CLI) to work with diagnostic logs. For information on working with diagnostic logs using Visual Studio, see Troubleshooting Azure in Visual Studio.
[AZURE.INCLUDE app-service-web-to-api-and-mobile]
App Service web apps provide diagnostic functionality for logging information from both the web server and the web application. These are logically separated into web server diagnostics and application diagnostics.
You can enable or disable the following kinds of logs:
- Detailed Error Logging - Detailed error information for HTTP status codes that indicate a failure (status code 400 or greater). This may contain information that can help determine why the server returned the error code.
- Failed Request Tracing - Detailed information on failed requests, including a trace of the IIS components used to process the request and the time taken in each component. This can be useful if you are attempting to increase site performance or isolate what is causing a specific HTTP error to be returned.
- Web Server Logging - Information about HTTP transactions using the W3C extended log file format. This is useful when determining overall site metrics such as the number of requests handled or how many requests are from a specific IP address.
Application diagnostics allows you to capture information produced by a web application. ASP.NET applications can use the System.Diagnostics.Trace class to log information to the application diagnostics log. For example:
System.Diagnostics.Trace.TraceError("If you're seeing this, something bad happened");
At runtime you can retrieve these logs to help with troubleshooting. For more information, see Troubleshooting Azure web apps in Visual Studio.
App Service web apps also log deployment information when you publish content to a web app. This happens automatically and there are no configuration settings for deployment logging. Deployment logging allows you to determine why a deployment failed. For example, if you are using a custom deployment script, you might use deployment logging to determine why the script is failing.
To enable diagnostics in the Azure Portal, go to the blade for your web app and click Settings > Diagnostics logs.
When you enable application diagnostics you also choose the Level. This setting allows you to filter the information captured to informational, warning or error information. Setting this to verbose will log all information produced by the application.
[AZURE.NOTE] Unlike changing the web.config file, enabling Application diagnostics or changing diagnostic log levels does not recycle the app domain that the application runs within.
In the classic portal Web app Configure tab, you can select storage or file system for web server logging. Selecting storage allows you to select a storage account, and then a blob container that the logs will be written to. All other logs for site diagnostics are written to the file system only.
The classic portal Web app Configure tab also has additional settings for application diagnostics:
- File system - stores the application diagnostics information to the web app file system. These files can be accessed by FTP, or downloaded as a Zip archive by using the Azure PowerShell or Azure Command-Line Interface (Azure CLI).
- Table storage - stores the application diagnostics information in the specified Azure Storage Account and table name.
- Blob storage - stores the application diagnostics information in the specified Azure Storage Account and blob container.
- Retention period - by default, logs are not automatically deleted from blob storage. Select set retention and enter the number of days to keep logs if you wish to automatically delete logs.
[AZURE.NOTE] If you regenerate your storage account's access keys, you must reset the respective logging configuration to use the updated keys. To do this:
- In the Configure tab, set the respective logging feature to Off. Save your setting.
- Enable logging to the storage account blob or table again. Save your setting.
Any combination of file system, table storage, or blob storage can be enabled at the same time, and have individual log level configurations. For example, you may wish to log errors and warnings to blob storage as a long-term logging solution, while enabling file system logging with a level of verbose.
While all three storage locations provide the same basic information for logged events, table storage and blob storage log additional information such as the instance ID, thread ID, and a more granular timestamp (tick format) than logging to file system.
[AZURE.NOTE] Information stored in table storage or blob storage can only be accessed using a storage client or an application that can directly work with these storage systems. For example, Visual Studio 2013 contains a Storage Explorer that can be used to explore table or blob storage, and HDInsight can access data stored in blob storage. You can also write an application that accesses Azure Storage by using one of the Azure SDKs.
[AZURE.NOTE] Diagnostics can also be enabled from Azure PowerShell using the Set-AzureWebsite cmdlet. If you have not installed Azure PowerShell, or have not configured it to use your Azure Subscription, see How to Use Azure PowerShell.
Diagnostic information stored to the web app file system can be accessed directly using FTP. It can also be downloaded as a Zip archive using Azure PowerShell or the Azure Command-Line Interface.
The directory structure that the logs are stored in is as follows:
-
Application logs - /LogFiles/Application/. This folder contains one or more text files containing information produced by application logging.
-
Failed Request Traces - /LogFiles/W3SVC#########/. This folder contains an XSL file and one or more XML files. Ensure that you download the XSL file into the same directory as the XML file(s) because the XSL file provides functionality for formatting and filtering the contents of the XML file(s) when viewed in Internet Explorer.
-
Detailed Error Logs - /LogFiles/DetailedErrors/. This folder contains one or more .htm files that provide extensive information for any HTTP errors that have occurred.
-
Web Server Logs - /LogFiles/http/RawLogs. This folder contains one or more text files formatted using the W3C extended log file format.
-
Deployment logs - /LogFiles/Git. This folder contains logs generated by the internal deployment processes used by Azure web apps, as well as logs for Git deployments.
To access diagnostic information using FTP, visit the Dashboard of your web app in the classic portal. In the quick glance section, use the FTP Diagnostic Logs link to access the log files using FTP. The Deployment/FTP User entry lists the user name that should be used to access the FTP site.
[AZURE.NOTE] If the Deployment/FTP User entry is not set, or you have forgotten the password for this user, you can create a new user and password by using the Reset deployment credentials link in the quick glance section of the Dashboard.
To download the log files, start a new instance of Azure PowerShell and use the following command:
Save-AzureWebSiteLog -Name webappname
This will save the logs for the web app specified by the -Name parameter to a file named logs.zip in the current directory.
[AZURE.NOTE] If you have not installed Azure PowerShell, or have not configured it to use your Azure Subscription, see How to Use Azure PowerShell.
To download the log files using the Azure Command Line Interface, open a new command prompt, PowerShell, Bash, or Terminal session and enter the following command:
azure site log download webappname
This will save the logs for the web app named 'webappname' to a file named diagnostics.zip in the current directory.
[AZURE.NOTE] If you have not installed the Azure Command-Line Interface (Azure CLI), or have not configured it to use your Azure Subscription, see How to Use Azure CLI.
Visual Studio Application Insights provides tools for filtering and searching logs, and for correlating the logs with requests and other events.
- Add the Application Insights SDK to your project in Visual Studio.
- In Solution Explorer, right click your project and choose Add Application Insights. You'll be guided through steps that include creating an Application Insights resource. Learn more
- Add the Trace Listener package to your project.
- Right click your project and choose Manage NuGet Packages. Select
Microsoft.ApplicationInsights.TraceListenerLearn more
- Upload your project and run it to generate log data.
- In the Azure Portal, browse to your new Application Insights resource, and open Search. You'll see your log data, along with request, usage and other telemetry. Some telemetry might take a few minutes to arrive: click Refresh. Learn more
Learn more about performance tracking with Application Insights
While developing an application, it is often useful to see logging information in near-real time. This can be accomplished by streaming logging information to your development environment using either Azure PowerShell or the Azure Command-Line Interface.
[AZURE.NOTE] Some types of logging buffer write to the log file, which can result in out of order events in the stream. For example, an application log entry that occurs when a user visits a page may be displayed in the stream before the corresponding HTTP log entry for the page request.
[AZURE.NOTE] Log streaming will also stream information written to any text file stored in the D:\home\LogFiles\ folder.
To stream logging information, start a new of Azure PowerShell and use the following command:
Get-AzureWebSiteLog -Name webappname -Tail
This will connect to the web app specified by the -Name parameter and begin streaming information to the PowerShell window as log events occur on the web app. Any information written to files ending in .txt, .log, or .htm that are stored in the /LogFiles directory (d:/home/logfiles) will be streamed to the local console.
To filter specific events, such as errors, use the -Message parameter. For example:
Get-AzureWebSiteLog -Name webappname -Tail -Message Error
To filter specific log types, such as HTTP, use the -Path parameter. For example:
Get-AzureWebSiteLog -Name webappname -Tail -Path http
To see a list of available paths, use the -ListPath parameter.
[AZURE.NOTE] If you have not installed Azure PowerShell, or have not configured it to use your Azure Subscription, see How to Use Azure PowerShell.
To stream logging information, open a new command prompt, PowerShell, Bash, or Terminal session and enter the following command:
azure site log tail webappname
This will connect to the web app named 'webappname' and begin streaming information to the window as log events occur on the web app. Any information written to files ending in .txt, .log, or .htm that are stored in the /LogFiles directory (d:/home/logfiles) will be streamed to the local console.
To filter specific events, such as errors, use the --Filter parameter. For example:
azure site log tail webappname --filter Error
To filter specific log types, such as HTTP, use the --Path parameter. For example:
azure site log tail webappname --path http
[AZURE.NOTE] If you have not installed the Azure Command-Line Interface, or have not configured it to use your Azure Subscription, see How to Use Azure Command-Line Interface.
## How to: Understand diagnostics logs
Application diagnostics stores information in a specific format for .NET applications, depending on whether you store logs to the file system, table storage, or blob storage. The base set of data stored is the same across all three storage types - the date and time the event occurred, the process ID that produced the event, the event type (information, warning, error,) and the event message.
File system
Each line logged to the file system or received using streaming will be in the following format:
{Date} PID[{process id}] {event type/level} {message}
For example, an error event would appear similar to the following:
2014-01-30T16:36:59 PID[3096] Error Fatal error on the page!
Logging to the file system provides the most basic information of the three available methods, providing only the time, process id, event level, and message.
Table storage
When logging to table storage, additional properties are used to facilitate searching the data stored in the table as well as more granular information on the event. The following properties (columns) are used for each entity (row) stored in the table.
| Property name | Value/format |
|---|---|
| PartitionKey | Date/time of the event in yyyyMMddHH format |
| RowKey | A GUID value that uniquely identifies this entity |
| Timestamp | The date and time that the event occurred |
| EventTickCount | The date and time that the event occurred, in Tick format (greater precision) |
| ApplicationName | The web app name |
| Level | Event level (e.g. error, warning, information) |
| EventId | The event ID of this event Defaults to 0 if none specified |
| InstanceId | Instance of the web app that the even occurred on |
| Pid | Process ID |
| Tid | The thread ID of the thread that produced the event |
| Message | Event detail message |
Blob storage
When logging to blob storage, data is stored in comma-separated values (CSV) format. Similar to table storage, additional fields are logged to provide more granular information about the event. The following properties are used for each row in the CSV:
| Property name | Value/format |
|---|---|
| Date | The date and time that the event occurred |
| Level | Event level (e.g. error, warning, information) |
| ApplicationName | The web app name |
| InstanceId | Instance of the web app that the even occurred on |
| EventTickCount | The date and time that the event occurred, in Tick format (greater precision) |
| EventId | The event ID of this event Defaults to 0 if none specified |
| Pid | Process ID |
| Tid | The thread ID of the thread that produced the event |
| Message | Event detail message |
The data stored in a blob would similar to the following:
date,level,applicationName,instanceId,eventTickCount,eventId,pid,tid,message
2014-01-30T16:36:52,Error,mywebapp,6ee38a,635266966128818593,0,3096,9,An error occurred
[AZURE.NOTE] The first line of the log will contain the column headers as represented in this example.
Failed request traces are stored in XML files named fr######.xml. To make it easier to view the logged information, an XSL stylesheet named freb.xsl is provided in the same directory as the XML files. Opening one of the XML files in Internet Explorer will use the XSL stylesheet to provide a formatted display of the trace information. This will appear similar to the following:
Detailed error logs are HTML documents that provide more detailed information on HTTP errors that have occurred. Since they are simply HTML documents, they can be viewed using a web browser.
The web server logs are formatted using the W3C extended log file format. This information can be read using a text editor or parsed using utilities such as Log Parser.
[AZURE.NOTE] The logs produced by Azure web apps do not support the s-computername, s-ip, or cs-version fields.
- How to Monitor Web Apps
- Troubleshooting Azure web apps in Visual Studio
- Analyze web app Logs in HDInsight
[AZURE.NOTE] If you want to get started with Azure App Service before signing up for an Azure account, go to Try App Service, where you can immediately create a short-lived starter web app in App Service. No credit cards required; no commitments.
- For a guide to the change from Websites to App Service see: Azure App Service and Its Impact on Existing Azure Services
- For a guide to the change of the old portal to the new portal see: Reference for navigating the preview portal