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, 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.
Image - the image name and tag of the 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% image:%$!metadata!Image% 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