Ведение журнала на стороне клиента с помощью клиентской библиотеки для .NET

  • Статья

С помощью клиентской библиотеки службы хранилища Azure для .NET (версии 2.1 и более поздних версий) можно записывать запросы службы хранилища Azure из клиентского приложения .NET с помощью стандартной инфраструктуры диагностика .NET. Таким образом, можно просмотреть сведения о запросах, отправляемых клиентом в службы хранилища Azure, и получаемых ответах.

Клиентская библиотека службы хранилища Azure позволяет контролировать, какие запросы к хранилищу можно регистрировать, а инфраструктура диагностика .NET предоставляет полный контроль над данными журнала, например, местом их отправки. Например, можно отправить данные журнала в файл или в приложение для обработки. В сочетании с Аналитика Службы хранилища Azure и мониторингом сети можно использовать ведение журнала клиентской библиотеки, чтобы создать подробную картину взаимодействия приложения со службами хранилища Azure. Дополнительные сведения см. в статье Мониторинг, диагностика и устранение неполадок службы хранилища Azure.

Включение ведения журнала клиентской библиотеки

В следующем примере показана конфигурация system.diagnostics, необходимая для сбора и хранения сообщений журнала хранилища в текстовом файле. Раздел конфигурации можно добавить в файлы app.config или web.config.

Примечание

Если вы используете версию старше 10.0.0, используйте имя Microsoft.WindowsAzure.Storage вместо Microsoft.Azure.Storage.

<system.diagnostics>  
     <!--In a dev/test environment you can set autoflush to true in order to autoflush to the log file. -->  
  <trace autoflush="false">  
    <listeners>  
      ...
      <add name="storageListener" />  
    </listeners>  
  </trace>  
  <sources>  
    <source name="Microsoft.Azure.Storage">  
      <listeners>  
        <add name="storageListener"/>  
      </listeners>  
    </source>  
  </sources>  
  <switches>  
    <add name="Microsoft.Azure.Storage" value="Verbose" />  
  </switches>  
  <sharedListeners>  
    <add name="storageListener"  
      type="System.Diagnostics.TextWriterTraceListener"  
      initializeData="C:\logs\WebRole.log"
      traceOutputOptions="DateTime" />  
  </sharedListeners>  
</system.diagnostics>

Примечание

платформа .NET Framework пользователей версий 4.6.1-4.7.1 (включительно) могут возникать проблемы с ведением журнала при использовании артефактов .NET Standard 2.0 библиотек службы хранилища Azure, которые могут автоматически выбираться диспетчером пакетов NuGet Visual Studio. Библиотеки также публикуются как платформа .NET Framework артефактов версии 4.5.2, в которых не возникают эти проблемы. Дополнительные сведения см. в статье о поддержке версий .NET Standard.

В этом примере настраивается клиентская библиотека для записи сообщений журнала в физический файл C:\logs\WebRole.log. Можно также использовать другие прослушиватели трассировки, например EventLogTraceListener , для записи в журнал событий Windows или EventProviderTraceListener для записи данных трассировки в подсистему ТРАССИРОВКИ.

Важно!

Полный путь к папке для файла журнала должен существовать в локальной файловой системе. В этом примере это означает, что необходимо сначала создать папку C:\logs , прежде чем записывать журналы в файл в этой папке.

Кроме того, можно задать для параметра autoflush значение true, чтобы записывать записи журнала в файл немедленно, а не буферизаписывать их. Этот параметр может быть полезен в среде разработки и тестирования с небольшим объемом сообщений трассировки, но в рабочей среде может потребоваться задать для автозаполнения значение false. Параметры конфигурации используются, чтобы включить трассировку клиента (и указать уровень, например Подробный, для всех сообщений) для всех операций хранения в клиенте.

Идентификатор Уровень журнала События
0 Выключено Сведения в журнал не заносятся.
1 Ошибка Если исключение не может быть обработано внутренне и возникает у пользователя, оно регистрируется как ошибка.
2 Предупреждение Если исключение перехватываются и обрабатываются внутренне, оно регистрируется как предупреждение. Основным вариантом использования для этого уровня журнала является сценарий повтора, в котором пользователю не возвращается исключение для повтора. Такое поведение также может происходить в таких операциях, как CreateIfNotExists, где ошибка 404 обрабатывается автоматически.
3 Informational Регистрируются следующие сведения:

• Сразу после того, как пользователь вызывает метод для запуска операции, регистрируются сведения о запросе, такие как URI и идентификатор запроса клиента.

• Важные вехи, такие как начало и конец отправки запроса, начало и конец отправки данных, начало и конец получения ответа, начало и конец загрузки данных, регистрируются для обозначения меток времени.

• Сразу после получения заголовков регистрируются сведения об ответе, такие как идентификатор запроса и код состояния HTTP.

•Если операция завершается сбоем и клиент хранилища решает повторить попытку, причина этого решения регистрируется вместе со сведениями о том, когда будет выполнена следующая повторная попытка.

•Все тайм-ауты на стороне клиента регистрируются, когда клиент хранилища решает прервать ожидающий запрос.
4 Подробный Регистрируются следующие сведения:

•Преобразование строки в подпись для каждого запроса.

•Любые дополнительные сведения, относящиеся к операциям (вплоть до каждой операции для определения и использования).

По умолчанию клиентская библиотека регистрирует сведения обо всех операциях хранения на уровне детализации, указанном в файле конфигурации. Вы также можете ограничить ведение журнала определенными областями клиентского приложения, чтобы уменьшить объем регистрированных данных и помочь вам найти необходимые сведения. Чтобы ограничить объем данных, записываемых в журналы, необходимо добавить код в клиентское приложение. Как правило, после включения трассировки на стороне клиента в файле конфигурации ее затем глобально отключают в коде с помощью класса OperationContext . Например, это можно сделать в ASP.NET приложении MVC в методе Application_Start перед выполнением каких-либо операций с хранилищем:

protected void Application_Start()  
{  
    ...  
  
    // Disable Default Logging for Windows Azure Storage  
    OperationContext.DefaultLogLevel = LogLevel.Off;  
  
    // Verify that all of the tables, queues, and blob containers used in this application  
    // exist, and create any that don't already exist.  
    CreateTablesQueuesBlobContainers();  
}

Затем можно включить трассировку для конкретных операций, которые вас интересуют, создав пользовательский объект OperationContext , определяющий уровень ведения журнала. Затем передайте объект OperationContext в качестве параметра в метод Execute , используемый для вызова операции хранения, как показано в следующем примере:

[HttpPost]  
[ValidateAntiForgeryToken]  
public ActionResult Create(Subscriber subscriber)  
{  
    if (ModelState.IsValid)  
    {  
       ...  
        var insertOperation = TableOperation.Insert(subscriber);  
        OperationContext verboseLoggingContext = new OperationContext() { LogLevel = LogLevel.Verbose };  
        mailingListTable.Execute(insertOperation, null, verboseLoggingContext);  
        return RedirectToAction("Index");  
    }  
  
    ...  
    return View(subscriber);  
}

Схема журнала клиентской части и пример

В следующем примере показано извлечение из журнала на стороне клиента, созданного клиентской библиотекой для операции с идентификатором запроса клиента, включающем c3aa328b. Идентификатор запроса клиента — это идентификатор корреляции, который позволяет коррелировать сообщения, зарегистрированные на стороне клиента, с сетевыми трассировками и журналами хранилища. Дополнительные сведения о корреляции см. в статье Мониторинг, диагностика и устранение неполадок службы хранилища Azure. Фрагмент кода содержит комментарии (выделенный наклонный шрифт), связанные с некоторыми ключевыми сведениями, которые можно получить из файлов журналов.

Чтобы проиллюстрировать эту функцию, используя первую строку следующего файла журнала, используются следующие поля:

Поле журнала Значение
Источник Microsoft.Azure.Storage
Детализации Сведения
Степень подробности 3
Идентификатор запроса клиента c3aa328b...
Текст операции Начинается выполнение операции с расположением «Основное» в режиме расположения PrimaryOnly.

Microsoft.Azure.Storage Information: 3 : c3aa328b...: Starting operation with location Primary per location mode PrimaryOnly.
В приведенном выше сообщении трассировки показано, что для режима расположения задан только основной режим, а это означает, что неудачный запрос не будет отправлен в дополнительное расположение.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Starting synchronous request to https://storageaccountname.table.core.windows.net/mailinglist.
Предыдущее сообщение трассировки показывает, что запрос является синхронным.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Setting payload format for the request to 'Json'.
Предыдущее сообщение трассировки показывает, что ответ должен быть возвращен в формате JSON.
Microsoft.Azure.Storage Verbose: 4 : c3aa328b...: StringToSign = GET...Fri, 23 May 2014 06:19:48 GMT./storageaccountname/mailinglist.
Предыдущее сообщение трассировки содержит сведения StringToSign, которые полезны для отладки сбоев проверки подлинности. Подробные сообщения также содержат полные сведения о запросе, включая тип операции и параметры запроса.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Waiting for response.
Предыдущее сообщение трассировки показывает, что запрос отправлен и клиент ожидает ответа.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Response received. Status code = 200, Request ID = 417db530-853d-48a7-a23c-0c8d5f728178, Content-MD5 = , ETag =
Предыдущее сообщение трассировки показывает, что ответ получен и его код состояния HTTP.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Response headers were processed successfully, proceeding with the rest of the operation.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Processing response body.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Retrieved '8' results with continuation token ''.
В приведенном выше сообщении трассировки показано, что было получено 8 результатов и маркер продолжения не предоставлен. Это означает, что для этого запроса больше нет результатов.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Operation completed successfully.
Предыдущее сообщение трассировки показывает, что операция успешно завершена.

В следующих двух подробных записях журнала (уровень 4) отображаются HEAD и запрос DELETE, а также показаны подробные сведения в поле Текст операции:
Microsoft.Azure.Storage Verbose: 4 : 07b26a5d...: StringToSign = HEAD............x-ms-client-request-id:07b26a5d....x-ms-date:Tue, 03 Jun 2014 10:33:11 GMT.x-ms-version:2014-02-14./storageaccountname/azuremmblobcontainer.restype:container.
Microsoft.Azure.Storage Verbose: 4 : 07b26a5d...: StringToSign = DELETE............x-ms-client-request-id:07b26a5d....x-ms-date:Tue, 03 Jun 2014 10:33:12 GMT.x-ms-version:2014-02-14./storageaccountname/azuremmblobcontainer.restype:container.
В предыдущем сообщении трассировки отображается поле OperationText в подробных сообщениях трассировки, включая подробные сведения, связанные с конкретным запросом. К ним относятся тип операции HTTP (например, HEAD, DELETE, POST), идентификатор запроса клиента, метка времени, версия пакета SDK и дополнительные данные, относящиеся к конкретной операции.