reloader

Documentation

Overview

Package reloader contains helpers to trigger reloads of Prometheus instances on configuration changes and to substitute environment variables in config files.

Reloader type is useful when you want to:

• Watch on changes against certain file e.g (`cfgFile`).
• Optionally, specify different different output file for watched `cfgFile` (`cfgOutputFile`). This will also try decompress the `cfgFile` if needed and substitute ALL the envvars using Kubernetes substitution format: (`$(var)`)
• Watch on changes against certain directories (`watchedDirs`).

Once any of those two changes, Prometheus on given `reloadURL` will be notified, causing Prometheus to reload configuration and rules.

This and below for reloader:

	u, _ := url.Parse("http://localhost:9090")
	rl := reloader.New(nil, nil, &reloader.Options{
		ReloadURL:     reloader.ReloadURLFromBase(u),
		CfgFile:       "/path/to/cfg",
		CfgOutputFile: "/path/to/cfg.out",
		WatchedDirs:      []string{"/path/to/dirs"},
		WatchInterval: 3 * time.Minute,
		RetryInterval: 5 * time.Second,
 })

The url of reloads can be generated with function ReloadURLFromBase(). It will append the default path of reload into the given url:

u, _ := url.Parse("http://localhost:9090")
reloader.ReloadURLFromBase(u) // It will return "http://localhost:9090/-/reload"

Start watching changes and stopped until the context gets canceled:

ctx, cancel := context.WithCancel(context.Background())
go func() {
	if err := rl.Watch(ctx); err != nil {
		log.Fatal(err)
	}
}()
// ...
cancel()

Reloader will make a schedule to check the given config files and dirs of sum of hash with the last result, even if it is no changes.

A basic example of configuration template with environment variables:

global:
  external_labels:
    replica: '$(HOSTNAME)'

Index

• func ReloadURLFromBase(u *url.URL) *url.URL
• type Options
• type Reloader
  • func New(logger log.Logger, reg prometheus.Registerer, o *Options) *Reloader
  • func (r *Reloader) Watch(ctx context.Context) error

Examples

• ReloadURLFromBase
• Reloader

Functions

func ReloadURLFromBase

func ReloadURLFromBase(u *url.URL) *url.URL

ReloadURLFromBase returns the standard Prometheus reload URL from its base URL.

Example

package main

import (
	"fmt"
	"log"
	"net/url"

	"github.com/thanos-io/thanos/pkg/reloader"
)

func main() {
	u, err := url.Parse("http://localhost:9090")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(reloader.ReloadURLFromBase(u))
}

Output:

http://localhost:9090/-/reload

Types

type Options

type Options struct {
	// ReloadURL is a prometheus URL to trigger reloads.
	ReloadURL *url.URL
	// CfgFile is a path to the prometheus config file to watch.
	CfgFile string
	// CfgOutputFile is a path for the output config file.
	// If cfgOutputFile is not empty the config file will be decompressed if needed, environment variables
	// will be substituted and the output written into the given path. Prometheus should then use
	// cfgOutputFile as its config file path.
	CfgOutputFile string
	// WatchedDirs is a collection of paths for the reloader to watch over.
	WatchedDirs []string
	// DelayInterval controls how long the reloader will wait without receiving
	// new file-system events before it applies the reload.
	DelayInterval time.Duration
	// WatchInterval controls how often reloader re-reads config and directories.
	WatchInterval time.Duration
	// RetryInterval controls how often the reloader retries a reloading of the
	// configuration in case the endpoint returned an error.
	RetryInterval time.Duration
}

Options bundles options for the Reloader.

type Reloader

type Reloader struct {
	// contains filtered or unexported fields
}

Reloader can watch config files and trigger reloads of a Prometheus server. It optionally substitutes environment variables in the configuration. Referenced environment variables must be of the form `$(var)` (not `$var` or `${var}`).

Example

package main

import (
	"context"
	"io"
	"log"
	"net/http"
	"net/url"
	"time"

	"github.com/thanos-io/thanos/pkg/reloader"
)

func main() {
	u, err := url.Parse("http://localhost:9090")
	if err != nil {
		log.Fatal(err)
	}
	rl := reloader.New(nil, nil, &reloader.Options{
		ReloadURL:     reloader.ReloadURLFromBase(u),
		CfgFile:       "/path/to/cfg",
		CfgOutputFile: "/path/to/cfg.out",
		WatchedDirs:   []string{"/path/to/dirs"},
		WatchInterval: 3 * time.Minute,
		RetryInterval: 5 * time.Second,
		DelayInterval: 1 * time.Second,
	})

	ctx, cancel := context.WithCancel(context.Background())
	go func() {
		if err := rl.Watch(ctx); err != nil {
			log.Fatal(err)
		}
	}()

	reloadHandler := func(w http.ResponseWriter, req *http.Request) {
		if _, err := io.WriteString(w, "Reloaded\n"); err != nil {
			http.Error(w, err.Error(), http.StatusInternalServerError)
		}
	}

	http.HandleFunc("/-/reload", reloadHandler)
	log.Fatal(http.ListenAndServe(":9090", nil))

	cancel()
}

func New

func New(logger log.Logger, reg prometheus.Registerer, o *Options) *Reloader

New creates a new reloader that watches the given config file and directories and triggers a Prometheus reload upon changes.

func (*Reloader) Watch

func (r *Reloader) Watch(ctx context.Context) error

Watch detects any change made to the watched config file and directories. It returns when the context is canceled. Whenever a filesystem change is detected or the watch interval has elapsed, the reloader expands the config file (if cfgOutputFile is specified) and triggers a reload if the configuration file or files in the watched directories have changed. Because some edge cases might be missing, the reloader also relies on the watch interval.