dockerobserver

README

Docker Observer Extension

Status
Stability	beta
Distributions	contrib
Issues
Code Owners	@MovieStoreGuy

The Docker observer extension is a Receiver Creator-compatible "watch observer" that will detect and report container endpoints discovered through the Docker API. Only containers that are in the state of Running and not Paused will emit endpoints. This observer watches the Docker engine's stream of events to dynamically create, update, and remove endpoints as events are processed.

Requires Docker API Version 1.24+.

The collector will need permissions to access the Docker Engine API, specifically it will need read access to the Docker socket (default unix:///var/run/docker.sock).

Example Config

extensions:
  docker_observer:
    # url of the docker socket, default to unix:///var/run/docker.sock
    endpoint: my/path/to/docker.sock
    # list of container image names to exclude
    excluded_images: ['redis', 'another_image_name']
    # client API version, default to 1.24
    api_version: 1.25
    # max amount of time to wait for a response from Docker API , default to 5s
    timeout: 15s

receivers:
  receiver_creator:
    watch_observers: [docker_observer]
    receivers:
      nginx:
        rule: type == "container" and name matches "nginx" and port == 80
        config:
          endpoint: '`endpoint`/status'
          collection_interval: 10s

Configuration

endpoint

The URL of the docker server.

default: unix:///var/run/docker.sock

timeout

The maximum amount of time to wait for docker API responses.

default: 5s

api_version

The client API version. If using one with a terminating zero, input as a string to prevent undesired truncation (e.g. "1.40" instead of 1.40, which is parsed as 1.4).

default: 1.24

excluded_images

A list of filters whose matching images are to be excluded. Supports literals, globs, and regex.

default: []

use_hostname_if_present

If true, the Config.Hostname field (if present) of the docker container will be used as the discovered host that is used to configure receivers. If false or if no hostname is configured, the field NetworkSettings.IPAddress is used instead. These settings can be found in the output of the Docker API's Container Inspect json.

default: false

use_host_bindings

If true, the observer will configure receivers for matching container endpoints using the host bound ip and port. This is useful if containers exist that are not accessible to an instance of the collector running outside of the docker network stack.

default: false

ignore_non_host_bindings

If true, the observer will ignore discovered container endpoints that are not bound to host ports. This is useful if containers exist that are not accessible to an instance of the collector running outside of the docker network stack.

default: false

cache_sync_interval

The time to wait before resyncing the list of containers the observer maintains through the docker event listener example: cache_sync_interval: "20m"

default: 60m

Endpoint Variables

The following endpoint variables are exposed to the receiver creator to be used in discovery rules:

Variable	Type	Description
name	string	Primary name of the container
image	string	Name of the container image
port	uint16	Exposed port of the container
alternate_port	uint16	Exposed port accessed through redirection, such as a mapped port
command	string	The command used to invoke the process of the container
container_id	string	ID of the container
host	string	Hostname or IP of the underlying host the container is running on
transport	string	Transport protocol used by the endpoint (TCP or UDP)
labels	map[string]string	User-specified metadata labels on the container

Documentation

Index

• func NewFactory() extension.Factory
• type Config
  • func (config Config) Validate() error

Functions

func NewFactory

func NewFactory() extension.Factory

NewFactory should be called to create a factory with default values.

Types

type Config

type Config struct {

	// The URL of the docker server.  Default is "unix:///var/run/docker.sock"
	Endpoint string `mapstructure:"endpoint"`

	// The maximum amount of time to wait for docker API responses.  Default is 5s
	Timeout time.Duration `mapstructure:"timeout"`

	// A list of filters whose matching images are to be excluded.  Supports literals, globs, and regex.
	ExcludedImages []string `mapstructure:"excluded_images"`

	// If true, the "Config.Hostname" field (if present) of the docker
	// container will be used as the discovered host that is used to configure
	// receivers.  If false or if no hostname is configured, the field
	// `NetworkSettings.IPAddress` is used instead.
	UseHostnameIfPresent bool `mapstructure:"use_hostname_if_present"`

	// If true, the observer will configure receivers for matching container endpoints
	// using the host bound ip and port.  This is useful if containers exist that are not
	// accessible to an instance of the agent running outside of the docker network stack.
	// If UseHostnameIfPresent and this config are both enabled, this setting will take precedence.
	UseHostBindings bool `mapstructure:"use_host_bindings"`

	// If true, the observer will ignore discovered container endpoints that are not bound
	// to host ports.  This is useful if containers exist that are not accessible
	// to an instance of the agent running outside of the docker network stack.
	IgnoreNonHostBindings bool `mapstructure:"ignore_non_host_bindings"`

	// The time to wait before resyncing the list of containers the observer maintains
	// through the docker event listener example: cache_sync_interval: "20m"
	// Default: "60m"
	CacheSyncInterval time.Duration `mapstructure:"cache_sync_interval"`

	// Docker client API version. Default is 1.22
	DockerAPIVersion string `mapstructure:"api_version"`
}

Config defines configuration for docker observer

func (Config) Validate

func (config Config) Validate() error