Compartir a través de

Registro del lado cliente con la biblioteca cliente para .NET

  • Artículo

Con la biblioteca cliente de Azure Storage para .NET (versión 2.1 y posteriores), puede registrar las solicitudes de Azure Storage desde la aplicación cliente de .NET mediante la infraestructura de diagnóstico estándar de .NET. De este modo, puede ver los detalles de las solicitudes que el cliente envía a los servicios de Azure Storage y las respuestas que recibe.

La biblioteca cliente de Azure Storage proporciona control sobre qué solicitudes de almacenamiento puede registrar y la infraestructura de diagnóstico de .NET le proporciona control total sobre los datos de registro, como dónde enviarlos. Por ejemplo, puede optar por enviar los datos de registro a un archivo o a una aplicación para su procesamiento. En combinación con Azure Storage Analytics y la supervisión de red, puede usar el registro de bibliotecas cliente para crear una imagen detallada de cómo interactúa la aplicación con los servicios de Azure Storage. Para más información, consulte Supervisión, diagnóstico y solución de problemas de Azure Storage.

Habilitación del registro de la biblioteca cliente

El siguiente ejemplo muestra la configuración de system.diagnostics necesaria para recopilar los mensajes de registro de almacenamiento y que persistan en un archivo de texto. La sección de configuración se puede agregar a archivos app.config o web.config.

Nota:

Si usa una versión anterior a la 10.0.0, use el nombre Microsoft.WindowsAzure.Storage en lugar de 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>

Nota:

Los usuarios de .NET Framework en las versiones 4.6.1-4.7.1 (inclusive) pueden experimentar problemas de registro al usar los artefactos de .NET Standard 2.0 de las bibliotecas de Azure Storage, que el administrador de paquetes NuGet de Visual Studio puede seleccionar automáticamente. Las bibliotecas también se publican como artefactos de .NET Framework 4.5.2, que no experimentan estos problemas. Para más información, lea sobre la compatibilidad con versiones de .NET Standard.

En este ejemplo se configura la biblioteca cliente para escribir mensajes de registro en el archivo C:\logs\WebRole.logfísico . También puede usar otros agentes de escucha de seguimiento, como EventLogTraceListener , para escribir en el registro de eventos de Windows o eventProviderTraceListener para escribir datos de seguimiento en el subsistema ETW.

Importante

La ruta de acceso completa de la carpeta del archivo de registro debe existir en el sistema de archivos local. En este ejemplo, esto significa que primero debe crear la C:\logs carpeta antes de escribir registros en un archivo de esa carpeta.

Además, puede establecer autoflush en true para escribir las entradas de registro en el archivo inmediatamente en lugar de almacenarlas en búfer. Esta configuración podría ser útil en un entorno de desarrollo y pruebas con bajos volúmenes de mensajes de seguimiento, pero en un entorno de producción es posible que desee establecer la autoflush en false. Use las opciones de configuración para habilitar el seguimiento de cliente (y para especificar el nivel, como Detallado, para todos los mensajes) para todas las operaciones de almacenamiento del cliente.

Identificador Nivel de registro Eventos
0 Desactivado No se registra nada.
1 Error Si una excepción no se puede controlar internamente y se produce al usuario, se registra como un error.
2 Advertencia Si se detecta y controla internamente una excepción, se registra como una advertencia. El caso de uso principal de este nivel de registro es el escenario de reintento, donde no se devuelve una excepción al usuario para reintentar. Este comportamiento también puede producirse en operaciones como CreateIfNotExists, donde el error 404 se controla de forma silenciosa.
3 Informativo Se registra la siguiente información:

•Justo después de que el usuario llame a un método para iniciar una operación, se registran los detalles de la solicitud, como el URI y el identificador de solicitud de cliente.

•Hitos importantes, como el inicio/finalización de la solicitud de envío, el inicio y el final de la carga de datos, el inicio/finalización de la respuesta de recepción, el inicio y el final de los datos de descarga se registran para marcar las marcas de tiempo.

•Justo después de recibir los encabezados, se registran los detalles de respuesta, como el identificador de solicitud y el código de estado HTTP.

•Si se produce un error en una operación y el cliente de almacenamiento decide reintentar, el motivo de esa decisión se registra junto con información sobre cuándo se producirá el siguiente reintento.

•Todos los tiempos de espera del lado cliente se registran cuando un cliente de almacenamiento decide anular una solicitud pendiente.
4 Verbose Se registra la siguiente información:

•Cadena a firmar para cada solicitud.

•Cualquier detalle adicional específico de las operaciones (hasta cada operación para definir y usar).

De forma predeterminada, la biblioteca cliente registra los detalles de todas las operaciones de almacenamiento en el nivel de detalle que especifique en el archivo de configuración. También puede limitar el registro a áreas específicas de la aplicación cliente para reducir la cantidad de datos registrados y para ayudarle a encontrar la información que necesita. Para limitar la cantidad de datos escritos en los registros, debe agregar código a la aplicación cliente. Normalmente, después de habilitar el seguimiento del lado cliente en el archivo de configuración, después de desactivarlo globalmente en el código mediante la clase OperationContext . Por ejemplo, puede hacerlo en una aplicación ASP.NET MVC en el método Application_Start antes de que la aplicación realice cualquier operación de almacenamiento:

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();  
}

Después, puede habilitar el seguimiento para las operaciones específicas que le interesan mediante la creación de un objeto OperationContext personalizado que defina el nivel de registro. A continuación, pase el objeto OperationContext como parámetro al método Execute que usa para invocar una operación de almacenamiento, como en el ejemplo siguiente:

[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);  
}

Esquema y ejemplo de registro del lado cliente

El ejemplo siguiente es un extracto del registro del lado cliente generado por la biblioteca cliente para una operación con un identificador de solicitud de cliente que incluye c3aa328b. El identificador de solicitud de cliente es un identificador de correlación que permite que los mensajes registrados en el lado cliente estén correlacionados con los seguimientos de red y los registros de almacenamiento. Para más información sobre la correlación, consulte Supervisión, diagnóstico y solución de problemas de Azure Storage. El extracto incluye comentarios (con sangría y en cursiva) sobre alguna información clave que puede observarse desde dentro de los archivos de registro.

Para ilustrar esta funcionalidad mediante la primera fila del siguiente archivo de registro, los campos son:

Campo de registro Value
Origen Microsoft.Azure.Storage
Detalle Information
Sin nivel de detalle 3
Id. de solicitud de cliente c3aa328b...
Texto de operación Iniciando operación con ubicación Primary según modo de ubicación PrimaryOnly.

Microsoft.Azure.Storage Information: 3 : c3aa328b...: Starting operation with location Primary per location mode PrimaryOnly.
El mensaje de seguimiento anterior muestra que el modo de ubicación solo se establece en principal, lo que significa que una solicitud con error no se enviará a una ubicación secundaria.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Starting synchronous request to https://storageaccountname.table.core.windows.net/mailinglist.
El mensaje de seguimiento anterior muestra que la solicitud es sincrónica.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Setting payload format for the request to 'Json'.
El mensaje de seguimiento anterior muestra que la respuesta debe devolverse con formato JSON.
Microsoft.Azure.Storage Verbose: 4 : c3aa328b...: StringToSign = GET...Fri, 23 May 2014 06:19:48 GMT./storageaccountname/mailinglist.
El mensaje de seguimiento anterior incluye la información stringToSign, que es útil para depurar errores de autenticación. Los mensajes detallados también contienen detalles completos de la solicitud, incluidos el tipo de operación y los parámetros de solicitud.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Waiting for response.
El mensaje de seguimiento anterior muestra que se ha enviado la solicitud y el cliente está esperando una respuesta.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Response received. Status code = 200, Request ID = 417db530-853d-48a7-a23c-0c8d5f728178, Content-MD5 = , ETag =
El mensaje de seguimiento anterior muestra que se ha recibido la respuesta y su código de estado 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 ''.
El mensaje de seguimiento anterior muestra que se recuperaron 8 resultados y no se proporcionó ningún token de continuación, lo que significa que no hay más resultados para esta consulta.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Operation completed successfully.
El mensaje de seguimiento anterior muestra que la operación se completó correctamente.

Las dos entradas de registro detalladas (nivel 4) siguientes muestran una solicitud HEAD y DELETE e ilustran la información detallada en el campo Texto de la operación:
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.
El mensaje de seguimiento anterior muestra el campo OperationText dentro de mensajes de seguimiento detallados, incluida información detallada relacionada con una solicitud específica. Estos detalles incluyen el tipo de operación HTTP (por ejemplo, HEAD, DELETE, POST), el identificador de solicitud de cliente, la marca de tiempo, la versión del SDK y los datos adicionales específicos de la operación.