NLog.Targets.HttpClient 6.2.2

NLog.Targets.HttpClient

The NLog HttpClient target sends log events to HTTP or HTTPS endpoints.

• Supports HTTP POST, GET, and custom HTTP methods.
• Supports batching multiple log events into a single HTTP request.
• Supports batching as JSON arrays or newline-delimited JSON (NDJSON).
• Supports GZip compression.
• Supports custom request headers.
• Supports HTTP authentication.
• Supports client certificates (mTLS).
• Supports HTTP proxies.

If you have trouble with output, check NLog InternalLogger for clues. See also Troubleshooting NLog.

Register Extension

The HttpClient type alias is available in an NLog.config file after registering the extension:

<extensions>
    <add assembly="NLog.Targets.HttpClient"/>
</extensions>

Alternatively, register it in code using the fluent configuration API:

LogManager.Setup().SetupExtensions(ext => {
    ext.RegisterTarget<NLog.Targets.HttpClientTarget>();
});

Configuration Example

HttpClient and JsonLayout can be used together to send structured log events to HTTP endpoints that accept JSON or newline-delimited JSON (NDJSON), including log collectors such as Fluentd, Fluent Bit, Logstash, and Vector.

<nlog xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<extensions>
  <add assembly="NLog.Targets.HttpClient"/>
</extensions>

<targets>
  <target xsi:type="HttpClient"
    name="http"
    url="http://localhost:9880/logs_api"
    contentType="application/x-ndjson"
    batchSize="100">
    <header name="User-Agent" layout="NLog-Http-${appdomain:friendly}" />
    <layout xsi:type="JsonLayout" includeEventProperties="true">
      <attribute name="timestamp" layout="${date:format=o:universalTime=true}" />
      <attribute name="hostname" layout="${hostname}" />
      <attribute name="application" layout="${processname}" />
      <attribute name="level" layout="${level}" />
      <attribute name="message" layout="${message:withException=true}" />
    </layout>
  </target>
</targets>

<rules>
    <logger name="*" minlevel="Info" writeTo="http" />
</rules>
</nlog>

Parameters

Splunk HTTP Event Collector (HEC)

SplunkLayout from the NLog.Targets.Network package can be used together with the HttpClient target to send events to the Splunk HEC /services/collector/event endpoint using newline-delimited JSON (NDJSON).

SplunkLayout renders the complete HEC event, including the outer time, host, source, sourcetype, index, and nested event fields.

The Authorization header is mandatory for Splunk HEC: Authorization: Splunk <hec-token>

<nlog xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<extensions>
  <add assembly="NLog.Targets.HttpClient"/>
  <add assembly="NLog.Targets.Network"/>
</extensions>
<targets>
  <target xsi:type="HttpClient"
    name="splunk"
    url="https://splunk-host:8088/services/collector/event"
    batchSize="100">
    <header name="Authorization" layout="Splunk ${configsetting:Splunk.Token}" />
    <layout xsi:type="SplunkLayout" />
  </target>
</targets>
<rules>
    <logger name="*" minlevel="Info" writeTo="splunk" />
</rules>
</nlog>

OpenSearch Bulk API

EcsLayout from the Elastic.CommonSchema.NLog can be used together with the HttpClient target to send ECS-formatted log events to OpenSearch using the Bulk API.

EcsLayout produces the ECS-formatted JSON document, while CompoundLayout adds the Bulk API action metadata. The 
 is an explicit LF required to separate the action and document lines in the NDJSON payload for Bulk API. The URL /logs/_bulk supplies the default target index, so the Bulk API action does not need to provide an index value.

<nlog xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<extensions>
  <add assembly="NLog.Targets.HttpClient"/>
  <add assembly="Elastic.CommonSchema.NLog"/>
</extensions>
<targets>
  <target xsi:type="HttpClient"
    name="opensearch"
    url="https://localhost:9200/logs/_bulk"
    contentType="application/x-ndjson"
    batchSize="100">
    <layout xsi:type="CompoundLayout">
        <layout xsi:type="SimpleLayout" text="{&quot;index&quot;:{}}&#xA;" />
        <layout xsi:type="EcsLayout" />
    </layout>
  </target>
</targets>
<rules>
    <logger name="*" minlevel="Info" writeTo="opensearch" />
</rules>
</nlog>

For production use, consider targeting a write index alias managed by your rollover/index lifecycle strategy rather than a permanently fixed index name. Authentication can be configured using the standard HttpClient target authentication and header options.

Note that the OpenSearch Bulk API can return HTTP 200 even when some bulk operations fail. The HttpClient target retries requests based on the HTTP status code, but does not inspect the Bulk API response body for per-document failures.

Log export depends on an in-memory queue, so log events can be lost if the application crashes or exits without a proper flush or shutdown. For stronger delivery guarantees, consider using Elastic.CommonSchema.NLog with the NLog FileTarget, then use Fluent Bit (AWS FireLens) or Data Prepper to forward the logs to OpenSearch.

Client Certificates (mTLS)

Mutual TLS authentication can be enabled using a client certificate:

<target xsi:type="HttpClient"
        name="http"
        url="https://secure.example.com/logs"
        sslCertificateFile="client.pfx"
        sslCertificatePassword="secret" />

Alternatively, load the client certificate from the Windows certificate store by thumbprint:

<target xsi:type="HttpClient"
        name="http"
        url="https://secure.example.com/logs"
        sslCertificateThumbprint="A1B2C3D4E5F6..." />

Retry Behavior

The target treats the following HTTP response status codes as transient failures, that can be retried:

• 408 Request Timeout
• 429 Too Many Requests
• 5xx Server Errors

Client-side failures such as 400 Bad Request are not retried.

Notes

• The target internally reuses a single HttpClient instance to take advantage of connection pooling.
• The HttpClient instance is periodically recycled (every 5 minutes) to detect DNS changes while still benefiting from pooled connections.