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

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 ID tenant to connect to.

WorkspaceId

The ID of the workspace that owns the table.

HTTP(S) directives

The following directives are for configuring HTTP(S) connection settings.

AddHeader

This optional directive can be specified multiple times to add custom headers to each HTTP request.

Compression

This optional directive can be used to enable HTTP compression for outgoing HTTP messages. The possible values are none, gzip, and deflate. By default, compression is disabled. Please note that some HTTP servers may not accept compressed HTTP requests. If a server doesn’t support a specific compression method, it may return 415 Unsupported Media Type errors in response to compressed requests.

HTTPBasicAuthPassword

HTTP basic authentication password. You must also set the HTTPBasicAuthUser directive to use HTTP authentication.

HTTPBasicAuthUser

HTTP basic authentication username. You must also set the HTTPBasicAuthPassword directive to use HTTP authentication.

HTTPSAllowExpired

Specifies if the connection should be allowed with an expired certificate. If set to TRUE, the remote host will be able to connect with an expired certificate. The default is FALSE: the certificate must not be expired.

HTTPSAllowUntrusted

Specifies if the connection should be allowed without certificate verification. If set to TRUE, the connection will be allowed even if the remote host presents an unknown or self-signed certificate. The default value is FALSE: the remote host must present a trusted certificate.

HTTPSCADir

The path to a directory containing certificate authority (CA) certificates. These certificates will be used to verify the certificate presented by the remote host. The certificate files must be named using the OpenSSL hashed format, i.e. the hash of the certificate followed by .0, .1 etc. To find the hash of a certificate using OpenSSL:

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

For example, if the certificate hash is e2f14e4a, then the certificate filename should be e2f14e4a.0. If there is another certificate with the same hash then it should be named e2f14e4a.1 and so on.

A remote host’s self-signed certificate (which is not signed by a CA) can also be trusted by including a copy of the certificate in this directory.

The default operating system root certificate store will be used if this directive is not specified. 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

The path of the certificate authority (CA) certificate that will be used to verify the certificate presented by the remote host. A remote host’s self-signed certificate (which is not signed by a CA) can be trusted by specifying the remote host certificate itself. In case of certificates signed by an intermediate CA, the certificate specified must contain the complete certificate chain (certificate bundle).

HTTPSCertFile

The path of the certificate file that will be presented to the remote host during the HTTPS handshake.

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

HTTPSCertKeyFile

The path of the private key file that was used to generate the certificate specified by the HTTPSCertFile directive. This is used for the HTTPS handshake.

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

Proxy

This optional directive is used to specify the protocol, IP address (or hostname) and port number of the HTTP or SOCKS proxy host to be used. 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. If the duration of the successful connection is greater than the current reconnect interval, then the reconnect interval will be 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.

Polling directives

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 optional boolean directive instructs the module on where to start reading events from the log source. Reading all events can result in a lot of messages and is usually not the expected behavior.

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 is found in the cache file.
When FALSE, NXLog Agent will read all events in the log source from the start, unless SavePos is TRUE and a saved position for this log source is found in the cache file.
If the ReadFromLast directive is not specified, it defaults to 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.

NOTE: The SavePos directive can be overridden by the global NoCache directive. If NoCache is TRUE, the SavePos directive is considered to be FALSE.

SavePos

This optional boolean directive instructs the module whether to save the position of the last read event before NXLog Agent exits. On the next startup, NXLog Agent will try to read the saved position from the cache file. This directive in conjunction with the ReadFromLast directive allows for resuming reading events directly from the saved position.

When TRUE, the position of the last read event are saved and will be read from the cache file upon startup.
If this directive is not specified, it defaults to TRUE.

This directive can be overridden by the global NoCache directive. If NoCache is TRUE, the SavePos directive is considered to be 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        azure_ad_app_id
    TenantId        azure_ad_tenant_id
    ClientSecret    azure_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        azure_ad_app_id
    TenantId        azure_ad_tenant_id
    ClientSecret    azure_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          azure_ad_app_id
    TenantId          azure_ad_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.