caddyumami

README

Caddy Umami Plugin

A module for Caddy which sends HTTP request information to Umami as page view events. The data is sent directly from the web server to Umami's /api/send endpoint without requiring you to include any client-side JavaScript on your website. The visitor's IP is set via the X-Forwarded-For header or the header specified with client_ip_header, one of which should be set as CLIENT_IP_HEADER in Umami.

Config

umami [<matcher>] {
	event_endpoint <endpoint>
	website_uuid <uuid>

	# the following are optional:

	allowed_extensions <extensions ...>
	client_ip_header <name>
	cookie_consent [path_only|disable_all] [<name>]
	cookie_resolution [<name>]
	device_detection
	trusted_ip_header <name>
	report_all_resources
	static_metadata {
		<key> <value>
		...
		<key> <value>
	}
}

• event_endpoint (required) is the address of your Umami installation's send API endpoint
• website_uuid (required) is the UUID of the website from your Umami dashboard
• allowed_extensions is a list of extensions which indicate valid content.
  • Make sure to include "" in this list if you want to track URLs which don't end in a file extension, such as / or /about-us
  • If unspecified, the default list of extensions is:
    • No extension
    • .htm
    • .html
    • .php
• client_ip_header is the name of an HTTP header which will be sent to Umami alongside X-Forwarded-For, which contains the visitor's IP address.
• cookie_consent is the name of a cookie, if that cookie's value is false then this plugin will not run. If a name is not set, the default name is umami_consent.
• cookie_resolution is the name of a cookie whose value should be the user's screen resolution, for example 1920x1080. It is your responsibility to set this cookie with client-side JavaScript (not provided). If this cookie is not set, device type will just be reported as unknown. If a name is not set, the default name is umami_resolution.
• device_detection can be enabled to set the sent screen resolution based on Sec-CH-UA-Mobile/Sec-CH-UA-Platform, for some rudimentary device detection without cookies. If this and cookie_resolution are both enabled, a screen resolution set by the cookie will take precedence.
• trusted_ip_header is the name of an incoming HTTP request header which contains the visitor's true IP, which will then be sent to Umami via the X-Forwarded-For. This may be useful if your Caddy server is behind a reverse proxy.
• report_all_resources can be included to report all requests to Umami, overriding allowed_extensions. By default, only requests with certain extensions are reported. This may be especially useful when using this module with a matcher.
• static_metadata is information which will be added to the query strings delivered to Umami. Note that if there is a query string which matches a key used here in the original web request, the value set here will be appended to that query string.
  • For example, if you set server node1 as the <key> <value> pair here, when a visitor accesses /about-us on your website, the path sent to Umami will be /about-us?server=node1. This allows you to do things like track which Caddy server sent the event data to Umami, and filter events in Umami based on that metadata (because Umami allows filtering by query string, but not by other things like event data).

Example

You should specify the order of the umami directive in your global options, otherwise the umami block has to be defined inside a route block.

{
	# see: https://caddyserver.com/docs/caddyfile/directives#directive-order
	order umami after route
}

example.com {
	umami {
		event_endpoint "https://umami.example.com/api/send"
		website_uuid "4fa2c16a-6c0f-488f-986f-bc26d90c76d1"
		allowed_extensions "" .html .htm .php
		client_ip_header X-Real-IP
		device_detection
	}

	// ...

}

Thanks

• Safing for Plausible Feeder Traefik Plugin

License

Copyright © 2024 Jonah Aragon

This source code is made available under the MIT and Apache licenses (i.e. you can pick which one to follow). This is because I generally prefer MIT and chose it first, but later noticed most of the Caddy ecosystem uses Apache 2.0 😄

Documentation

Index

• type CookieConsent
• type StaticMetadata
  • func ParseCaddyfileStaticMetadata(d *caddyfile.Dispenser) ([]StaticMetadata, error)
• type Umami
  • func (Umami) CaddyModule() caddy.ModuleInfo
  • func (p *Umami) GetAllowed(r *http.Request) int
  • func (p *Umami) GetClientIP(r *http.Request) string
  • func (p *Umami) GetClientInfo(r *http.Request, payload map[string]interface{})
  • func (p *Umami) Provision(ctx caddy.Context) error
  • func (p Umami) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error
  • func (p *Umami) UnmarshalCaddyfile(d *caddyfile.Dispenser) error
  • func (p *Umami) Validate() error

Types

type CookieConsent

type CookieConsent struct {
	// The name of the cookie that stores the consent setting.
	Name string `json:"name,omitempty"`
	// Can be "disable_all" to disable sending analytics if the cookie value is "false",
	// or "path_only" to send analytic data without client information (IP, user agent, etc.) if the cookie value is "false".
	// Defaults to "disable_all" if not specified.
	Behavior string `json:"behavior,omitempty"`
}

Cookie-based consent settings.

type StaticMetadata

type StaticMetadata struct {
	// The key of the metadata.
	Key string `json:"key,omitempty"`
	// The value of the metadata.
	Value string `json:"value,omitempty"`
}

Optional static metadata to include with each event via query string.

func ParseCaddyfileStaticMetadata

func ParseCaddyfileStaticMetadata(d *caddyfile.Dispenser) ([]StaticMetadata, error)

type Umami

type Umami struct {
	// The address of your Umami installation's send API endpoint.
	EventEndpoint string `json:"event_endpoint"`
	// The UUID of the website you want to track.
	WebsiteUUID string `json:"website_uuid"`
	// A map of page path extensions that should be reported to Umami. You must include the leading dot.
	AllowedExtensions []string `json:"allowed_extensions,omitempty"`
	// The header to send the client IP address to Umami with.
	ClientIPHeader string `json:"client_ip_header,omitempty"`
	// Enables reporting of all resources (ignoring extension checks).
	ReportAllResources bool `json:"report_all_resources,omitempty"`
	// The header to use to get the client IP address from, behind a trusted reverse proxy.
	TrustedIPHeader string `json:"trusted_ip_header,omitempty"`
	// A map of cookie-based consent settings. Only the first value in the map is utilized currently.
	CookieConsent []CookieConsent `json:"cookie_consent,omitempty"`
	// The name of the cookie that stores the visitor's screen resolution.
	CookieResolution string `json:"cookie_resolution,omitempty"`
	// Enable rudimentary device detection based on Sec-CH-UA-Mobile and Sec-CH-UA-Platform headers.
	DeviceDetection bool `json:"device_detection,omitempty"`
	// Optional static metadata to include with each event via query string.
	StaticMetadata []StaticMetadata `json:"static_metadata,omitempty"`
	// contains filtered or unexported fields
}

A Caddy module which sends visitor information to Umami's Events REST API endpoint.

func (Umami) CaddyModule

func (Umami) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*Umami) GetAllowed

func (p *Umami) GetAllowed(r *http.Request) int

Check whether analytics should be performed based on cookie consent settings. 0 - no analytics 1 - all analytics 2 - only path analytics

func (*Umami) GetClientIP

func (p *Umami) GetClientIP(r *http.Request) string

Get the client IP address from the request. If a trusted IP header is provided, use that instead. If the client opted-out, replace the IP address with a psuedo Class E IP address.

func (*Umami) GetClientInfo

func (p *Umami) GetClientInfo(r *http.Request, payload map[string]interface{})

Get client information from the request.

func (*Umami) Provision

func (p *Umami) Provision(ctx caddy.Context) error

Provision logging for module

func (Umami) ServeHTTP

func (p Umami) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error

ServeHTTP implements the caddyhttp.MiddlewareHandler interface.

func (*Umami) UnmarshalCaddyfile

func (p *Umami) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile implements caddyfile.Unmarshaler.

func (*Umami) Validate

func (p *Umami) Validate() error