traefik_umami_feeder

README

Traefik Umami Feeder

This plugin for enables Traefik Reverse Proxy to feed Umami Analytics with tracking events.

It was created as an alternative to traefik-umami-plugin and inspired by idea of Plausible Feeder Traefik Plugin.

Features

• Super easy to setup, one middleware for all websites
• Server Side Tracking, no need to add JavaScript to your websites
• Fast and private analytics

Installation

To add this plugin to traefik reference this repository as a plugin in the static config. The version references a git tag.

experimental:
  plugins:
    umami-feeder:
      moduleName: github.com/astappiev/traefik-umami-feeder
      version: v1.0.0 # replace with latest version available

[experimental.plugins.umami-feeder]
  moduleName = "github.com/astappiev/traefik-umami-feeder"
  version = "v1.0.0" # replace with latest version available

With the plugin installed, you can configure a middleware in a dynamic configuration such as a config.yml or docker labels.

http:
  middlewares:
    my-umami-middleware:
      plugin:
        umami-feeder:
          umamiHost: "http://umami:3000"
          websites:
            "example.com": "d4617504-241c-4797-8eab-5939b367b3ad"

[http.middlewares]
  [http.middlewares.my-umami-middleware.plugin.umami-feeder]
    umamiHost = "umami:3000"

    [http.middlewares.my-umami-middleware.plugin.umami-feeder.websites]
      "example.com" = "d4617504-241c-4797-8eab-5939b367b3ad"

You have an option to give a list of domains to track (and their website IDs on Umami).
Or, you can give a token and the list will be fetched from Umami. For this, you need either retrieve the token yourself, or use username/password instead.

After that, you need to add the middleware to a router. Remember to reference the correct provider namespace.

E.g. as Docker labels:

- "traefik.http.routers.whoami.middlewares=my-umami-middleware@file"

Or, for all routers in a static configuration:

entryPoints:
  web:
    http:
      middlewares:
        - my-umami-middleware@file

Configuration

key	default	type	description
disabled	false	bool	Set to true to disable the plugin
debug	false	bool	Something doesn't work? Set to true to see more logs (plugins doesn't have access to Traefik's log level)
queueSize	1000	int	The maximum number of events that can be queued before they are sent to the Umami server
umamiHost	-	string	Umami server url, reachable from within traefik (container), e.g. http://umami:3000
umamiToken	-	string	An API Token, used to automatize work with websites, not needed if you provide websites
umamiUsername	-	string	An alternative to umamiToken, you can provide an username and password
umamiPassword	-	string	Only in combination with umamiUsername
umamiTeamId	-	string	In order to organize websites, you can use Umami Teams
websites	-	map	A map of hostnames and their associated Umami IDs. Can also be used to override or extend fetched websites
createNewWebsites	false	bool	If set to true, will try to create a new website on Umami, if domain not found there
trackErrors	false	bool	If set to true, will track errors (status codes >= 400)
trackAllResources	false	bool	Defines whether all requests for any resource should be tracked. By default, only requests that are believed to contain content are tracked
trackExtensions		string[]	Defines an alternative list of file extensions that should be tracked
ignoreUserAgents		string[]	A list of user agents that should be ignored from tracking, e.g. ["Googlebot", "Uptime-Kuma"] (matched with strings.Contains)
ignoreURLs		string[]	A list of URLs that should be ignored from tracking, e.g. ["/health", "https?://[^/]+/health$"] (matched with regexp.Compile.MatchString)
ignoreIPs		string[]	A list of IPs that should be ignored from tracking, e.g. ["127.0.0.1", "10.0.0.1/16"] (matched with netip.ParsePrefix.Contains)
headerIp	X-Real-Ip	string	The header to use to get the real IP address of the client, in case it's forwarded by a proxy

Documentation

Index

• func New(ctx context.Context, next http.Handler, config *Config, name string) (http.Handler, error)
• type Auth
• type AuthResponse
• type Config
  • func CreateConfig() *Config
• type ResponseWriter
  • func (rw *ResponseWriter) Flush()
  • func (rw *ResponseWriter) Hijack() (net.Conn, *bufio.ReadWriter, error)
  • func (rw *ResponseWriter) WriteHeader(code int)
• type SendBody
• type SendPayload
• type UmamiFeeder
  • func (h *UmamiFeeder) ServeHTTP(rw http.ResponseWriter, req *http.Request)
• type UmamiPayload
• type Website
• type WebsitesResponse

Functions

func New

func New(ctx context.Context, next http.Handler, config *Config, name string) (http.Handler, error)

New created a new Demo plugin.

Types

type Auth

type Auth struct {
	Username string `json:"username"`
	Password string `json:"password"`
}

type AuthResponse

type AuthResponse struct {
	Token string `json:"token"`
}

type Config

type Config struct {
	// Disabled disables the plugin.
	Disabled bool `json:"disabled"`
	// Debug enables debug logging, be prepared for flooding.
	Debug bool `json:"debug"`
	// QueueSize defines the size of queue, i.e. the amount of events that are waiting to be submitted to Umami.
	QueueSize int `json:"queueSize"`

	// UmamiHost is the URL of the Umami instance.
	UmamiHost string `json:"umamiHost"`
	// UmamiToken is an API KEY, which is optional, but either UmamiToken or Websites should be set.
	UmamiToken string `json:"umamiToken"`
	// UmamiUsername could be provided as an alternative to UmamiToken, used to retrieve the token.
	UmamiUsername string `json:"umamiUsername"`
	// UmamiPassword is required if UmamiUsername is set.
	UmamiPassword string `json:"umamiPassword"`
	// UmamiTeamId defines a team, which will be used to retrieve the websites.
	UmamiTeamId string `json:"umamiTeamId"`

	// Websites is a map of domain to websiteId, which is required if UmamiToken is not set.
	// If both UmamiToken and Websites are set, Websites will override/extend domains retrieved from the API.
	Websites map[string]string `json:"websites"`
	// CreateNewWebsites when set to true, the plugin will create new websites using API, UmamiToken is required.
	CreateNewWebsites bool `json:"createNewWebsites"`

	// TrackErrors defines whether errors (status codes >= 400) should be tracked.
	TrackErrors bool `json:"trackErrors"`
	// TrackAllResources defines whether all requests for any resource should be tracked.
	// By default, only requests that are believed to contain content are tracked.
	TrackAllResources bool `json:"trackAllResources"`
	// TrackExtensions defines an alternative list of file extensions that should be tracked.
	TrackExtensions []string `json:"trackExtensions"`

	// IgnoreUserAgents is a list of user agents to ignore.
	IgnoreUserAgents []string `json:"ignoreUserAgents"`
	// IgnoreURLs is a list of request urls to ignore, each string is converted to RegExp and urls matched against it.
	IgnoreURLs []string `json:"ignoreURLs"`
	// IgnoreIPs is a list of IPs or CIDRs to ignore.
	IgnoreIPs []string `json:"ignoreIPs"`
	// headerIp Header associated to real IP
	HeaderIp string `json:"headerIp"`
}

Config the plugin configuration.

func CreateConfig

func CreateConfig() *Config

CreateConfig creates the default plugin configuration.

type ResponseWriter

type ResponseWriter struct {
	http.ResponseWriter
	// contains filtered or unexported fields
}

ResponseWriter is used to wrap given response writers.

func (*ResponseWriter) Flush

func (rw *ResponseWriter) Flush()

func (*ResponseWriter) Hijack

func (rw *ResponseWriter) Hijack() (net.Conn, *bufio.ReadWriter, error)

func (*ResponseWriter) WriteHeader

func (rw *ResponseWriter) WriteHeader(code int)

WriteHeader adds custom handling to the wrapped WriterHeader method.

type SendBody

type SendBody struct {
	Payload SendPayload `json:"payload"`
	Type    string      `json:"type"`
}

type SendPayload

type SendPayload struct {
	Website  string `json:"website"`
	Hostname string `json:"hostname"`
	Language string `json:"language,omitempty"`
	Referrer string `json:"referrer,omitempty"`
	Url      string `json:"url"`
}

type UmamiFeeder

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

UmamiFeeder a UmamiFeeder plugin.

func (*UmamiFeeder) ServeHTTP

func (h *UmamiFeeder) ServeHTTP(rw http.ResponseWriter, req *http.Request)

type UmamiPayload

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

type Website

type Website struct {
	ID        string    `json:"id,omitempty"`
	Name      string    `json:"name,omitempty"`
	TeamId    string    `json:"teamId,omitempty"`
	Domain    string    `json:"domain,omitempty"`
	CreatedAt time.Time `json:"createdAt,omitempty"`
}

type WebsitesResponse

type WebsitesResponse struct {
	Data     []Website `json:"data"`
	Count    int       `json:"count"`
	Page     int       `json:"page"`
	PageSize int       `json:"pageSize"`
	OrderBy  string    `json:"orderBy"`
}