为 Azure 应用服务中的应用启用诊断日志记录Enable diagnostics logging for apps in Azure App Service

概述Overview

Azure 提供内置诊断功能,可帮助调试应用服务应用Azure provides built-in diagnostics to assist with debugging an App Service app. 在本文中,将了解如何启用诊断日志记录并将检测添加到应用程序,以及如何访问由 Azure 记录的信息。In this article, you learn how to enable diagnostic logging and add instrumentation to your application, as well as how to access the information logged by Azure.

本文使用 Azure 门户和 Azure CLI 来处理诊断日志。This article uses the Azure portal and Azure CLI to work with diagnostic logs. 有关通过 Visual Studio 使用诊断日志的信息,请参阅在 Visual Studio 中对 Azure 进行故障排除For information on working with diagnostic logs using Visual Studio, see Troubleshooting Azure in Visual Studio.

Web 服务器诊断和应用程序诊断Web server diagnostics and application diagnostics

应用服务为 Web 服务器和 Web 应用程序中的日志记录信息提供诊断功能。App Service provides diagnostic functionality for logging information from both the web server and the web application. 这些诊断功能按逻辑分为 Web 服务器诊断应用程序诊断These are logically separated into web server diagnostics and application diagnostics.

Web 服务器诊断Web server diagnostics

可以启用或禁用以下种类的日志:You can enable or disable the following kinds of logs:

  • 详细错误日志记录 - 任何会生成 HTTP 状态代码 400(或更大数字)的请求的详细信息。Detailed Error Logging - Detailed information for any request that results in HTTP status code 400 or greater. 其中可能包含有助于确定服务器返回错误代码的原因的信息。It may contain information that can help determine why the server returned the error code. 会为应用的文件系统中的每个错误生成一个 HTML 文件,并可保留最多 50 个错误(文件)。One HTML file is generated for each error in the app's file system, and up to 50 errors (files) are retained. 当 HTML 文件的数目超出 50 时,最旧的 26 个文件会自动删除。When the number of HTML files exceed 50, the oldest 26 files are automatically deleted.
  • 失败请求跟踪 - 有关失败请求的详细信息,包括对用于处理请求的 IIS 组件和每个组件所用的时间的跟踪。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. 如果要提高站点性能或隔离特定的 HTTP 错误,这将非常有用。It's useful if you want to improve site performance or isolate a specific HTTP error. 会在应用的文件系统中为每个错误生成一个文件夹。One folder is generated for each error in the app's file system. 文件保留策略与上述详细错误日志记录的相同。File retention policies are the same as the detailed error logging above.
  • Web 服务器日志记录 - 使用 W3C 扩展日志文件格式的 HTTP 事务信息。Web Server Logging - Information about HTTP transactions using the W3C extended log file format. 这在确定整体站点指标(如处理的请求数量或来自特定 IP 地址的请求数)时非常有用。It's 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

应用程序诊断可以捕获由 Web 应用程序产生的信息。Application diagnostics allows you to capture information produced by a web application. ASP.NET 应用程序可使用 System.Diagnostics.Trace 类将信息记录到应用程序诊断日志。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. 有关详细信息,请参阅在 Visual Studio 中对 Azure 应用服务进行故障排除For more information, see Troubleshooting Azure App Service in Visual Studio.

将内容发布到某个应用时,应用服务还记录部署信息。App Service also logs deployment information when you publish content to an app. 此操作自动执行,不会对部署日志记录进行配置设置。It 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 use a custom deployment script, you might use deployment logging to determine why the script is failing.

如何启用诊断How to enable diagnostics

若要在 Azure 门户中启用诊断,请转到应用的相应页面,并依次单击“设置”>“诊断日志”。To enable diagnostics in the Azure portal, go to the page for your app and click Settings > Diagnostics logs.

日志部分

启用“应用程序诊断”时,还需选择“级别”。When you enable application diagnostics, you also choose the Level. 下表显示了每个级别包含的日志类别:The following table shows the categories of logs each level includes:

级别Level 包含的日志类别Included log categories
已禁用Disabled None
错误Error “错误”、“严重”Error, Critical
警告Warning “警告”、“错误”、“严重”Warning, Error, Critical
信息Information “信息”、“警告”、“错误”、“严重”Info, Warning, Error, Critical
详细Verbose “跟踪”、“调试”、“信息”、“警告”、“错误”、“严重”(所有类别)Trace, Debug, Info, Warning, Error, Critical (all categories)
- -

对于“应用程序日志记录”,可以临时打开文件系统选项以便调试。For Application logging, you can turn on the file system option temporarily for debugging purposes. 此选项将在 12 小时后自动关闭。This option turns off automatically in 12 hours. 还可打开 blob 存储选项,选择某个 blob 容器来写入日志。You can also turn on the blob storage option to select a blob container to write logs to.

Note

目前,只有 .NET 应用程序日志可以写入 blob 存储。Currently only .NET application logs can be written to the blob storage. Java、PHP、Node.js、Python 应用程序日志只能存储在文件系统上(无需修改代码即可将日志写入外部存储)。Java, PHP, Node.js, Python application logs can only be stored on the file system (without code modifications to write logs to external storage).

对于“Web 服务器日志记录”,可选择“存储”或“文件系统”。For Web server logging, you can select storage or file system. 选择“存储”可选择存储帐户,然后将日志写入 Blob 容器。Selecting storage allows you to select a storage account, and then a blob container that the logs are written to.

如果将日志存储在文件系统中,可通过 FTP 访问这些文件,或使用 Azure CLI 将这些文件作为 Zip 存档下载。If you store logs on the file system, the files can be accessed by FTP, or downloaded as a Zip archive by using Azure CLI.

默认情况下,日志不会自动删除(除非是“应用程序日志记录(文件系统)”)。By default, logs are not automatically deleted (with the exception of Application Logging (Filesystem)). 要自动删除日志,请设置“保留期(天)”字段。To automatically delete logs, set the Retention Period (Days) field.

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:

  1. 在“配置”选项卡上,将相应的日志记录功能设置为“关闭”。In the Configure tab, set the respective logging feature to Off. 保存设置。Save your setting.
  2. 再次启用将日志记录到存储帐户 Blob。Enable logging to the storage account blob again. 保存设置。Save your setting.

可同时启用文件系统或 Blob 存储的任意组合,并采用单独的日志级别配置。Any combination of file system or blob storage can be enabled at the same time, and have individual log level configurations. 例如,你可能希望将错误和警告记录到 Blob 存储中作为长期的日志记录解决方案,同时将文件系统日志记录级别设置为“详细”。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.

尽管这两个存储位置都可为记录事件提供相同的基本信息,但与记录到文件系统相比,Blob 存储还会记录其他信息,例如实例 ID、线程 ID 以及更详细的时间戳(刻度格式)。While both storage locations provide the same basic information for logged events, blob storage logs additional information such as the instance ID, thread ID, and a more granular timestamp (tick format) than logging to file system.

Note

只能使用存储客户端访问或由直接使用这些存储系统的应用程序访问存储在 Blob 存储中的信息。Information stored in blob storage can only be accessed using a storage client or an application that can directly work with these storage systems. 例如,Visual Studio 2013 包含的存储资源管理器可用于浏览 Blob 存储,而 HDInsight 可以访问存储在 Blob 存储中的数据。For example, Visual Studio 2013 contains a Storage Explorer that can be used to explore blob storage, and HDInsight can access data stored in blob storage. 还可编写通过使用 Azure SDK 之一访问 Azure 存储的应用程序。You can also write an application that accesses Azure Storage by using one of the Azure SDKs.

如何:下载日志How to: Download logs

可使用 FTP 直接访问存储到应用文件系统的诊断信息。Diagnostic information stored to the app file system can be accessed directly using FTP. 还可以使用 Azure CLI 将其作为 Zip 存档下载。It can also be downloaded as a Zip archive using Azure CLI.

存储日志采用的目录结构如下:The directory structure that the logs are stored in is as follows:

  • 应用程序日志 - /LogFiles/Application/。Application logs - /LogFiles/Application/. 此文件夹包含一个或多个包含应用程序日志记录生成的信息的文本文件。This folder contains one or more text files containing information produced by application logging.
  • 失败请求跟踪 - /LogFiles/W3SVC#########/。Failed Request Traces - /LogFiles/W3SVC#########/. 此文件夹包含一个 XSL 文件和一个或多个 XML 文件。This folder contains an XSL file and one or more XML files. 请确保将 XSL 文件下载到 XML 文件所在的目录,因为 XSL 文件可提供格式化和筛选这些文件的内容的功能(在 Internet Explorer 中查看 XML 文件时)。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.
  • 详细错误日志 - /LogFiles/DetailedErrors/。Detailed Error Logs - /LogFiles/DetailedErrors/. 此文件夹包含一个或多个 .htm 文件,这些文件可提供大量有关所有已出现 HTTP 错误的信息。This folder contains one or more .htm files that provide extensive information for any HTTP errors that have occurred.
  • Web 服务器日志 - /LogFiles/http/RawLogs。Web Server Logs - /LogFiles/http/RawLogs. 此文件夹包含使用 W3C 扩展日志文件格式进行格式化的一个或多个文本文件。This folder contains one or more text files formatted using the W3C extended log file format.
  • 部署日志 - /LogFiles/Git。Deployment logs - /LogFiles/Git. 此文件夹包含由 Azure 应用服务所用的内部部署过程生成的日志和 Git 部署的日志。This folder contains logs generated by the internal deployment processes used by Azure App Service, as well as logs for Git deployments. 此外,还可在 D:\home\site\deployments 下找到部署日志。You can also find deployment logs under D:\home\site\deployments.

FTPFTP

要开启到应用的 FTP 服务器的 FTP 连接,请参阅使用 FTP/S 将应用部署到 Azure App ServiceTo open an FTP connection to your app's FTP server, see Deploy your app to Azure App Service using FTP/S.

一旦连接到应用的 FTP/S 服务器,请打开 LogFiles 文件夹,所有日志文件都存储于此。Once connected to your app's FTP/S server, open the LogFiles folder, where the log files are stored.

使用 Azure CLI 下载Download with Azure CLI

若要使用 Azure 命令行接口下载日志文件,请打开新的命令提示符、PowerShell、Bash 或终端会话,并输入以下命令: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:

az webapp log download --resource-group resourcegroupname --name appname

此命令将名为“appname”的应用的日志保存到当前目录中名为 webapp_logs.zip 的文件。This command saves the logs for the app named 'appname' to a file named webapp_logs.zip in the current directory.

Note

如果尚未安装 Azure CLI,或尚未将其配置为使用你的 Azure 订阅,请参阅如何使用 Azure CLIIf you haven't installed Azure CLI, or haven't configured it to use your Azure Subscription, see How to Use Azure CLI.

如何:流式传输日志How to: Stream logs

开发应用程序时,以近乎实时的方式查看日志记录信息通常很有用。While developing an application, it is often useful to see logging information in near-real time. 可以使用 Azure CLI 将日志记录信息流式传输到开发环境。You can stream logging information to your development environment using Azure CLI.

Note

某些类型的日志记录缓冲区会对日志文件执行写入操作,这可能会导致流中的事件变成混乱。Some types of logging buffer write to the log file, which can result in out of order events in the stream. 例如,用户访问页面时出现的应用程序日志项可能显示在该页面请求所对应的 HTTP 日志项的前面。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.

Note

日志流式传输还将对写入存储在 D:\home\LogFiles\ 文件夹中的任何文本文件的信息进行流式传输。Log streaming also streams information written to any text file stored in the D:\home\LogFiles\ folder.

使用 Azure CLI 流式传输Streaming with Azure CLI

若要流式传输日志记录信息,请打开新的命令行提示、PowerShell、Bash 或终端会话并输入以下命令:To stream logging information, open a new command prompt, PowerShell, Bash, or Terminal session and enter the following command:

az webapp log tail --name appname --resource-group myResourceGroup

此命令连接到名为“appname”的应用,并在该应用上出现日志事件时开始将信息流式传输到窗口。This command connects to the app named 'appname' and begin streaming information to the window as log events occur on the app. 写入以 .txt、.log 或 .htm 结尾并存储在 /LogFiles 目录 (d:/home/logfiles) 中文件的所有信息将流式传输至本地控制台。Any information written to files ending in .txt, .log, or .htm that are stored in the /LogFiles directory (d:/home/logfiles) is streamed to the local console.

若要筛选特定事件(如错误),请使用 --Filter 参数。To filter specific events, such as errors, use the --Filter parameter. 例如:For example:

az webapp log tail --name appname --resource-group myResourceGroup --filter Error

若要筛选特定日志类型(如 HTTP),请使用 --Path 参数。To filter specific log types, such as HTTP, use the --Path parameter. 例如:For example:

az webapp log tail --name appname --resource-group myResourceGroup --path http

Note

如果尚未安装 Azure CLI,或尚未将其配置为使用你的 Azure 订阅,请参阅如何使用 Azure CLIIf you haven't installed Azure CLI, or haven't configured it to use your Azure Subscription, see How to Use Azure CLI.

如何:了解诊断日志How to: Understand diagnostics logs

应用程序诊断日志Application diagnostics logs

应用程序诊断将信息以特定格式存储在 .NET 应用程序中,具体取决于是将日志存储到文件系统还是 Blob 存储。Application diagnostics stores information in a specific format for .NET applications, depending on whether you store logs to the file system or blob storage.

这两种存储类型存储的基本数据信息相同 — 事件发生的日期和时间,生成事件的进程 ID,事件类型(信息、警告、错误)以及事件消息。The base set of data stored is the same across both 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. 如果需要立即访问日志以排查某个问题,则使用文件系统作为日志存储会很有帮助,因为日志文件几乎是即时更新的。Using the file system for log storage is useful when you need immediate access to troubleshoot an issue because the log files are updated near instantaneously. Blob 存储用于存档目的,因为这些文件将会缓存,并按计划刷新到存储容器。Blob storage is used for archival purposes because the files are cached and then flushed to the storage container on a schedule.

文件系统File system

记录到文件系统或使用流式传输收到的每行都会采用以下格式:Each line logged to the file system or received using streaming is in the following format:

{Date}  PID[{process ID}] {event type/level} {message}

例如,错误事件可能类似如下所示:For example, an error event would appear similar to the following sample:

2014-01-30T16:36:59  PID[3096] Error       Fatal error on the page!

记录到文件系统可提供三种可用方法的最基本信息,仅提供时间、进程 ID、事件级别以及消息。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.

Blob 存储Blob storage

如果记录到 Blob 存储,数据以逗号分隔值 (CSV) 格式存储。When logging to blob storage, data is stored in comma-separated values (CSV) format. 将记录其他字段以提供有关事件的更详尽信息。Additional fields are logged to provide more granular information about the event. 以下属性适用于每一行(CSV 格式):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 (for example, error, warning, information)
ApplicationNameApplicationName 应用名称The app name
InstanceIdInstanceId 发生事件的应用实例Instance of the app that the event occurred on
EventTickCountEventTickCount 事件发生的日期和时间,刻度格式(精度更高)The date and time that the event occurred, in Tick format (greater precision)
EventIdEventId 此事件的事件 IDThe event ID of this event

如果未指定,默认为 0Defaults to 0 if none specified

PidPid 进程 IDProcess ID
TidTid 生成事件的线程的线程 IDThe thread ID of the thread that produced the event
消息Message 事件详细消息Event detail message

存储在 blob 中的数据如下方示例所示:The data stored in a blob would look similar to the following example:

date,level,applicationName,instanceId,eventTickCount,eventId,pid,tid,message
2014-01-30T16:36:52,Error,mywebapp,6ee38a,635266966128818593,0,3096,9,An error occurred

Note

对于 ASP.NET Core,可以使用 Microsoft.Extensions.Logging.AzureAppServices 提供程序实现日志记录。此提供程序会将其他日志文件保存到 Blob 容器。For ASP.NET Core, logging is accomplished using the Microsoft.Extensions.Logging.AzureAppServices provider This provider deposits additional log files into the blob container. 有关详细信息,请参阅 Azure 中的 ASP.NET Core 日志记录For more information, see ASP.NET Core logging in Azure.

失败请求跟踪Failed request traces

失败请求跟踪存储在名为 fr######.xml 的 XML 文件中。Failed request traces are stored in XML files named fr######.xml. 为了便于查看记录信息,在 XML 文件所在目录中提供了一个名为 freb.xsl 的 XSL 样式表。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. 如果在 Internet Explorer 中打开其中一个 XML 文件,Internet Explorer 会使用 XSL 样式表提供易于阅读的跟踪信息,如下方示例所示:If you open one of the XML files in Internet Explorer, Internet Explorer uses the XSL stylesheet to provide a formatted display of the trace information, similar to the following example:

在浏览器中查看失败请求

详细的错误日志Detailed error logs

详细的错误日志是 HTML 文档,可提供有关发生的 HTTP 错误的详细信息。Detailed error logs are HTML documents that provide more detailed information on HTTP errors that have occurred. 由于它们只是 HTML 文档,所以可以使用 Web 浏览器查看。Since they are simply HTML documents, they can be viewed using a web browser.

Web 服务器日志Web server logs

可使用 W3C 扩展日志文件格式格式化 Web 服务器日志。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.

Note

Azure 应用服务生成的日志不支持 s-computernames-ipcs-version 字段。The logs produced by Azure App Service do not support the s-computername, s-ip, or cs-version fields.

后续步骤Next steps