NLog.Azure.Kusto 1.0.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 6.0

Getting started

Install from NuGet:

Install-Package NLog.Azure.Kusto

Configuration

Add the ADX target to your NLog configuration:

<nlog>
  <extensions>
    <add assembly="NLog.Azure.Kusto"/>
  </extensions>
  <targets>
   
    <target name="adxtarget" xsi:type="ADXTarget"
      IngestionEndpointUri="<ADX connection string>"
      Database="<ADX database name>"
      TableName="<ADX table name>"
      ApplicationClientId="<AAD App clientId>"
      ApplicationKey="<AAD App key>"
     Authority="<AAD tenant id>"
    />
  </targets>
  <rules>
    <logger minlevel="Info" name="*" writeTo="adxtarget"/>
  </rules>
</nlog>

Available Configuration Options

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.
• ColumnsMapping: Use an ingestion-time data mapping.

Authentication

Authentication can be used by setting the AuthenticationMode property in the nlog target configuration.

AuthenticationMode="<authentication_method_name>"

The authentication_method_name can be replaced with the following supported authentication methods:

1. AadApplicationKey
   • This is the default authentication mode. This requires the following properties to be set in the nlog target configuration.
     • ApplicationClientId
     • ApplicationKey
     • Authority
2. AadUserManagedIdentity
   • 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

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:INGEST_ENDPOINT="<ingestionURI>"
       $env:APP_ID="<appId>"
       $env:APP_KEY="<appKey>"
       $env:AZURE_TENANT_ID="<tenant>"
       $env:DATABASE="<databaseName>"
     

   • For Mac/Linux:

       export INGEST_ENDPOINT="<ingestionURI>"
       export APP_ID="<appId>"
       export APP_KEY="<appKey>"
       export AZURE_TENANT_ID="<tenant>"
       export DATABASE="<databaseName>"
     

2. Run the tests using the following command:

     dotnet test