Compartir vía

Obtención de datos de Serilog

  • Artículo

Serilog es un conocido marco de registro para aplicaciones .NET. Serilog permite a los desarrolladores controlar qué instrucciones de registro se generan con granularidad arbitraria en función del nombre del registrador, el nivel del registrador y el patrón de mensaje. El receptor de Serilog, también conocido como appender, transmite los datos de registro a su tabla, donde puede analizar y visualizar los registros en tiempo real.

En este artículo se muestra cómo ingerir datos con Serilog.

Para obtener una lista completa de los conectores de datos, consulte Introducción a los conectores de datos.

Requisitos previos

Creación de una entidad de servicio de Microsoft Entra

La autenticación de aplicaciones de Microsoft Entra se usa para las aplicaciones que necesitan acceder a su tabla de bases de datos KQL sin que haya un usuario presente. Para ingerir datos mediante el conector de Serilog, es preciso crear una entidad de servicio de Microsoft Entra y registrarla, y, después, autorizar esta entidad de seguridad como la identidad que usa el conector para ingerir datos en la base de datos KQL.

La entidad de servicio de Microsoft Entra se puede crear desde Azure Portal o mediante programación, como en el ejemplo siguiente.

Más adelante concederemos permisos para que esta entidad de servicio acceda a los recursos de Kusto.

  1. Inicie sesión en su suscripción de Azure a través de la CLI de Azure. A continuación, realice la autenticación en el explorador.

    az login

  2. Elija la suscripción para hospedar la entidad de servicio. Este paso es necesario si tiene varias suscripciones.

    az account set --subscription YOUR_SUBSCRIPTION_GUID

  3. Cree la entidad de servicio. En este ejemplo, la entidad de servicio se llama my-service-principal.

    az ad sp create-for-rbac -n "my-service-principal" --role Contributor --scopes /subscriptions/{SubID}

  4. En los datos JSON devueltos, copie los valores appId, password y tenant para usarlos posteriormente.

    {
  "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "displayName": "my-service-principal",
  "name": "my-service-principal",
  "password": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "tenant": "00001111-aaaa-2222-bbbb-3333cccc4444"
}

Ha creado una aplicación de Microsoft Entra y una entidad de servicio.

Creación de una tabla de destino y una asignación de ingesta

Cree una tabla de destino para los datos entrantes y una asignación de ingesta para asignar las columnas de datos ingeridos a las columnas de la tabla de destino. En los pasos siguientes, el esquema de tabla y la asignación corresponden a los datos enviados desde la aplicación de ejemplo.

  1. Ejecute el siguiente comando de creación de tablas en el editor de consultas y reemplace el marcador de posición TableName por el nombre de la tabla de destino:

    .create table <TableName> (Timestamp: datetime, Level: string, Message: string, Exception: string, Properties: dynamic, Position: dynamic, Elapsed: int)

  2. Ejecute el siguiente comando de asignación de ingesta .create, y reemplace los marcadores de posición TableName por el nombre de la tabla de destino y TableNameMapping por el nombre de la asignación de ingesta:

    .create table <TableName> ingestion csv mapping '<TableNameMapping>' '[{"Name":"Timestamp","DataType":"","Ordinal":"0","ConstValue":null},{"Name":"Level","DataType":"","Ordinal":"1","ConstValue":null},{"Name":"Message","DataType":"","Ordinal":"2","ConstValue":null},{"Name":"Exception","DataType":"","Ordinal":"3","ConstValue":null},{"Name":"Properties","DataType":"","Ordinal":"4","ConstValue":null},{"Name":"Position","DataType":"","Ordinal":"5","ConstValue":null},{"Name":"Elapsed","DataType":"","Ordinal":"6","ConstValue":null}]'

  3. Conceda a la entidad de servicio de Crear una entidad de servicio de Microsoft Entra permisos del rol de agente de ingesta de base de datos para trabajar con la base de datos. Para más información, consulte Ejemplos. Reemplace el marcador de posición DatabaseName por el nombre de la base de datos de destino y ApplicationID por el valor AppId que guardó al crear una entidad de servicio de Microsoft Entra.

    .add database <DatabaseName> ingestors ('aadapp=<ApplicationID>') 'App Registration'

Uso de Serilog en una aplicación de ASP.NET Core

En esta sección se explica cómo integrar Serilog en una aplicación de ASP.NET Core para registrar los datos y enviarlos a la tabla KQL.

Instalar el paquete

Agregue el paquete de la biblioteca NuGet Serilog.Sinks.AzureDataExplorer. Use el comando Install-Package que especifica el nombre del paquete NuGet.

Install-Package Serilog.Sinks.AzureDataExplorer

Incorporación del receptor de Serilog a la aplicación

Uso los pasos siguientes para:

  • Agregue el receptor de Serilog a la aplicación.
  • Configure las variables que usa el receptor.
  • Compile y ejecute la aplicación.

  1. Agregue el siguiente código a su app:

    using Serilog.Sinks.AzureDataExplorer;

  2. Configure el receptor de Serilog y reemplace los marcadores de posición mediante la información de la tabla siguiente:

    var log = new LoggerConfiguration()
.WriteTo.AzureDataExplorerSink(new AzureDataExplorerSinkOptions
{
    IngestionEndpointUri = "<TargetURI>",
    DatabaseName = "<MyDatabase>",
    TableName = "<MyTable>",
    BufferBaseFileName = "<BufferBaseFileName>"
})
.CreateLogger();
    Variable Descripción
    IngestionEndPointUri El identificador URI de ingesta.
    DatabaseName Nombre de la base de datos de destino en el que se distinguen mayúsculas de minúsculas.
    TableName Nombre de una tabla de destino existente en el que se distinguen mayúsculas de minúsculas. Por ejemplo, SerilogTest es el nombre de la tabla creada en Creación una tabla de destino y una asignación de ingesta.
    AppId El id. de cliente de la aplicación necesario para la autenticación. Ha guardado este valor en Creación de una entidad de servicio de Microsoft Entra.
    AppKey La clave de aplicación necesaria para la autenticación. Guardó este valor como password en Creación de una entidad de servicio de Microsoft Entra.
    Inquilino El id. del inquilino en el que se registra la aplicación. Ha guardado este valor en Creación de una entidad de servicio de Microsoft Entra.
    BufferBaseFileName Nombre de archivo base opcional para el archivo de búfer. Establezca este valor si necesita que los registros duren aunque se produzcan errores de conexión que provoquen pérdidas en el clúster. Por ejemplo, C:/Temp/Serilog.

    Para ver más opciones, consulte Opciones de receptor.

  3. Envíe datos a la base de datos mediante el receptor de Serilog. Por ejemplo:

    log.Verbose("Processed {@Position} in {Elapsed:000} ms.", position, elapsedMs);
log.Information("Processed {@Position} in {Elapsed:000} ms.", position, elapsedMs);
log.Warning("Processed {@Position} in {Elapsed:000} ms.", position, elapsedMs);
log.Error(new Exception(), "Processed {@Position} in {Elapsed:000} ms.", position, elapsedMs);
log.Debug("Processed {@Position} in {Elapsed:000} ms. ", position, elapsedMs);

  4. Compile y ejecute la aplicación. Por ejemplo, si usa Visual Studio, presione F5.

  5. Compruebe que los datos están en la tabla. Ejecute la siguiente consulta, pero reemplace el marcador de posición por el nombre de la tabla que se creó en un paso anterior:

    <TableName>
| take 10

Ejecutar la aplicación de ejemplo

Si no tiene sus propios datos para realizar la prueba, puede usar la aplicación generadora de registros de ejemplo con datos de ejemplo para probar la configuración y el uso del receptor de Serilog.

  1. Clone el repositorio de Git del receptor de Serilog mediante el siguiente comando de Git:

    git clone https://github.com/Azure/serilog-sinks-azuredataexplorer

  2. Establezca las siguientes variables de entorno para configurar el receptor de Serilog:

    Variable Descripción
    IngestionEndPointUri El identificador URI de ingesta.
    DatabaseName Nombre de la base de datos de destino en el que se distinguen mayúsculas de minúsculas.
    TableName Nombre de una tabla de destino existente en el que se distinguen mayúsculas de minúsculas. Por ejemplo, SerilogTest es el nombre de la tabla creada en Creación una tabla de destino y una asignación de ingesta.
    AppId Identificador de cliente de aplicación necesario para la autenticación. Ha guardado este valor en Creación de una entidad de servicio de Microsoft Entra.
    AppKey Clave de aplicación necesaria para la autenticación. Ha guardado este valor en Creación de una entidad de servicio de Microsoft Entra.
    Inquilino El id. del inquilino en el que se registra la aplicación. Ha guardado este valor en Creación de una entidad de servicio de Microsoft Entra.
    BufferBaseFileName Nombre de archivo base del archivo de búfer. Establezca este valor si necesita que los registros duren aunque se produzcan errores de conexión que provoquen pérdidas en el clúster. Por ejemplo: C:/Temp/Serilog

    Puede establecer las variables de entorno manualmente o mediante los siguientes comandos:

    $env:ingestionURI="<ingestionURI>"
$env:appId="<appId>"
$env:appKey="<appKey>"
$env:tenant="<tenant>"
$env:databaseName="<databaseName>"
$env:tableName="<tableName>"

  3. En el terminal, vaya a la carpeta raíz del repositorio clonado y ejecute el siguiente comando de .NET para compilar la aplicación:

    dotnet build src

  4. En el terminal, vaya a la carpeta de ejemplos y ejecute el siguiente comando de .NET para ejecutar la aplicación:

    dotnet build run

  1. Seleccione la base de datos KQL de destino y ejecute la siguiente consulta para explorar los datos ingeridos, reemplazando el marcador de posición TableName por el nombre de la tabla de destino:

    <TableName>
| take 10

    El resultado debería ser similar al siguiente:

    Marca de tiempo Nivel Mensaje Exception Propiedades Posición Transcurrido
    2023-03-12 1248:474590 Información Procesado { Latitude: 25, Longitude:30} {"Position": { "Latitude": 25, "Longitude":30} { "Latitude": 25, "Longitude":30} 34
    2023-03-12 1248474770 Advertencia Procesado { Latitude: 25, Longitude:30} {"Position": { "Latitude": 25, "Longitude":30} { "Latitude": 25, "Longitude":30} 34
    2023-03-12 1248475590 Error Zohar Procesado { Latitude: 25, Longitude:30} {"Position": { "Latitude": 25, "Longitude":30} { "Latitude": 25, "Longitude":30} 34
    2023-03-12 1248474790 Información Procesado { Latitude: 25, Longitude:30} {"Position": { "Latitude": 25, "Longitude":30} { "Latitude": 25, "Longitude":30} 34
    2023-03-12 124847.5610 Advertencia Procesado { Latitude: 25, Longitude:30} {"Position": { "Latitude": 25, "Longitude":30} { "Latitude": 25, "Longitude":30} 34
    2023-03-12 124847.5620 Error Zohar Procesado { Latitude: 25, Longitude:30} {"Position": { "Latitude": 25, "Longitude":30} { "Latitude": 25, "Longitude":30} 34
    2023-03-12 124847.5630 Información Procesado { Latitude: 25, Longitude:30} {"Position": { "Latitude": 25, "Longitude":30} { "Latitude": 25, "Longitude":30} 34
    2023-03-12 124847.5660 Error Procesado { Latitude: 25, Longitude:30} {"Position": { "Latitude": 25, "Longitude":30} { "Latitude": 25, "Longitude":30} 34
    2023-03-12 124847.5670 Información Zohar Procesado { Latitude: 25, Longitude:30} {"Position": { "Latitude": 25, "Longitude":30} { "Latitude": 25, "Longitude":30} 34
    2023-03-12 124847.5680 Advertencia Procesado { Latitude: 25, Longitude:30} {"Position": { "Latitude": 25, "Longitude":30} { "Latitude": 25, "Longitude":30} 34

Contenido relacionado