imdocker: Docker Input Module¶

Module Name:	imdocker
Author:	Nelson Yen
Available since:	8.41.0

Purpose¶

The imdocker input plug-in provides the ability to receive container logs from Docker (engine) via the Docker Rest API.

Other features include:

filter containers through the plugin options
handle long log lines (greater than 16kb) and obtain
container metadata, such as container id, name, image id, labels, etc.

Note: Multiple docker instances are not supported at the time of this writing.

Configuration Parameters¶

The configuration parameters for this module are designed for tailoring the behavior of imdocker.

Note

Parameter names are case-insensitive; CamelCase is recommended for readability.

Note

This module supports module parameters, only.

Module Parameters¶

Parameter	Summary
DockerApiUnixSockAddr	Unix socket path for Docker API connections; default `/var/run/docker.sock`.
ApiVersionStr	Docker API version string like `v1.27`.
PollingInterval	Seconds between `List Containers` polls for new containers; default `60`.
ListContainersOptions	HTTP query options appended to `List Containers` requests; omit leading `?`.
GetContainerLogOptions	HTTP query options for `Get container logs` requests; default `timestamps=0&follow=1&stdout=1&stderr=1&tail=1`.
RetrieveNewLogsFromStart	Whether to read newly discovered container logs from start; default `on`.
DefaultFacility	Syslog facility assigned to received messages; default `user`.
DefaultSeverity	Syslog severity assigned to received messages; default `info`.
escapeLF	Escapes line feeds as `#012` in multi-line messages; default `on`.

Metadata¶

The imdocker module supports message metadata. It supports the following data items:

Id - the container id associated with the message.
Names - the first container associated with the message.
ImageID - the image id of the container associated with the message.
Labels - all the labels of the container associated with the message in json format.

Note: At the time of this writing, metadata is always enabled.

Statistic Counter¶

This plugin maintains statistics <http://www.rsyslog.com/rsyslog-statistic-counter/>. The statistic is named “imdocker”.

The following properties are maintained for each listener:

submitted - total number of messages submitted to main queue after reading from journal for processing since startup. All records may not be submitted due to rate-limiting.
ratelimit.discarded - number of messages discarded due to rate-limiting within configured rate-limiting interval.
curl.errors - total number of curl errors.

Caveats/Known Bugs¶

At the moment, this plugin only supports a single instance of docker on a host.

Configuration Examples¶

Load module, with only defaults¶

This activates the module with all the default options:

module(load="imdocker")

Load module, with container filtering¶

This activates the module with container filtering on a label:

module(load="imdocker"
  DockerApiUnixSockAddr="/var/run/docker.sock"
  ApiVersionStr="v1.27"
  PollingInterval="60"
  ListContainersOptions="filters={\"label\":[\"log_opt_enabled\"]}"
  GetContainerLogOptions="timestamps=0&follow=1&stdout=1&stderr=0&tail=1"
)

Example template to get container metadata¶

An example of how to create a template with container metadata

template (name="ImdockerFormat" type="string"
      string="program:%programname% tag:%syslogtag% id:%$!metadata!Id% name:%$!metadata!Names% imageid:%$!metadata!ImageID% labels:%$!metadata!Labels% msg: %msg%\n"
)

Support: rsyslog Assistant | GitHub Discussions | GitHub Issues: rsyslog source project

Contributing: Source & docs: rsyslog source project