Introducing the LogAnalytics.Client NuGet for .NET Core

by Tobias Zimmergren

Directly related to Log Analytics and sending entities from C#, I have previously talked about Building Custom Data Collectors for Azure Log Analytics and Log custom application security events in Azure Log Analytics which are ingested and used in Azure Sentinel.

I created the LogAnalytics.Client project on GitHub, and recently published a NuGet for anyone to consume.

Simply put: It's an easy way to send logs from your applications to Azure Log Analytics.

It abstracts away the boring bits, leaving us with a client that accepts any entity (object) with valid properties.

A contributing reason why I initially built this was that I kept coming back to the same use case. I didn't want to re-implement the same functionality across multiple projects, so I made a wrapper. Since I kept getting many requests about this topic, I decided to put it on GitHub and push a NuGet.

How do I use LogAnalytics.Client?

Start by installing the LogAnalytics.Client NuGet to your project. You can do this in several ways, depending on your project preferences.

Install the NuGet

Install using the dotnet CLI:

dotnet add package LogAnalytics.Client

Install with the NuGet Package Manager:

Install-Package LogAnalytics.Client

Install by adding a PackageReference to csproj:

<PackageReference Include="LogAnalytics.Client" Version="1.1.1" />

Install using Paket CLI:

paket add LogAnalytics.Client

Using LogAnalytics.Client

Usage is straight forward. Begin by initializing the LogAnalyticsClient:

LogAnalyticsClient logger = new LogAnalyticsClient(
                workspaceId: "LAW ID",
                sharedKey: "LAW KEY");

Next, we can send any of our entities to Log Analytics.

Example of sending a single entity:

await logger.SendLogEntry(new TestEntity
{
    Category = GetCategory(),
    TestString = $"String Test",
    TestBoolean = true,
    TestDateTime = DateTime.UtcNow,
    TestDouble = 2.1,
    TestGuid = Guid.NewGuid()
}, "demolog")
.ConfigureAwait(false);

Example of sending multiple entities in batch: 

List<DemoEntity> entities;
// populate 'entities' in whatever way you need; the next line sends the entire collection in a batch request.

await logger.SendLogEntries(entities, "demolog").ConfigureAwait(false);

The entieies will be represented by rows in Log Analytics.

Here's an example of the entities being present in Log Analytics.

Azure Log Analytics displaying custom events from the LogAnalytics.Client NuGet

Contribute

Everyone is encouraged to help. I appreciate any help on the project. We've already had a few individuals help out with PRs and suggestions, which is excellent!

Development

Setting up the project locally is a great way to contribute quickly.

We need to configure a set of test secrets, as we're running real integration/e2e tests directly with a Log Analytics instance. The setup helps us verify the code works and that the code is valid with the latest version of Log Analytics running in the cloud.

Configure Tests secrets

You need to have your own Log Analytics Workspace Id and Key in your project. We currently make use of user secrets for this.

Using the dotnet CLI from the LogAnalyticsClient.Tests project directory:

dotnet user-secrets set "LawConfiguration:LawId" "YOUR LOG ANALYTICS INSTANCE ID"
dotnet user-secrets set "LawConfiguration:LawKey" "YOUR LOG ANALYTICS WORKSPACE KEY"
dotnet user-secrets set "LawServicePrincipalCredentials:ClientId" "CLIENT ID HERE"
dotnet user-secrets set "LawServicePrincipalCredentials:ClientSecret" "CLIENT SECRET HERE"
dotnet user-secrets set "LawServicePrincipalCredentials:Domain" "TENANT NAME OR DOMAIN ID HERE"

You should now have a secrets.json file in your local project, with contents similar to this:

{
  "LawConfiguration": {
    "LawId": "YOUR LOG ANALYTICS INSTANCE ID",
    "LawKey": "YOUR LOG ANALYTICS WORKSPACE KEY"
  },
  "LawServicePrincipalCredentials": {
    "ClientId": "Principal Client ID Here",
    "ClientSecret": "Principal Client Secret Here",
    "Domain": "Your tenant guid here, or tenant name"
  }
}
Where can I get my credentials?

To make the integration tests work, you need your keys from your instance of Log Analytics. You can find these from the Log Analytics Workspace in the Azure Portal, for example.

To add the Service Principal secrets, you should create a new service principal, add a secret, and grant it read access to the Log Analytics resource.

Check Step 1 from this post:

You should have a pleasant and neat project set up. I've already built a few unit tests and a set of integration tests. These tests help verify that the code works with the latest version of Log Analytics running in the cloud.

LogAnalytics.Client NuGet development

Summary

It was fun to initially build this project, which I did a couple of years ago. To see that people are using it now when it's on NuGet makes it all the more fun. As of today's writing, there are about 2,800 downloads. It's not much, but it looks like there's a growing interest.