sitetraffic

package
v0.31.39 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 13, 2026 License: Apache-2.0 Imports: 36 Imported by: 0

Documentation

Overview

Package sitetraffic is the edge's request log and the traffic figure folded from it (epic memql#4906, the Run epic of the Deployables program), and the visit fields a deployable's website statistics are counted from (docs/superpowers/specs/2026-11-08-site-and-email-statistics-design.md).

The edge emitted no per-site metrics, so "is anybody using this deployable, and is it healthy" had no truthful answer. This package is both halves of the answer: a bounded writer that records one row per served request off the request path, and the read that answers a window from the continuous aggregate TimescaleDB folds those rows into.

What a row records about a visitor, and what it never does

A count of requests cannot answer what a client is promised about their website -- how many people, which pages, from where -- so every row also records whether it was a page view and whether a bot asked, and a page view alone records its path, its source, a country, a device, a browser, an operating system and a visitor id.

The visitor id is HMAC-SHA256 over (site, client address, user agent) under a random secret that exists for one UTC day (VisitorSecrets) and is deleted when the day ends (spec D1). It counts a day's distinct visitors without a cookie, the alternative the design rejected because it would need a consent banner on every client's site; keyed by site, it cannot join one visitor across two sites; and once the day's secret is gone, nothing stored can link an id back to an address. The price: a person visiting on three days counts three times in a weekly total.

What is still never stored: the IP address and the user agent. The edge derives the fields above from them and drops both before a Record exists, so they never reach this package, its table or its logs. Neither does a query string, a fragment or a referring URL: a path is normalized, and a source is a utm_source or a referring host. A stored row answers "how many people, on which pages, from where, on what", and never "who".

It lives in component/, not integrations/

For component/packages' reason: an integration is an outbound call to somebody else's system, and this calls nobody. It writes to the cluster's own database and reads the cluster's own aggregate, which is the relationship `database` has to Postgres rather than the one `shopify` has to Shopify. module_taxonomy_test.go records the verdict.

One write, folded by the database

The figure is a continuous aggregate over the rows, never a counter something increments, so the raw log and the figure cannot disagree. That is what makes a spike in errors followable: the number on the page and the lines behind it are the same evidence at two resolutions.

An absent figure and a zero are different answers

A window nothing measured returns NO ROW, and a window with requests and no errors returns a row whose errorCount is 0. The reader never invents a zero (the campaignStats rule), because "nobody visited" and "we were not recording" send a person to two different places.

Which connection each part runs on

Everything but the rollup -- the edge's writer, its visitor secret and country loaders, the country refresh and both reads -- runs on the request pool and inside its limit: a server statement_timeout (8 s by default) set below pgdriver's 10 s client read deadline, so a slow statement is cancelled by the server, not abandoned by the client and left running. Nothing here raises that limit, which would only move the cut to the client (statisticsTx). The five-minute rollup, whose statements can rightly run longer, runs on the dedicated maintenance session instead, with limits of its own (rollup.go, "Where the statements run").

Index

Constants

View Source
const (
	Bucket1m = "1m"
	Bucket1h = "1h"
)

Bucket names the aggregate a read comes from.

View Source
const (
	// PathClassAsset is a file served from the bundle that is not an HTML
	// document -- the immutable, content-addressed majority.
	PathClassAsset = "asset"
	// PathClassDocument is an HTML document that existed in the bundle: the
	// root index.html, a directory index, or a prerendered <path>.html.
	PathClassDocument = "document"
	// PathClassFallback is index.html served because nothing matched -- the
	// spa tail of the resolution order.
	PathClassFallback = "fallback"
	// PathClassProxy is a request forwarded to the bff (/_memql/*) or to the
	// identity service (the four same-origin JSON paths).
	PathClassProxy = "proxy"
	// PathClassConfig is GET /runtime-config.json, the document every live
	// site answers with its own identity discovery and runtime settings.
	PathClassConfig = "config"
	// PathClassUnserved is a request the site did not serve: a draft,
	// disabled or archived deployable, or a path that matched nothing on a
	// static site. It is a class of its own rather than folded into
	// `document`, because "this deployable answered nothing" is the state
	// somebody reading the figure is trying to distinguish.
	PathClassUnserved = "unserved"
	// PathClassView is a page-change ping from a single-page app's view
	// script, which the edge answers itself. An accepted ping is a page
	// view; a refused one is still a request the edge answered, so it is
	// recorded either way and counts for health like every other class.
	PathClassView = "view"
)

The path classes: what the edge did, not what was asked for.

"Did" rather than "asked" is the useful reading, and Fallback is why. The SPA fallback firing is the fact that tells somebody whether prerendering is working -- a site whose every page request lands on Fallback is one where the build emitted no routes, which looks identical from the request side.

View Source
const ComponentName = common.ComponentName("sitetraffic.sink")

ComponentName is the bus-side name.

View Source
const CountriesComponentName = common.ComponentName("sitetraffic.countries")

CountriesComponentName is the bus-side name of the country database loader.

View Source
const (
	// DefaultRetentionDays matches the migration's own policies and the log
	// store's thirty days.
	DefaultRetentionDays = 30
)

Retention bounds.

View Source
const VisitorsComponentName = common.ComponentName("sitetraffic.visitors")

VisitorsComponentName is the bus-side name of the visitor-secret keeper.

Variables

PathClasses is the closed set, for a caller that wants to validate one. Appended to, never reordered: the edge's own list is compared to this one index by index.

Functions

func ApplyRetention

func ApplyRetention(ctx context.Context, db *bun.DB, days int) error

ApplyRetention points the three TimescaleDB retention policies at the configured window -- the raw rows and both aggregates, in step, so "unmeasured" means the same thing at every horizon.

A no-op without TimescaleDB: a plain Postgres box has no policies to move, and the views the migration created there are computed live from rows nothing drops. That is a real difference and it is the developer box's, which is why it is a log line rather than a refusal.

func RequestLogEnabled

func RequestLogEnabled() bool

RequestLogEnabled reads MEMQL_EDGE_REQUEST_LOG_ENABLED. ON BY DEFAULT: a deployable's Statistics and its row in the Deployables list ask "is anybody using it", and a cluster where nobody had opted in would answer unmeasured forever with nothing to say why.

func RetentionDays

func RetentionDays() int

RetentionDays reads MEMQL_EDGE_REQUEST_LOG_RETENTION_DAYS, clamped. An unparseable value takes the default rather than zero, which would ask the database to drop everything the moment it was written.

Types

type CountryLoader added in v0.31.28

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

CountryLoader holds the current country database (an MMDB kept in edge_geo_country) as an in-memory reader.

Country is an atomic load plus an in-memory lookup, so it is safe on the request path. The database is read only at Start and on an hourly check of the stored release label (cheap: the blob is fetched only when the label changed), so a monthly refresh reaches every replica without a restart; a check that fails is tried again sooner, from thirty seconds doubling back up to the hour (retry.go). No row or an unreadable one means no country, never a failed request.

func NewCountryLoader added in v0.31.28

func NewCountryLoader(logger *slog.Logger, provider func() *bun.DB) *CountryLoader

func (*CountryLoader) ComponentName added in v0.31.28

func (c *CountryLoader) ComponentName() common.ComponentName

func (*CountryLoader) Country added in v0.31.28

func (c *CountryLoader) Country(addr netip.Addr) string

Country returns the ISO 3166 alpha-2 code for addr, or "" when no database is loaded or the address is not in it.

func (*CountryLoader) IsRunning added in v0.31.28

func (c *CountryLoader) IsRunning() bool

func (*CountryLoader) Order added in v0.31.28

func (c *CountryLoader) Order() int

func (*CountryLoader) Ready added in v0.31.28

func (c *CountryLoader) Ready() <-chan struct{}

func (*CountryLoader) Start added in v0.31.28

func (c *CountryLoader) Start(ctx context.Context)

func (*CountryLoader) Stop added in v0.31.28

func (c *CountryLoader) Stop(ctx context.Context)

type CountryRefreshReport added in v0.31.28

type CountryRefreshReport struct {
	Release    string `json:"release"`
	Downloaded bool   `json:"downloaded"`
	Reason     string `json:"reason,omitempty"`
}

CountryRefreshReport is what one refresh did. Reason says why nothing was downloaded (the stored release is current) and is empty after a download.

type Engine

type Engine interface {
	Execute(ctx context.Context, query string) (*memql.ExecuteResult, error)
}

Engine is the narrow engine surface the reader needs: one method, the same seam every other Go component in this tree uses to ask a named query.

type Integration

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

Integration exposes the two reads, the rollup and the country refresh.

func NewIntegration

func NewIntegration(engine Engine, bunDB func() *bun.DB, maintenance MaintenanceSession, logger *slog.Logger) *Integration

NewIntegration wires the handles. The db getter and the session opener are resolved lazily at call time, not at construction: a node's database handle is not necessarily up when plug-ins are materialized.

func (*Integration) Capabilities

func (i *Integration) Capabilities() []memql.IntegrationCapability

Capabilities implements memql.IntegrationProvider.

func (*Integration) IntegrationName

func (i *Integration) IntegrationName() string

IntegrationName implements memql.IntegrationProvider.

type MaintenanceSession added in v0.31.28

type MaintenanceSession func(ctx context.Context) (*sql.Conn, func(), error)

MaintenanceSession opens the dedicated session a run's statements run on: memql.PluginContext.OpenMaintenanceSession, which component/database's maintenance_session.go provides. The run closes it with the func it answers.

type Point added in v0.31.28

type Point struct {
	At                                                               time.Time
	Visitors, Visits, Bounces, PageViews, Requests, Errors, NotFound *int64
	P95Ms                                                            *float64
}

Point is one bucket of a series, starting At.

type Query

type Query struct {
	// SiteIds are BARE site ids -- the client contract at every wire seam,
	// and what the edge stamped on the rows.
	SiteIds []string
	// Bucket is Bucket1m or Bucket1h.
	Bucket string
	// WindowStart is inclusive, WindowEnd exclusive. The caller aligns them
	// to the bucket; a half-open window is what makes two adjacent windows
	// add up rather than double-count their shared edge.
	WindowStart time.Time
	WindowEnd   time.Time
	// Summary folds the whole window into one row per deployable instead of
	// one row per bucket -- what a list row needs to say "last served" for
	// twenty deployables without pulling twenty series.
	Summary bool
}

Query is one read.

type Reader

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

Reader answers a Query, gated by what the caller may read.

func NewReader

func NewReader(db *bun.DB, engine Engine) *Reader

NewReader wires the two handles. Either may be nil, and a read then refuses with a sentence naming what is missing rather than panicking -- a node without a database is a real deployment, not a bug.

func (*Reader) Read

func (r *Reader) Read(ctx context.Context, q Query) ([]Reading, error)

Read answers the query for the sites the caller may read.

func (*Reader) Statistics added in v0.31.28

func (r *Reader) Statistics(ctx context.Context, q StatisticsQuery) (Statistics, error)

Statistics answers the query for the deployables the caller may read.

type Reading

type Reading struct {
	SiteId           string
	Bucket           string
	WindowStart      time.Time
	WindowEnd        time.Time
	RequestCount     int64
	ErrorCount       int64
	ClientErrorCount int64
	BytesTotal       int64
	LastServedAt     time.Time
}

Reading is one answer: a bucket of one deployable's traffic, or -- in summary mode -- one deployable's whole window folded into a single row.

windowEnd - windowStart says which: a bucket's span is the bucket size, and a summary's span is the window the caller asked for. That is the codeMetric convention, where a consumer reads the bucket size off the difference rather than off a second field.

type Record

type Record struct {
	// SiteId is the BARE id of the v1:platform:site the request resolved to
	// (component/edge bare-ifies on projection, and the client contract is
	// bare ids at every wire seam). The reader compares the caller's bare ids
	// against this column directly, so the two spellings must not diverge.
	SiteId string
	// Node is MEMQL_NODE_ID -- which edge replica served it. Kept because a
	// figure that differs per replica is the first thing anyone asks about
	// when one replica is misconfigured; nothing reads it yet.
	Node string
	// ServedAt is when the response finished, in UTC.
	ServedAt time.Time
	// Status is the HTTP status the edge answered with.
	Status int
	// PathClass is what the edge DID with the request -- one of the constants
	// below.
	PathClass string
	// Bytes is the response body size in bytes, as counted through the
	// wrapped writer. Zero for a hijacked connection (a WebSocket upgrade
	// through the API proxy), where the bytes leave through the raw
	// connection and the wrapper never sees them; that undercount is
	// deliberate and named rather than guessed at.
	Bytes int64
	// DurationNs is how long the handler took, in nanoseconds.
	DurationNs int64

	// Measured is true on every row the edge writes since the visit fields
	// exist. Rows recorded before them read false from the column default,
	// and that difference is the whole point: it lets a statistic say "not
	// measured" for those days rather than "nobody visited", while the rows
	// keep counting for health.
	Measured bool
	// PageView is a person opening a page: a browser navigation (spec D2) or
	// an accepted page-change ping from a single-page app. Never true for a
	// bot, nor for a request the edge served under a preview grant (an
	// operator testing a candidate version, not a visitor).
	PageView bool
	// Bot is true when the user agent was empty or named automation. Set on
	// every row, page view or not, so bot requests count under health and
	// stay out of visitors and page views.
	Bot bool

	// Path is the page's path with no query string or fragment, a trailing
	// slash removed except at the root, at most 256 bytes.
	Path string
	// Source is where a navigation arrived from: its utm_source, else the
	// referring host, else "direct". Empty for a navigation inside the site
	// and for every ping, so the Sources list counts arrivals.
	Source string
	// Country is an ISO 3166-1 alpha-2 code from the country database, empty
	// when none is loaded or the address is not in it.
	Country string
	// Device, Browser and OS are members of closed sets (desktop / mobile /
	// tablet; Chrome, Safari, ...; Windows, macOS, ...), so a statistic groups
	// on them without cleaning.
	Device  string
	Browser string
	OS      string
	// Visitor is the day's visitor id, 32 lowercase hex characters. Empty
	// whenever the edge held no secret for the request's UTC day: visitors
	// then read low rather than being linked across days.
	Visitor string
}

Record is one served request, as the edge saw it: its outcome, which every row carries, and the visit fields derived from it, which a page view alone fills (see the package comment for why they exist).

It still carries no IP address and no user agent, and that remains a decision rather than an omission. The edge reads both on the serving path, derives every field below from them and drops them before building a Record, so nothing this package writes can hold them: a table with raw addresses in it would be one an operator has to reason about under data-protection law just to run a dashboard. What it carries instead is derived: members of closed sets, a host or utm_source, a normalized path and a day's keyed hash.

type Recorder

type Recorder interface {
	// Record files one served request. MUST NOT BLOCK: it is called from the
	// serving path, and an observability write that can wait on Postgres is a
	// head-of-line latency hazard for every visitor of every site.
	Record(r Record)
}

Recorder is the one method the edge needs. The edge declares its own identical interface rather than importing this package, so the dependency runs one way: the app bootstrap builds a sink here and hands it over.

type RollupReport added in v0.31.28

type RollupReport struct {
	// Hours is how many hour periods were published: for every published
	// day, its hours from the first one the hourly table still keeps through
	// the one under way.
	Hours int `json:"hours"`
	// Days is how many UTC days were published, today among them.
	Days int `json:"days"`
	// Backfilled is true when the run read a day before yesterday: every
	// logged day on the first run, or the days an outage or a failure left
	// without a finalization record.
	Backfilled bool `json:"backfilled"`
	// Deleted is how many statistics rows retention removed -- hourly, daily
	// and top rows. The finalization records and the state it removes are
	// not counted.
	Deleted int64 `json:"deleted"`
}

RollupReport says what one run of the rollup did.

func Rollup added in v0.31.28

func Rollup(ctx context.Context, open MaintenanceSession, now time.Time) (RollupReport, error)

Rollup brings the statistics tables up to date with edge_request as of now.

It reads today -- after yesterday, while yesterday is open -- then every day from the oldest one still in the request log through yesterday that is not yet final, newest first. Each day's settled fold is carried to the horizon, window by window; a day whose fold reaches its end is published final, and a day still open to late requests is published with its tail. Today's publication also writes the 24-hour window's top lists. Then it deletes the rows past retention, and folds each month whose final days changed into its monthly top lists.

Every transaction is its own: a day that fails costs only that day -- it is not recorded final, so the next run carries it on from its progress -- and this run carries on with every other open day. Each failed day is a *dayFailure in the returned error, joined with any other failure, so the caller can log each by name.

Every statement runs on a session that open opens, and on nothing else (see "Where the statements run" above); with no open at all, the run refuses.

type Row

type Row struct {
	bun.BaseModel `bun:"table:edge_request,alias:er"`

	ServedAt   time.Time `bun:"served_at,notnull"`
	Id         string    `bun:"id,notnull"`
	SiteId     string    `bun:"site_id,notnull"`
	Node       string    `bun:"node"`
	Status     int       `bun:"status,notnull"`
	PathClass  string    `bun:"path_class,notnull"`
	Bytes      int64     `bun:"bytes"`
	DurationNs int64     `bun:"duration_ns"`

	// The visit columns. Each has a constant default in the table, so an
	// insert that names none of them -- a previous release's edge during a
	// rolling upgrade -- still lands, and reads back unmeasured.
	Measured bool   `bun:"measured,notnull"`
	PageView bool   `bun:"page_view,notnull"`
	Bot      bool   `bun:"bot,notnull"`
	Path     string `bun:"path,notnull"`
	Source   string `bun:"source,notnull"`
	Country  string `bun:"country,notnull"`
	Device   string `bun:"device,notnull"`
	Browser  string `bun:"browser,notnull"`
	OS       string `bun:"os,notnull"`
	Visitor  string `bun:"visitor,notnull"`
}

Row mirrors the edge_request schema in migrations/20260903020000_edge_request_hypertable.up.sql, plus the visit columns of migrations/20261108090100_edge_request_visit_fields.up.sql. Exported so a test can supply its own Insert and assert on what would have been written; the bun tags stay inside this package.

type Sink

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

Sink batches Records into the edge_request hypertable.

The shape is component/observe.TimescaleSink's, and the reasoning is the same one that file states: the writer is INTENTIONALLY LOSSY under sustained pressure. When the buffer is full a record is dropped and counted, because the alternative -- blocking the serving path -- turns measurement into the thing that makes a site slow. A dropped record makes the figure low; a blocked write makes the site late, and only one of those is visible to a visitor.

It differs from the observe sink in two ways that matter here:

  • Drops are on a Prometheus counter, not only on an internal number. The figure this feeds is read as evidence, so "the figure is low because we dropped records" has to be answerable from outside the process. The observe sink's counters are readable by tests and by nothing else.
  • A flush failure is counted as dropped rows rather than only as an error, for the same reason: what a reader of the figure needs to know is how many requests are missing from it. And a refused batch is retried one row at a time first (writeRowByRow), so the rows missing are only the ones the database refused, not every request that shared their batch.

func NewSink

func NewSink(db *bun.DB, opts SinkOptions) *Sink

NewSink constructs the writer. It does not start the drain; call Start.

func (*Sink) Record

func (s *Sink) Record(r Record)

Record implements Recorder. NON-BLOCKING: a full buffer drops the record and advances the counter, so the serving path's cost is one channel send whether the database is healthy, slow or gone.

func (*Sink) Start

func (s *Sink) Start()

Start begins the background drain. Safe to call more than once.

func (*Sink) Stats

func (s *Sink) Stats() (written, dropped uint64)

Stats returns what the sink has written and dropped, for tests and for the boot log line.

func (*Sink) Stop

func (s *Sink) Stop(ctx context.Context) error

Stop drains what is queued and exits. Blocks until the loop finishes or ctx is cancelled. Idempotent.

type SinkComponent

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

SinkComponent is the writer's lifecycle: it resolves the database handle after the database component has started, builds the Sink, applies the configured retention window, and flushes what is queued on shutdown.

Wired only into an EDGE node (app/transport_edge.go), because the edge is the only node type that serves a site. The read half is a plug-in and registers everywhere; only the write half is node-specific.

A missing database is a WARNING, not a fatal: an edge with no handle still serves every site it was serving, and the honest consequence is that the traffic figure reads unmeasured. Refusing to boot over a metric would take a cluster's sites down to protect a number.

func NewSinkComponent

func NewSinkComponent(logger *slog.Logger, provider func() *bun.DB, order int) *SinkComponent

NewSinkComponent constructs the lifecycle wrapper. order should be later than the database component's; 0 takes 50, the observe sink's number and well past the standard startup phases.

func (*SinkComponent) ComponentName

func (c *SinkComponent) ComponentName() common.ComponentName

func (*SinkComponent) IsRunning

func (c *SinkComponent) IsRunning() bool

func (*SinkComponent) Order

func (c *SinkComponent) Order() int

func (*SinkComponent) Ready

func (c *SinkComponent) Ready() <-chan struct{}

func (*SinkComponent) Record

func (c *SinkComponent) Record(r Record)

Record implements Recorder by forwarding to the sink once there is one.

THE COMPONENT IS THE RECORDER, not the sink it builds, and the reason is startup order: the handler is constructed before the database component has started, so a caller handed `c.sink` would be handed nil and keep it. A record arriving before Start -- or on a replica where the log is switched off, or where no database resolved -- is dropped here, silently and cheaply, which is the same answer the sink's full-buffer branch gives.

Not counted as a drop: nothing was measuring yet, and a counter that climbed during every boot would put a permanent floor under the one series an operator is meant to alert on.

func (*SinkComponent) Start

func (c *SinkComponent) Start(ctx context.Context)

func (*SinkComponent) Stop

func (c *SinkComponent) Stop(ctx context.Context)

type SinkOptions

type SinkOptions struct {
	// BufferSize is how many records may be waiting for a flush. Default 4096.
	BufferSize int
	// FlushInterval is how often a partial batch is written. Default 1s.
	FlushInterval time.Duration
	// MaxBatch is the largest single insert. Default 256.
	MaxBatch int
	// Node is MEMQL_NODE_ID, stamped on every row. Resolved once by the
	// caller so the serving path never reads the environment.
	Node string
	// Logger is where a flush failure is reported. Defaults to slog.Default.
	Logger *slog.Logger
	// Insert replaces the bun insert, for tests. Nil means the real one.
	Insert func(ctx context.Context, rows []Row) error
}

SinkOptions configures the writer. Zero values take the defaults, which are the Logs store's numbers (its design's L5) for the same reason it chose them: a queue deep enough to ride out a flush, a batch big enough that one insert is worth making, and a flush interval short enough that a figure is never more than a second behind the traffic it describes.

type SiteTotals added in v0.31.28

type SiteTotals struct {
	SiteId                      string
	Visitors, Visits, PageViews *int64
}

SiteTotals is one deployable's own figures over the period.

type Statistics added in v0.31.28

type Statistics struct {
	Period statsperiod.Period
	// Bucket is statsperiod's: hour, day or month.
	Bucket string
	// Start and End are the period; PrevStart and PrevEnd the one before it,
	// zero when HasPrevious is false.
	Start, End, PrevStart, PrevEnd time.Time
	HasPrevious                    bool
	// MeasuredSince is the first day any of the deployables has visitor
	// figures, nil when none has: where the page says visitor counting began.
	MeasuredSince *time.Time
	Totals        Totals
	// Previous is the previous period's figures, every one nil without one.
	Previous Totals
	// Series has one point per bucket, oldest first, and PreviousSeries the
	// previous period's, aligned by offset; nil without a previous period.
	Series, PreviousSeries []Point
	// Top holds a list per dimension (topDimensions), each the
	// topEntriesKept leading values and an (other) remainder last.
	Top map[string][]TopEntry
	// Sites holds each deployable with any row in the period, most visitors
	// first.
	Sites []SiteTotals
}

Statistics is one read's answer.

func (Statistics) Payload added in v0.31.28

func (s Statistics) Payload() map[string]any

Payload is the answer as the node carries it, which the OS parses (parseSiteStatistics): lowerCamel keys, instants in RFC3339, measuredSince as YYYY-MM-DD, and every figure nothing measured PRESENT AND NULL, so a client can tell "not measured" from a key it does not know. Without a previous period, previous, previousSeries, prevStart and prevEnd are null.

func (Statistics) WithoutHealth added in v0.31.31

func (s Statistics) WithoutHealth() Statistics

WithoutHealth is the answer for a caller who does not hold the health part (execute app:deployables/health): every Health figure nil -- requests, errors, not found, bytes, bot requests and response times, in the totals and in both series -- which the payload spells null, as it spells any unmeasured figure. The visitor figures are untouched. handleStatistics applies it.

type StatisticsQuery added in v0.31.28

type StatisticsQuery struct {
	// SiteIds names the deployables, as bare ids, at most maxSitesPerRead.
	// Empty means every deployable the caller may read. A list that is not
	// empty is named even when none of its ids is usable: blank ids name no
	// deployable, and the answer is empty.
	SiteIds []string
	// AccountIds keeps a read that names no deployables to these
	// organizations, as bare ids. It narrows what the caller may read and
	// never widens it, and it is not consulted when SiteIds names the
	// deployables: the names are already narrower than any organization. As
	// with SiteIds, a list of blank ids names no organization and keeps none.
	AccountIds []string
	// Period is one of statsperiod's.
	Period statsperiod.Period
	// Now is the instant the period is counted back from; zero is time.Now.
	Now time.Time
}

StatisticsQuery is one statistics read.

type TopEntry added in v0.31.28

type TopEntry struct {
	Value                       string
	Visitors, Visits, PageViews int64
}

TopEntry is one value of a top list, summed over the period.

type Totals added in v0.31.28

type Totals struct {
	Visitors, Visits, Bounces, PageViews, Requests, Errors, NotFound, Bytes, BotRequests *int64
	// ViewsPerVisit is PageViews / Visits and BounceRate is Bounces / Visits,
	// worked out from the period's sums rather than averaged from its
	// buckets; both nil without a visit.
	ViewsPerVisit, BounceRate *float64
	// MedianMs and P95Ms are merged from the period's response-time
	// histograms (histogram.go); nil when nothing was served.
	MedianMs, P95Ms *float64
}

Totals are a period's figures; nil is "not measured".

type VisitorSecrets added in v0.31.28

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

VisitorSecrets keeps the day's visitor secret on an edge replica.

Every replica reads the SAME row (insert-if-absent, then select), so two replicas hash one visitor identically; that is what makes the daily unique-visitor count agree across a cluster.

The request path only does an atomic load. All database work happens in Start, at each UTC midnight and on an hourly safety check -- sooner after a check that failed (retry.go) -- so a slow or absent database can never delay a response.

FAIL CLOSED: a keeper that cannot read today's secret yields no visitor. It never falls back to an older secret, which would link a person across days and outlive the deletion that is the privacy promise.

func NewVisitorSecrets added in v0.31.28

func NewVisitorSecrets(logger *slog.Logger, provider func() *bun.DB, now func() time.Time) *VisitorSecrets

NewVisitorSecrets constructs the keeper. now is injectable for tests.

func (*VisitorSecrets) ComponentName added in v0.31.28

func (v *VisitorSecrets) ComponentName() common.ComponentName

func (*VisitorSecrets) IsRunning added in v0.31.28

func (v *VisitorSecrets) IsRunning() bool

func (*VisitorSecrets) Order added in v0.31.28

func (v *VisitorSecrets) Order() int

func (*VisitorSecrets) Ready added in v0.31.28

func (v *VisitorSecrets) Ready() <-chan struct{}

func (*VisitorSecrets) Start added in v0.31.28

func (v *VisitorSecrets) Start(ctx context.Context)

func (*VisitorSecrets) Stop added in v0.31.28

func (v *VisitorSecrets) Stop(ctx context.Context)

func (*VisitorSecrets) Visitor added in v0.31.28

func (v *VisitorSecrets) Visitor(siteID, addressKey, userAgent string, at time.Time) string

Visitor returns the visitor id for a request at time at, or "" when the held secret is not that UTC day's (none held, rotation pending or failed).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址