Skip to content

Autoconf

Epoch collectors can automatically detect and configure popular integrations such as Kubernetes, Consul, Redis, Memcached, and Apache. The Autoconf feature works by detecting specific container images and then dynamically associating the correct configurations for that image.

For example, the collector would look for the consul docker image and automatically generate the correct configuration to pull in consul metrics.

Default Autoconf Templates

Autoconf templates are configured by default for the following applications:

Concept

In a traditional non-container environment, integration configuration is static like the environment in which it runs. The collector reads integration configurations from disk when it starts, and as long as it’s running, it continuously runs every configured integration. Any network-related options configured within them serve to identify specific instances of a monitored service (for example, a redis instance at 10.0.0.61:6379).

In containerized environments, the IP address and port configuration of services can be dynamic and change at runtime. With the Autoconf feature the integration configurations can adapt to the actual IP address and port of the services at runtime.

Execution Model

The execution model for computing autoconf differs from static config files. The collector doesn’t run all the integrations all the time unlike static config; it decides which integrations to enable by inspecting all containers currently running on the same host as the collector.

As the collector inspects each running container, it checks if the container matches any of the container identifiers from any loaded templates. For each match, the collector generates a static integration configuration by substituting the IP address and port of the matching container. Then it enables the integration using the static configuration.

The collector watches for container events (creation, destruction, starts, and stops) and enables, disables, and regenerates static integration configurations on such events.

Autodiscovery Template

Autodiscovery uses templates for integration configuration. In each template, the collector looks for two template variables: %%host%% and %%port%% to appear in place of any normally-hardcoded network options. For example: a template for the collector’s Go Expvar integration would contain the option expvar_url: http://%%host%%:%%port%%. For containers that have more than one IP address or exposed port, you can direct Autodiscovery to pick the right ones by using template variable indexes.

Template Source: Files (Autoconf)

The collector looks for Autodiscovery templates in its conf.d/auto_conf directory. Some integrations as listed here are enabled by default. The default templates are adequate for basic use cases. By providing custom Autoconf files, you can customize the configuration further with extra integration options, different container identifiers, different port mapping, and so on.

Template Variable Indexes

For containers that have many IP addresses or expose many ports, you can tell Autodiscovery which ones to choose by appending an underscore and integer to the template variable; for example, %%host_0%%, %%port_4%%. After inspecting the container, Autodiscovery sorts the IP addresses and ports numerically and in ascending order, so for a container that exposes ports 80, 443, and 8443, %%port_0%% refers to port 80. Non-indexed template variables refer to the last item in the sorted list, so in this case, %%port%% means port 8443.

You can also add a network name suffix to the %%host%% variable to identify containers attached to multiple networks; for example, %%host_bridge%%, %%host_swarm%%. When %%host%% does not have a suffix, Autodiscovery picks the container’s bridge network IP address.

Image Identifiers

Autoconf uses docker-images attributes to identify the application and generate the correct configuration file. It uses the default docker image name (such as redis or consul) to identify the application. If you are using custom docker images, however, then you will need to update the docker-image identifier.

For example, below is the apache.yaml template packaged with the containerized epoch-dd-agent:

docker_images:
  - httpd

init_config:

instances:
  - apache_status_url: http://%%host%%/server-status?auto

Notice the docker_images option. This required option lets you provide container identifiers. Autoconf will apply this template to any containers on the same host that run any httpd image.

Autoconf cannot distinguish between identically-named images from different sources or with different tags. If you have one container running library/httpd:latest and another running yourusername/httpd:v2, Autoconf will apply the above template to both containers. You must, however, provide short names for container images, for example httpd. The name library/httpd:latest is not valid.

If you need to apply different integration configurations to different containers running the same image, use labels to identify the containers. Label each container differently, then add each label to the docker_images list of any template file. The docker_images supports any kind of container identifier, not just images.