NLog.Azure.Kusto 3.1.0

NLog.Azure.Kusto

An Azure Data Explorer(ADX) custom target that writes log events to an Azure Data Explorer (Kusto) cluster.

Package - NLog.Azure.Kusto | Platforms - .NET 8.0 + .NET Standard 2.0 + .NET Framework 4.7.2

You can now use the Kusto NLog connector with free Kusto cluster and Microsoft Fabric cluster URLs by providing the cluster URL in the ConnectionString parameter of the ADXTarget configuration.

!! BREAKING CHANGE !!

IngestionEndpoint will not be supported from verison 2.0.0. It has been replaced with Connection String based authentication. With Connection String based authentication, you can use different modes of authentication, such as User Prompt Authentication, User Token Authentication, and more. To learn more about Kusto connection strings and the authentication modes they support, please visit Kusto connection strings.

Getting started

Install from NuGet:

dotnet add package NLog.Azure.Kusto --version 3.1.0

Configuration

Add the ADX target to your NLog configuration:

<nlog>
 <extensions>
 <add assembly="NLog.Azure.Kusto"/>
 </extensions>
 <targets>
 
 <target name="adxtarget" type="ADXTarget"
 ConnectionString="<ADX connection string>"
 Database="<ADX database name>"
 TableName="<ADX table name>">
 <contextproperty name="HostName" layout="${hostname}" /> 
 </target>
 </targets>
 <rules>
 <logger minlevel="Info" name="*" writeTo="adxtarget"/>
 </rules>
</nlog>

Available Configuration Options

IngestionEndpointUri is longer supported with Version 2.0.0, as it has been replaced by Connection String based authentication. Read more about Kusto connection strings

Mapping

Azure Data Explorer provides data mapping capabilities, allowing the ability to extract data rom the ingested JSONs as part of the ingestion. This allows paying a one-time cost of processing the JSON during ingestion, and reduced cost at query time.

By default, the sink uses the following data mapping:

This mapping can be overridden using the following options:

• MappingNameRef: Use a data mapping configured in ADX.

Authentication

Authentication will be taken according to the kusto connection string passed in the nlog target configuration.

It is also possible to assign AuthenticationType to override the authentication mode.

Running tests

To run the tests locally, you need to have an ADX cluster created.

1. Export environment variables for the following:

   • For Windows:

      $env:CONNECTION_STRING="<connectionString>"
      $env:DATABASE="<databaseName>"
     

   • For Mac/Linux:

      export CONNECTION_STRING="<connectionString>"
      export DATABASE="<databaseName>"
     

2. Run the tests using the following command:

    dotnet test