# 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

© 2008–2025 Rainer Gerhards and others. Licensed under the Apache License 2.0.