Microsoft Azure Monitor (im_azuremonitor)

This module fetches logs from Azure services using the Azure Monitor Log Analytics API.

Prerequisites

To use this module, you need a Microsoft Entra ID application and the following details:

The Application (client) ID.
The Directory (tenant) ID.
A client secret or a certificate and private key pair for authentication.

Create a Microsoft Entra ID application registration

Follow the instructions to Register an application in Microsoft Entra ID. Once you have created the new application, take note of the Application (client) ID and the Directory (tenant) ID from the application Overview page.

Generate a client secret

To use a client secret to authenticate with Microsoft’s API, follow the instructions to Add a client secret. Once you create the new client secret, save it in a safe location because you will not be able to retrieve it again once you navigate away from the page.

Generate a certificate and private key

To use certificate-based authentication to authenticate with Microsoft’s APIs, you need an X.509 certificate and the private key used to generate the certificate. The following instructions guide you through creating the private key pair using OpenSSL.

Save the following script in a file named gencertkey.sh

#!/bin/sh

openssl req -new -nodes -newkey rsa:2048 -x509 -days 730 -keyout certkey.pem -out cert.pem
#openssl pkcs12 -export -out cert.pfx -inkey certkey.pem -in cert.pem
openssl x509 -outform der -in cert.pem -out cert.der
cat cert.der |openssl dgst -binary -sha1 | openssl base64 >cert.base64thumb
THUMBPRINT=`cat cert.base64thumb`
echo "ThumbPrint:$THUMBPRINT"

UUID=`uuidgen`
CERT=`cat cert.pem | grep -v "\-\-\-\-"| tr -d '\n'`

cat <<EOF
"keyCredentials": [
     {
        "customKeyIdentifier":"$THUMBPRINT",
        "keyId":"$UUID",
        "type":"AsymmetricX509Cert",
        "usage":"Verify",
        "value":"$CERT"
     }
],
EOF

The script depends on the openssl toolkit and the uuidgen program. Install the corresponding packages if necessary.

On Debian-based platforms:
```
# apt install openssl uuid-runtime
```
On Centos/Red Hat platforms:
```
# yum install openssl util-linux
```

Execute gencertkey.sh on the computer where NXLog Agent is installed to generate the certificate.

$ ./gencertkey.sh

The output:

Generating a RSA private key
............+++++
................................................+++++
writing new private key to 'certkey.pem'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:
State or Province Name (full name) [Some-State]:
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgits Pty Ltd]:
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []:
Email Address []:
ThumbPrint:0nFt3fB0JP7zuSmHaRQtmsFNYqo=
"keyCredentials": [
{
    "customKeyIdentifier":"0nFt3fB0JP7zuSmHaRQtmsFNYqo=",
    "keyId":"629ab88d-1059-454b-b258-4ca05b46dee4",
    "type":"AsymmetricX509Cert",
    "usage":"Verify",
    "value":"MIIDXTCCAkWgAwIBAgIJAP+XrnwhAxjOMA0GCSqGSIb3DQEBCwUAMEUxCzAJB..."
}
],
--------

Take note of the following:
- The path of the certkey.pem file and the value of ThumbPrint. You will need these to configure NXLog Agent.
- The value of KeyCredentials. You will need this to configure the Microsoft Entra ID application.
Go to the Microsoft Entra ID application registration page, select Manifest on the left, and click Download.

Edit the downloaded manifest file and replace the KeyCredentials value with the value from the previous step.

"keyCredentials": [
{
    "customKeyIdentifier":"0nFt3fB0JP7zuSmHaRQtmsFNYqo=",
    "keyId":"629ab88d-1059-454b-b258-4ca05b46dee4",
    "type":"AsymmetricX509Cert",
    "usage":"Verify",
    "value":"MIIDXTCCAkWgAwIBAgIJAP+XrnwhAxjOMA0GCSqGSIb3DQEBCwUAMEUxCzAJB..."
}
],

Save the changes and upload the manifest to Microsoft Azure.

Pagination

The module polls the API every PollInterval seconds and fetches all new records, using the TimeGenerated field to detect new records. Because there is usually a delay between when the event is sent to the server and when it’s available through the API, the module polls for events between now() - PollInterval*2 seconds and now() - PollInterval seconds. At startup, the module waits for PollInterval*2 seconds before it polls the API unless InitialPollDelay is specified.

Configuration

The im_azuremonitor module accepts the following directives in addition to the common module directives.

Required directives

The following directives are required for the module to start.

CertKeyFile

The path of the private key file that was used to generate the certificate specified by the CertThumbprint directive. It is only required if you’re using certificates to authenticate to the Azure Monitor Log Analytics API.

This directive is mutually exclusive with the ClientSecret directive.

CertThumbprint

The thumbprint of the X.509 certificate. It is only required if you’re using certificates to authenticate to the Azure Monitor Log Analytics API.

This directive is mutually exclusive with the ClientSecret directive.

ClientId

The Application (client) ID of the application that will be used to authenticate with Microsoft Entra ID.

ClientSecret

The Microsoft Entra ID application client secret. It is only required if you’re using a client secret to authenticate to the Azure Monitor Log Analytics API.

This directive is mutually exclusive with the CertThumbprint and CertKeyFile directives.

TableName

The name of the Azure Monitor table to collect logs from.

TenantId

The ID of the Microsoft Entra tenant to connect to.

WorkspaceId

The ID of the workspace that owns the table.

HTTPS directives

The following directives configure secure data transfer via HTTPS.

HTTPSAllowExpired

Set this directive to TRUE to allow connections with remote hosts that present an expired certificate. The default is FALSE; the module rejects connections with expired certificates.

HTTPSAllowUntrusted

Set this directive to TRUE to allow connections with remote hosts regardless of certificate verification results. The default is FALSE; the module only accepts connections with trusted certificates.

HTTPSCADir

Set this directive to the path of a directory containing Certificate Authority (CA) certificates. The module uses these certificates to verify the certificate presented by the remote host. Name the certificate files using the OpenSSL hashed format: the hash of the certificate followed by .0, .1, and so on. To find the hash of a certificate using OpenSSL:

$ openssl x509 -hash -noout -in ca.crt

For example, if the certificate hash is e2f14e4a, name the certificate file e2f14e4a.0. If there is another certificate with the same hash, name it e2f14e4a.1, and so on.

To trust a remote host’s self-signed certificate, include a copy of it in this directory.

If this directive isn’t specified, NXLog Agent falls back to the default operating system root certificate store. Unix-like operating systems commonly store root certificates in /etc/ssl/certs. Windows operating systems use the Windows Certificate Store, while macOS uses the Keychain Access Application as the default certificate store. See Certification Authority (CA) certificates in the NXLog Platform User Guide for more information on using this directive.

In addition, Microsoft’s PKI repository contains root certificates for Microsoft services.

HTTPSCAFile

Set this directive to the path of the Certificate Authority (CA) certificate used to verify the certificate presented by the remote host. To trust a remote host’s self-signed certificate, specify the remote host’s certificate itself. For certificates signed by an intermediate CA, the specified certificate must contain the complete certificate chain (certificate bundle).

HTTPSCertFile

Set this directive to the path of the certificate file to present to the remote host during the HTTPS handshake.

This directive is only required when using a Proxy that uses TLS/SSL.

HTTPSCertKeyFile

Set this directive to the path of the private key file corresponding to the certificate specified by HTTPSCertFile.

This directive is only required when using a Proxy that uses TLS/SSL.

Polling directives

AddHeader

Set this directive to a custom header to add to each HTTP request. Specify this directive multiple times to add more than one header.

Compression

Set this directive to enable HTTP compression for outgoing HTTP messages. The accepted values are none, gzip, and deflate. The default is none; compression is disabled.

Some HTTP servers may not accept compressed HTTP requests. If the server doesn’t support the specified compression method, it may return 415 Unsupported Media Type errors.

HTTPBasicAuthPassword

Set this directive to the HTTP basic authentication password. This directive requires you to also set the HTTPBasicAuthUser directive to use HTTP authentication.

HTTPBasicAuthUser

Set this directive to the HTTP basic authentication username. If the HTTPBasicAuthPassword directive is not set, the module attempts HTTP Basic authentication using an empty password.

Proxy

Set this directive to route outgoing requests through an HTTP or SOCKS proxy host. The format is protocol://hostname:port.

Reconnect

This optional directive sets the reconnect interval in seconds. If it is set, the module attempts to reconnect in every defined second. If it is not set, the reconnect interval will start at 1 second and double with every attempt. In the latter case, when the system decides that the reconnection is successful, the reconnect interval is immediately reset to 1 sec.

The Reconnect directive must be used with caution. If it is used on multiple systems, it can send reconnect requests simultaneously to the same destination, potentially overloading the destination system. It may also cause NXLog Agent to use unusually high system resources or cause NXLog Agent to become unresponsive.

ReconnectOnData

This optional directive defines the behavior when the connection with the remote host is lost. When set to TRUE, the module only attempts to reconnect when it has data to send. The default value is FALSE; it will always keep a connection open with the remote host.

AdjustLag

This optional directive is used to enable or disable the polling interval adjustment mechanism. TRUE enables the polling interval adjustment mechanism. The default value is TRUE.

InitialPollDelay

This optional directive specifies the initial delay in seconds before the module starts polling at startup. The default value is PollInterval*2 seconds.

PollInterval

This optional directive specifies the polling interval, in seconds. The polling interval defines how frequently the module will check for new events. This value must be a positive integer greater than 0. The default value is 60 seconds.

NOTE: When the module starts, the initial downloads may take longer than expected potentially exceeding the configured polling interval. If this occurs, the polling cursor may lag behind widening the gap between the scheduled poll time and the current time making it difficult to catch up. To mitigate this issue, the module automatically adjusts the polling interval. By default, if the elapsed time exceeds twice the configured polling interval, the module adjusts the interval end time to align more closely with the current time. This adjustment helps maintain synchronization and ensures timely polling. To disable this automatic adjustment feature, set the AdjustLag directive to false.

Optional directives

AuthURL

The URL for authenticating with the API. The default value is https://login.microsoftonline.com.

Columns

Specify a comma-separated list of table columns to retrieve. Column names are case-sensitive. If not specified, the module retrieves all columns.

Filter

One or more Where clauses delimited by the | character used to filter the data. For example:

'Where Message !has "test" | Where Message has "abc"'

The queries must comply with the Kusto Query Language (KQL). Any queries not starting with the Where clause are ignored and a warning is logged in the NXLog Agent log file.

LogConnections

Use this boolean directive to turn on connection logging. Since connections can be very frequent, it could generate a lot of noise. However, it helps troubleshoot connection issues. The default value is FALSE.

ReadFromLast

This boolean directive instructs the module on where to start reading events from the log source when NXLog Agent starts.

When TRUE, NXLog Agent will only read events logged after NXLog Agent started, unless SavePos is TRUE and a saved position for this log source exists in the cache file.

When FALSE, NXLog Agent will read all events from the log source, unless SavePos is TRUE and a saved position for this log source exists in the cache file.

The default is TRUE.

The following matrix shows the outcome of this directive in conjunction with the SavePos directive:

ReadFromLast SavePos Saved position Outcome

TRUE

Yes

Reads events from the saved position.

TRUE

Reads events that are logged after NXLog Agent is started.

TRUE

FALSE

Yes

Reads events that are logged after NXLog Agent is started.

TRUE

FALSE

Reads events that are logged after NXLog Agent is started.

FALSE

TRUE

Yes

Reads events from the saved position.

FALSE

TRUE

Reads all events.

FALSE

Yes

Reads all events.

FALSE

Reads all events.

If the NoCache directive is TRUE, it overrides the SavePos directive. In this case, the module behaves as if SavePos is FALSE.

SavePos

Set this directive to TRUE to save the position of the last processed event before NXLog Agent exits. On the next startup, the agent reads the saved position from the cache file and resumes from that point. Together with the ReadFromLast directive, this directive allows the agent to continue reading events from the saved position.

The default is TRUE; the position of the last read event is saved and will be read from the cache file on the next startup.

If the NoCache directive is TRUE, it overrides the SavePos directive. In this case, the module behaves as if SavePos is FALSE.

StartFrom

This optional directive specifies the time of the first event to pull in RFC3339 format. If this directive is not set, the module reads events according to the ReadFromLast directive.

URL

The URL of the Azure Monitor Log Analytics API. The default value is https://api.loganalytics.azure.com.

Creating and populating fields

When the im_azuremonitor module reads log records from the Azure Monitor Log Analytics API, it creates and populates fields according to the returned Columns. You can use the fields for further processing or to convert the log record to a different output format, such as JSON or XML. Additionally, the $raw_event core field is populated as follows:

TimeGenerated Hostname Severity field1=value1 field2=value2 EventType=TableName

The EventType field is populated with the TableName.

If the EventTime, Hostname, and Severity fields are not returned as part of the log record, the following default values are used:

Hostname: The value returned by the hostname() function.
Severity: INFO

Examples

Example 1. Collecting logs from Azure Monitor with minimal configuration

This configuration collects logs from a table named MyLogs. im_azuremonitor receives records from the Log Analytics API in JSON format, which it then parses into structured data and writes each record as a list of key-value pairs to the $raw_event field.

nxlog.conf

<Input azure_table>
    Module         im_azuremonitor

    ClientId        ms_entra_app_id
    TenantId        ms_entra_tenant_id
    ClientSecret    ms_entra_app_client_secret

    WorkspaceId     workspace_id
    TableName       MyLogs
</Input>

The following is a log record after it was processed by NXLog Agent.

Output sample

2024-11-15 12:23:15 nxlog-server INFO MessageSourceAddress="192.168.0.123" SourceModuleName="tcp_listen" SourceModule="im_tcp" Message:"Connection accepted from 192.168.1.200" TenantId="c1580b88-581a-4cd0-a5c8-a3dd46241740" Type="MyLogs" _ResourceId="" EventType="MyLogs"

Example 2. Filtering logs in Azure Monitor

This configuration collects logs from a table named MyLogs. It specifies a Filter to retrieve only logs containing "test" in the Message field.

im_azuremonitor receives records from the Log Analytics API in JSON format, which it then parses into structured data and writes each record as a list of key-value pairs to the $raw_event field.

nxlog.conf

<Input azure_table>
    Module         im_azuremonitor

    ClientId        ms_entra_app_id
    TenantId        ms_entra_tenant_id
    ClientSecret    ms_entra_app_client_secret

    WorkspaceId     workspace_id
    TableName       MyLogs
    Filter          'Where Message has "test"'
</Input>

The following is a matching log record after it was processed by NXLog Agent.

Output sample

2024-11-15 12:23:15 nxlog-server INFO MessageSourceAddress="192.168.0.123" SourceModuleName="tcp_listen" SourceModule="im_tcp" Message:"This is a test message" TenantId="c1580b88-581a-4cd0-a5c8-a3dd46241740" Type="MyLogs" _ResourceId="" EventType="MyLogs"

Example 3. Using certificate-based authentication

This configuration uses certificate-based authentication to connect to the Log Analytics API. See Generate a certificate and private key above.

nxlog.conf

<Input azure_table>
    Module            im_azuremonitor

    ClientId          ms_entra_app_id
    TenantId          ms_entra_tenant_id

    WorkspaceId       workspace_id
    TableName         MyLogs

    CertKeyFile       /path/to/certkey.pem (1)
    CertThumbprint    certificate_thumbprint (2)
</Input>

1	The CertKeyFile directive specifies the path of the certificate’s private key file.
2	The CertThumbprint directive specifies the certificate’s thumprint.