NLog.Azure.Kusto 2.0.1

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 6.0

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 2.0.1

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.

There are few cases to keep in mind for the following authentication modes:

1. Managed Identity Authentication
   • This authentication mode can be of two types System Assigned Managed Identity and User Assigned Managed Identity. In case of User Assigned Managed Identity, it requires the following properties to be set in the nlog target configuration::
     • ManagedIdentityClientId :
       • system : This will enable managed identity authentication for system assigned managed identity.
       • <clientId>: Setting ManagedIdentityClientId to a specific clientId will enable managed identity authentication for user assigned managed identity.
2. AzCliAuth
   • This authentication mode will use the Azure CLI to authenticate. This authentication mode will only work when the application is running on a machine with Azure CLI installed and logged in. Accepted values true or false. Default value is false.

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