tracker

Documentation

Index

• func ExtendSession(r *http.Request, salt string, options *HitOptions)
• func Fingerprint(r *http.Request, salt string, date time.Time, headerParser []ip.HeaderParser, ...) uint64
• func IgnoreHit(r *http.Request) bool
• func SetFingerprintKeys(key0, key1 uint64)
• type Config
• type EventOptions
• type HitOptions
  • func HitOptionsFromRequest(r *http.Request) *HitOptions
• type SessionState
  • func HitFromRequest(r *http.Request, salt string, options *HitOptions) (*model.PageView, SessionState, *model.UserAgent)
• type Tracker
  • func NewTracker(client db.Store, salt string, config *Config) *Tracker
  • func (tracker *Tracker) ClearSessionCache()
  • func (tracker *Tracker) Event(r *http.Request, eventOptions EventOptions, options *HitOptions)
  • func (tracker *Tracker) ExtendSession(r *http.Request, options *HitOptions)
  • func (tracker *Tracker) Flush()
  • func (tracker *Tracker) Hit(r *http.Request, options *HitOptions)
  • func (tracker *Tracker) SetGeoDB(geoDB *geodb.GeoDB)
  • func (tracker *Tracker) Stop()

Functions

func ExtendSession

func ExtendSession(r *http.Request, salt string, options *HitOptions)

ExtendSession looks up and extends the session for given request. This function does not Store a hit or event in database.

func Fingerprint

func Fingerprint(r *http.Request, salt string, date time.Time, headerParser []ip.HeaderParser, allowed []net.IPNet) uint64

Fingerprint returns a hash for given request and salt. The hash is unique for the visitor and day.

func IgnoreHit

func IgnoreHit(r *http.Request) bool

IgnoreHit returns true, if a hit should be ignored for given request, or false otherwise. The easiest way to track visitors is to use the Tracker.

func SetFingerprintKeys

func SetFingerprintKeys(key0, key1 uint64)

SetFingerprintKeys used to set the SipHash keys for fingerprints. This function is NOT concurrency save and should be called once on startup (before generating the first fingerprint).

Types

type Config

type Config struct {
	// Worker sets the number of workers that are used to client hits.
	// Must be greater or equal to 1.
	Worker int

	// WorkerBufferSize is the size of the buffer used to client hits.
	// Must be greater than 0. The hits are stored in batch when the buffer is full.
	WorkerBufferSize int

	// WorkerTimeout sets the timeout used to client hits.
	// This is used to allow the workers to client hits even if the buffer is not full yet.
	// It's recommended to set this to a few seconds.
	// If you leave it 0, the default timeout is used, else it is limited to 60 seconds.
	WorkerTimeout time.Duration

	// ReferrerDomainBlacklist see HitOptions.ReferrerDomainBlacklist.
	ReferrerDomainBlacklist []string

	// ReferrerDomainBlacklistIncludesSubdomains see HitOptions.ReferrerDomainBlacklistIncludesSubdomains.
	ReferrerDomainBlacklistIncludesSubdomains bool

	// SessionCache is the session cache implementation to be used.
	// This will be set to NewMemCache by default.
	SessionCache session.Cache

	// MaxSessions sets the maximum size for the session cache.
	// If you leave it 0, the default will be used.
	MaxSessions int

	// SessionMaxAge see HitOptions.SessionMaxAge.
	SessionMaxAge time.Duration

	// HeaderParser see HitOptions.HeaderParser.
	// Set it to nil to use the DefaultHeaderParser list.
	HeaderParser []ip.HeaderParser

	// AllowedProxySubnets see HitOptions.AllowedProxySubnets.
	// Set it to nil to allow any IP.
	AllowedProxySubnets []net.IPNet

	// MinDelay see HitOptions.MinDelay.
	MinDelay int64

	// IsBotThreshold see HitOptions.IsBotThreshold.
	// Will be set to 5 by default.
	IsBotThreshold uint8

	// MaxPageViews see HitOptions.MaxPageViews.
	// Will be set to 150 by default.
	MaxPageViews uint16

	// DisableFlaggingBots disables MinDelay and IsBotThreshold (otherwise these would be set to their default values).
	DisableFlaggingBots bool

	// GeoDB enables/disabled mapping IPs to country codes.
	// Can be set/updated at runtime by calling Tracker.SetGeoDB.
	GeoDB *geodb.GeoDB

	// Logger is the log.Logger used for logging.
	// The default log will be used printing to os.Stdout with "pirsch" in its prefix in case it is not set.
	Logger *log.Logger
}

Config is the optional configuration for the Tracker.

type EventOptions

type EventOptions struct {
	// Name is the name of the event (required).
	Name string

	// Duration is an optional duration that is used to calculate an average time on the dashboard.
	Duration uint32

	// Meta are optional fields used to break down the events that were send for a name.
	Meta map[string]string
}

EventOptions are the options to save a new event. The name is required. All other fields are optional.

type HitOptions

type HitOptions struct {
	// Salt is used to generate a fingerprint (optional).
	// It can be different for every request.
	Salt string

	// SessionCache is the cache to look up sessions.
	SessionCache session.Cache

	// HeaderParser is an (optional) list of parsers to extract the real client IP from request headers.
	HeaderParser []ip.HeaderParser

	// AllowedProxySubnets is an (optional) list of subnets to trust when extracting the real client IP from request headers.
	AllowedProxySubnets []net.IPNet

	// ClientID is optionally saved with a hit to split the data between multiple clients.
	ClientID uint64

	// SessionMaxAge defines the maximum time a session stays active.
	// A session is kept active if requests are made within the time frame.
	// Set to 15 minutes by default.
	SessionMaxAge time.Duration

	// MinDelay defines the minimum time in milliseconds between two page views before the session is flagged as a bot request.
	// This will update the Session.IsBot counter, which can later be used to filter upon.
	// Set it to 0 to disable flagging bots.
	MinDelay int64

	// IsBotThreshold sets the threshold before a request is ignored.
	// If Session.IsBot is larger or equal to the configured value, the request won't be accepted.
	// Set it to 0 to disable ignoring requests.
	IsBotThreshold uint8

	// MaxPageViews defines the maximum number of page views a session might have.
	// Once the maximum is reached, the session will be flagged as a bot, which can later be used to filter upon.
	// Only when IsBotThreshold is set this will have an effect on whether the session is updated or not.
	// Set it to 0 to disable flagging bots.
	MaxPageViews uint16

	// URL can be set to manually overwrite the URL stored for this request.
	// This will also affect the Path, except it is set too.
	URL string

	// Path can be set to manually overwrite the path stored for the request.
	// This will also affect the URL.
	Path string

	// Title is the page title.
	Title string

	// Referrer can be set to manually overwrite the referrer from the request.
	Referrer string

	// ReferrerDomainBlacklist is used to filter out unwanted referrers from the Referrer header.
	// This can be used to filter out traffic from your own site or subdomains.
	// To filter your own domain and subdomains, add your domain to the list and set ReferrerDomainBlacklistIncludesSubdomains to true.
	// This way the referrer for blog.mypage.com -> mypage.com won't be saved.
	ReferrerDomainBlacklist []string

	// ReferrerDomainBlacklistIncludesSubdomains set to true to include all subdomains in the ReferrerDomainBlacklist,
	// or else subdomains must explicitly be included in the blacklist.
	// If the blacklist contains domain.com, sub.domain.com and domain.com will be treated as equals.
	ReferrerDomainBlacklistIncludesSubdomains bool

	// ScreenWidth sets the screen width to be stored with the hit.
	ScreenWidth uint16

	// ScreenHeight sets the screen height to be stored with the hit.
	ScreenHeight uint16
	// contains filtered or unexported fields
}

HitOptions is used to manipulate the data saved on a hit.

func HitOptionsFromRequest

func HitOptionsFromRequest(r *http.Request) *HitOptions

HitOptionsFromRequest returns the HitOptions for given client request. This function can be used to accept hits from pirsch.js. Invalid parameters are ignored and left empty. You might want to add additional checks before calling HitFromRequest afterwards (like for the HitOptions.ClientID).

type SessionState

type SessionState struct {
	// State is the new state for the session.
	State model.Session

	// Cancel is the state to cancel.
	// On session creation, this field is nil.
	Cancel *model.Session
}

SessionState is the state and cancellation for a session. The sessions must be inserted together to ensure sessions collapse.

func HitFromRequest

func HitFromRequest(r *http.Request, salt string, options *HitOptions) (*model.PageView, SessionState, *model.UserAgent)

HitFromRequest returns a new PageView and Session for given request, salt and HitOptions. The salt must stay consistent to track visitors across multiple calls. The easiest way to track visitors is to use the Tracker.

type Tracker

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

Tracker provides methods to track requests. Make sure you call Stop to make sure the hits get stored before shutting down the server.

func NewTracker

func NewTracker(client db.Store, salt string, config *Config) *Tracker

NewTracker creates a new tracker for given client, salt and config. Pass nil for the config to use the defaults. The salt is mandatory. It creates the same amount of workers for both, hits and events.

func (*Tracker) ClearSessionCache

func (tracker *Tracker) ClearSessionCache()

ClearSessionCache clears the session cache.

func (*Tracker) Event

func (tracker *Tracker) Event(r *http.Request, eventOptions EventOptions, options *HitOptions)

Event stores the given request as a new event. The event name in the options must be set, or otherwise the request will be ignored. The request might be ignored if it meets certain conditions. The HitOptions, if passed, will overwrite the Tracker configuration. It's save (and recommended!) to call this function in its own goroutine.

func (*Tracker) ExtendSession

func (tracker *Tracker) ExtendSession(r *http.Request, options *HitOptions)

ExtendSession looks up and extends the session for given request and client ID (optional). This function does not Store a hit or event in database.

func (*Tracker) Flush

func (tracker *Tracker) Flush()

Flush flushes all hits to client that are currently buffered by the workers. Call Tracker.Stop to also save hits that are in the queue.

func (*Tracker) Hit

func (tracker *Tracker) Hit(r *http.Request, options *HitOptions)

Hit stores the given request. The request might be ignored if it meets certain conditions. The HitOptions, if passed, will overwrite the Tracker configuration. It's safe (and recommended!) to call this function in its own goroutine.

func (*Tracker) SetGeoDB

func (tracker *Tracker) SetGeoDB(geoDB *geodb.GeoDB)

SetGeoDB sets the GeoDB for the Tracker. The call to this function is thread safe to enable live updates of the database. Pass nil to disable the feature.

func (*Tracker) Stop

func (tracker *Tracker) Stop()

Stop flushes and stops all workers.