Documentation
¶
Overview ¶
Package telemetry is donkey's small, purpose-built traffic telemetry backend. It accepts OTLP/HTTP metrics, keeps 30 days of bounded rollups and serves the reports used by the admin console.
Index ¶
- Constants
- Variables
- func AppToken(key []byte, space, app string) string
- func GatewayToken(key []byte) string
- func QueryToken(key []byte) string
- func Run(ctx context.Context, cfg *Config) error
- func RuntimeToken(key []byte) string
- func VisitorHashes(key []byte, space, app, subject string) (appHash, spaceHash string)
- func WebVisitor(key []byte, space, app, subject, address, userAgent string, day time.Time) string
- type AnalyticsDefinitions
- type AnalyticsDimension
- type AnalyticsFilter
- type AnalyticsLive
- type AnalyticsPoint
- type AnalyticsProperty
- type AnalyticsPropertyValue
- type AnalyticsReport
- type AnalyticsRow
- type AnalyticsTotals
- type AppUsage
- type BuildScope
- type BuildSummary
- type CallerBatch
- type CallerEvent
- type Client
- func (c *Client) Analytics(ctx context.Context, space, app string, selected TrafficRange, ...) (AnalyticsReport, error)
- func (c *Client) AnalyticsLive(ctx context.Context, space, app string) (AnalyticsLive, error)
- func (c *Client) Build(ctx context.Context, space, app string, sequence int64) (json.RawMessage, error)
- func (c *Client) BuildByImage(ctx context.Context, space, app, image string) (json.RawMessage, error)
- func (c *Client) BuildScopes(ctx context.Context) ([]BuildScope, error)
- func (c *Client) Builds(ctx context.Context, space, app string) ([]BuildSummary, error)
- func (c *Client) PurgeBuilds(ctx context.Context, space, app string) error
- func (c *Client) PurgeSpace(ctx context.Context, space string) error
- func (c *Client) Ready(ctx context.Context) error
- func (c *Client) RecordBuild(ctx context.Context, space, app, image string, ok bool, record json.RawMessage) (int64, error)
- func (c *Client) Resources(ctx context.Context, space, app string, selected ResourceRange) (ResourceReport, error)
- func (c *Client) Traffic(ctx context.Context, space, app, source string, selected TrafficRange) (TrafficReport, error)
- func (c *Client) Usage(ctx context.Context) (UsageReport, error)
- type Config
- type Definitions
- type MCPOperation
- type MCPReport
- type OperationTotals
- type ResourceCurrent
- type ResourceExporter
- type ResourceObservation
- type ResourcePoint
- type ResourceRange
- type ResourceReport
- type Service
- type Store
- func (s *Store) Analytics(ctx context.Context, space, app string, selected TrafficRange, ...) (AnalyticsReport, error)
- func (s *Store) AnalyticsLive(ctx context.Context, space, app string, now time.Time) (AnalyticsLive, error)
- func (s *Store) Build(ctx context.Context, space, app string, sequence int64) (string, error)
- func (s *Store) BuildByImage(ctx context.Context, space, app, image string) (string, error)
- func (s *Store) Builds(ctx context.Context, space, app string) ([]BuildSummary, error)
- func (s *Store) Cleanup(ctx context.Context, now time.Time) error
- func (s *Store) Close() error
- func (s *Store) IngestMetrics(ctx context.Context, req *metricsv1.ExportMetricsServiceRequest, ...) (accepted, rejected int64, err error)
- func (s *Store) IngestResourceMetrics(ctx context.Context, req *metricsv1.ExportMetricsServiceRequest) (accepted, rejected int64, err error)
- func (s *Store) InsertBuild(ctx context.Context, space, app, image string, ok bool, record string, ...) (int64, error)
- func (s *Store) InsertCallers(ctx context.Context, batch CallerBatch, now time.Time) (accepted, rejected int, err error)
- func (s *Store) InsertViews(ctx context.Context, batch ViewBatch, now time.Time) (accepted, rejected int, err error)
- func (s *Store) InsertWebEvents(ctx context.Context, batch WebBatch, now time.Time) (accepted, rejected int, err error)
- func (s *Store) PurgeBuilds(ctx context.Context, space, app string) error
- func (s *Store) PurgeSpace(ctx context.Context, space string) error
- func (s *Store) Ready(ctx context.Context) error
- func (s *Store) Resources(ctx context.Context, space, app string, selected ResourceRange, now time.Time) (ResourceReport, error)
- func (s *Store) Traffic(ctx context.Context, space, app, source string, selected TrafficRange, ...) (TrafficReport, error)
- func (s *Store) Usage(ctx context.Context, now time.Time) (UsageReport, error)
- type TrafficEndpoint
- type TrafficPoint
- type TrafficRange
- type TrafficReport
- type TrafficTotals
- type UsageReport
- type ViewBatch
- type ViewEvent
- type WebBatch
- type WebEvent
Constants ¶
const ( WebKindPageview = "pageview" WebKindEvent = "event" WebKindEngagement = "engagement" )
Web analytics is the client-side stream donkey-gateway collects from the script it adds to web apps' HTML pages: page views (including SPA route changes), custom events, and how long a page stayed visible. The gateway derives every dimension before export — browser, OS and device from the user agent, the country from the browser's time zone, the referrer's host from its URL — so this service never sees an IP address, a user agent or a query string. Visits are not stored; they are read out of the events.
const ( // HTTPServerRequestDuration is the stable OpenTelemetry HTTP server // duration metric. Counts come from the histogram's count, so one // instrument supplies request volume and latency without a second stream. HTTPServerRequestDuration = "http.server.request.duration" MCPServerOperationDuration = "mcp.server.operation.duration" // Runtime resource snapshots use only OpenTelemetry's container metrics. ContainerCPUUsage = "container.cpu.usage" ContainerMemoryWorkingSet = "container.memory.working_set" SourceEdge = "edge" SourceApp = "app" DefaultRetentionDays = 30 )
const TelemetryTokenHeader = "X-Donkey-Telemetry-Token"
TelemetryTokenHeader is deliberately separate from Authorization. It fits OTEL_EXPORTER_OTLP_HEADERS without putting the installation's session key, or a credential useful anywhere else, on the wire.
const UsageDays = 7
UsageDays is the window usage is measured over: a week shows an app's habits, where a day would show a launch or a quiet Sunday.
Variables ¶
var ErrNoBuild = errors.New("no matching build record")
ErrNoBuild reports that no matching build record is stored.
var HTTPDurationBounds = []float64{
0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25,
0.5, 0.75, 1, 2.5, 5, 7.5, 10,
}
HTTPDurationBounds are the explicit bucket boundaries recommended by the OpenTelemetry HTTP semantic conventions. Values and stored sums are seconds.
var MCPDurationBounds = []float64{0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300}
MCP conventions are Development. Keep these buckets separate from HTTP: tool execution regularly takes longer than an HTTP page or API response. Convention snapshot: semantic-conventions-genai 9ffc7e00c639be7712e544e3e54331e885dccf84, docs/gen-ai/mcp.md (reviewed 2026-10-24).
Functions ¶
func AppToken ¶
AppToken is valid for exactly one semantic-convention resource scope. An app can report its own in-process metrics, but cannot write another app's stream or the gateway-owned edge stream.
func GatewayToken ¶
func QueryToken ¶
func RuntimeToken ¶
RuntimeToken lets donkey-server submit resource snapshots for every app in its installation in one OTLP request. It is distinct from the gateway and app tokens, so none of those writers can forge runtime-owned measurements.
func VisitorHashes ¶
VisitorHashes deliberately use different domains. A query for a whole space can deduplicate one signed-in person across its apps, while app-level hashes cannot be joined across apps. Empty subjects remain anonymous.
func WebVisitor ¶
WebVisitor is the web analytics visitor: for a signed-in visitor a per-app hash of the subject, stable across days; for anyone else a per-app hash of the address and browser that changes with the UTC day, so it cannot follow a person from one day to the next or from one app to another. Nothing is stored on the visitor's device either way.
Types ¶
type AnalyticsDefinitions ¶
type AnalyticsDimension ¶
type AnalyticsDimension string
AnalyticsDimension names one breakdown and one filter. Path and event are page-level: filtering by them keeps the visits that contain the page or event, and narrows the pages or events table to it. Every other dimension describes a visit.
const ( DimPath AnalyticsDimension = "path" DimEntry AnalyticsDimension = "entry" DimExit AnalyticsDimension = "exit" DimReferrer AnalyticsDimension = "referrer" DimChannel AnalyticsDimension = "channel" DimUTMSource AnalyticsDimension = "utm_source" DimUTMMedium AnalyticsDimension = "utm_medium" DimUTMCampaign AnalyticsDimension = "utm_campaign" DimBrowser AnalyticsDimension = "browser" DimOS AnalyticsDimension = "os" DimDevice AnalyticsDimension = "device" DimCountry AnalyticsDimension = "country" DimLanguage AnalyticsDimension = "language" DimEvent AnalyticsDimension = "event" )
type AnalyticsFilter ¶
type AnalyticsFilter struct {
Dimension AnalyticsDimension `json:"dimension"`
Value string `json:"value"`
}
func ParseAnalyticsFilters ¶
func ParseAnalyticsFilters(values []string) ([]AnalyticsFilter, error)
ParseAnalyticsFilters reads repeated dimension:value query values.
type AnalyticsLive ¶
type AnalyticsLive struct {
Visitors int64 `json:"visitors"`
WindowMinutes int `json:"windowMinutes"`
Pages []AnalyticsRow `json:"pages"`
}
type AnalyticsPoint ¶
type AnalyticsProperty ¶
type AnalyticsProperty struct {
Key string `json:"key"`
Values []AnalyticsPropertyValue `json:"values"`
}
type AnalyticsPropertyValue ¶
type AnalyticsReport ¶
type AnalyticsReport struct {
Space string `json:"space"`
App string `json:"app"`
Range TrafficRange `json:"range"`
Granularity string `json:"granularity"`
From time.Time `json:"from"`
To time.Time `json:"to"`
Filters []AnalyticsFilter `json:"filters"`
Totals AnalyticsTotals `json:"totals"`
// Previous is the same-length window just before From, when it is still
// retained.
Previous *AnalyticsTotals `json:"previous,omitempty"`
Series []AnalyticsPoint `json:"series"`
Breakdowns map[AnalyticsDimension][]AnalyticsRow `json:"breakdowns"`
EventProperties []AnalyticsProperty `json:"eventProperties,omitempty"`
Definitions AnalyticsDefinitions `json:"definitions"`
}
type AnalyticsRow ¶
type AnalyticsRow struct {
Value string `json:"value"`
Visitors int64 `json:"visitors"`
Count int64 `json:"count"`
}
AnalyticsRow is one value of a breakdown. Count is page views for path, occurrences for event, and visits for every other dimension.
type AnalyticsTotals ¶
type AnalyticsTotals struct {
Visitors int64 `json:"visitors"`
Visits int64 `json:"visits"`
Pageviews int64 `json:"pageviews"`
Events int64 `json:"events"`
ViewsPerVisit float64 `json:"viewsPerVisit"`
BounceRate float64 `json:"bounceRate"`
VisitDurationSeconds float64 `json:"visitDurationSeconds"`
}
type AppUsage ¶
type AppUsage struct {
Space string `json:"space"`
App string `json:"app"`
People float64 `json:"people"`
}
AppUsage is one app's people on an average day of the window. A person is a signed-in caller where the app has any — behind the login, crawlers never are one — and otherwise a browser visitor of its web analytics, which drops bots and headless browsers. Anonymous visitors are counted once per day anyway (their hash changes with the day), so both kinds are counted per day and averaged, which keeps the two comparable.
type BuildScope ¶
type BuildSummary ¶
type BuildSummary struct {
Sequence int64 `json:"sequence"`
Created string `json:"created"`
Image string `json:"image,omitempty"`
OK bool `json:"ok"`
}
BuildSummary is one line of an app's build history.
type CallerBatch ¶
type CallerBatch struct {
Events []CallerEvent `json:"events"`
}
type CallerEvent ¶
type CallerEvent struct {
TimeUnixNano uint64 `json:"timeUnixNano"`
Space string `json:"space"`
App string `json:"app"`
UserHash string `json:"user.hash"`
SpaceUserHash string `json:"spaceUserHash"`
}
CallerEvent contains only gateway-derived HMACs of a verified identity. Anonymous requests do not get an identifier. Repeated events are harmless: the store retains one observation per caller, app and hour, not a request log.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
func (*Client) Analytics ¶
func (c *Client) Analytics(ctx context.Context, space, app string, selected TrafficRange, filters []AnalyticsFilter) (AnalyticsReport, error)
Analytics reads one app's web analytics report.
func (*Client) AnalyticsLive ¶
AnalyticsLive reads who is on one app right now.
func (*Client) Build ¶
func (c *Client) Build(ctx context.Context, space, app string, sequence int64) (json.RawMessage, error)
Build fetches one stored record by sequence; BuildByImage fetches the newest record for an exact image reference. Both return ErrNoBuild when nothing matches.
func (*Client) BuildByImage ¶
func (*Client) BuildScopes ¶
func (c *Client) BuildScopes(ctx context.Context) ([]BuildScope, error)
func (*Client) PurgeBuilds ¶
PurgeBuilds removes an app's build history.
func (*Client) RecordBuild ¶
func (c *Client) RecordBuild(ctx context.Context, space, app, image string, ok bool, record json.RawMessage) (int64, error)
RecordBuild appends one build record to an app's history and returns its sequence number.
func (*Client) Resources ¶
func (c *Client) Resources(ctx context.Context, space, app string, selected ResourceRange) (ResourceReport, error)
func (*Client) Traffic ¶
func (c *Client) Traffic(ctx context.Context, space, app, source string, selected TrafficRange) (TrafficReport, error)
type Config ¶
type Config struct {
OTLPListen string
APIListen string
DatabasePath string
RetentionDays int
Key []byte
}
func ConfigFromEnv ¶
type Definitions ¶
type Definitions struct {
Success string `json:"success"`
View string `json:"view"`
UniqueVisitors string `json:"uniqueVisitors"`
AuthenticatedCallers string `json:"authenticatedCallers"`
}
Definitions keeps dashboard words honest. In particular, a document load observed at the gateway is not every SPA route transition, and public anonymous visitors are intentionally not assigned a tracking cookie.
type MCPOperation ¶
type MCPOperation struct {
App string `json:"app"`
Method string `json:"method"`
Target string `json:"target"`
OperationTotals
}
type MCPReport ¶
type MCPReport struct {
Source string `json:"source"`
Totals OperationTotals `json:"totals"`
Operations []MCPOperation `json:"operations"`
}
MCP operations and HTTP transport requests are separate measurements. Both use the selected source, so legacy app metrics cannot double-count the gateway's automatic protocol observations.
type OperationTotals ¶
type ResourceCurrent ¶
type ResourceExporter ¶
type ResourceExporter struct {
// contains filtered or unexported fields
}
ResourceExporter is donkey-server's small OTLP/HTTP writer. It constructs the convention's Gauge and UpDownCounter data directly rather than starting a second OpenTelemetry SDK and periodic reader inside the control plane; the server already owns the sampling cadence.
func NewResourceExporter ¶
func NewResourceExporter(endpoint string, key []byte) *ResourceExporter
func (*ResourceExporter) Export ¶
func (e *ResourceExporter) Export(ctx context.Context, observations []ResourceObservation) error
type ResourceObservation ¶
type ResourceObservation struct {
Space string
App string
Instance string
ContainerID string
ContainerName string
KubeNamespace string
KubePodName string
KubePodUID string
SampledAt time.Time
CPUCores float64
CPUUserCores float64
CPUSystemCores float64
CPUModesAvailable bool
MemoryBytes int64
}
ResourceObservation is one container snapshot exported by donkey-server as OTLP after sampling Docker or Kubernetes. App totals are calculated only when reports are read, preserving the standard container entity boundary.
type ResourcePoint ¶
type ResourceRange ¶
type ResourceRange string
ResourceRange is separate from TrafficRange because recent CPU and memory snapshots have a finer retained resolution than HTTP traffic rollups.
const ( ResourceRange1Hour ResourceRange = "1h" ResourceRange4Hours ResourceRange = "4h" ResourceRange48Hours ResourceRange = "48h" ResourceRange7Days ResourceRange = "7d" ResourceRange30Days ResourceRange = "30d" DefaultResourceRange = ResourceRange4Hours )
func ParseResourceRange ¶
func ParseResourceRange(value string) (ResourceRange, error)
type ResourceReport ¶
type ResourceReport struct {
Space string `json:"space"`
App string `json:"app"`
Range ResourceRange `json:"range"`
Granularity string `json:"granularity"`
From time.Time `json:"from"`
To time.Time `json:"to"`
Available bool `json:"available"`
Current *ResourceCurrent `json:"current,omitempty"`
Series []ResourcePoint `json:"series"`
}
ResourceReport is retained CPU and memory usage for one app. Current is the most recent observation even when it is stale; Fresh tells the console whether it is recent enough to describe the app now.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
func (*Store) Analytics ¶
func (s *Store) Analytics(ctx context.Context, space, app string, selected TrafficRange, filters []AnalyticsFilter, now time.Time) (AnalyticsReport, error)
func (*Store) AnalyticsLive ¶
func (s *Store) AnalyticsLive(ctx context.Context, space, app string, now time.Time) (AnalyticsLive, error)
AnalyticsLive is who is on the app right now: visitors active in the last few minutes, and the page each of them is on.
func (*Store) BuildByImage ¶
BuildByImage returns the newest record that produced or released the given image reference — how a `--no-build --tag` redeploy recovers the decisions that tag was actually verified with.
func (*Store) IngestMetrics ¶
func (s *Store) IngestMetrics(ctx context.Context, req *metricsv1.ExportMetricsServiceRequest, trustedGateway bool) (accepted, rejected int64, err error)
IngestMetrics retains HTTP server and MCP server operation histograms and deliberately rejects unrelated instruments. This endpoint is an OTLP boundary for donkey's traffic analytics, not a general-purpose metrics warehouse.
func (*Store) IngestResourceMetrics ¶
func (s *Store) IngestResourceMetrics(ctx context.Context, req *metricsv1.ExportMetricsServiceRequest) (accepted, rejected int64, err error)
IngestResourceMetrics accepts only the gauges written with RuntimeToken. One ResourceMetrics message becomes one atomic container observation; app reports aggregate the fresh container identities after ingestion.
func (*Store) InsertBuild ¶
func (s *Store) InsertBuild(ctx context.Context, space, app, image string, ok bool, record string, now time.Time) (int64, error)
InsertBuild appends one record to the app's history and retires records beyond the retention window. It returns the record's sequence number.
func (*Store) InsertCallers ¶
func (*Store) InsertViews ¶
func (*Store) InsertWebEvents ¶
func (s *Store) InsertWebEvents(ctx context.Context, batch WebBatch, now time.Time) (accepted, rejected int, err error)
InsertWebEvents stores one gateway batch. Anything malformed is counted as rejected rather than failing the batch: the gateway already validated it, so a rejection here is a version skew worth seeing, not worth retrying.
func (*Store) PurgeBuilds ¶
PurgeBuilds removes an app's whole history. Removing an app takes its records with it, so a later app by the same name starts with its own.
func (*Store) PurgeSpace ¶
PurgeSpace atomically removes every retained metric and normalization baseline for a logical space. Reusing its name then starts with clean reports rather than mixing a new application with up to 30 days of history.
func (*Store) Resources ¶
func (s *Store) Resources(ctx context.Context, space, app string, selected ResourceRange, now time.Time) (ResourceReport, error)
type TrafficEndpoint ¶
type TrafficEndpoint struct {
App string `json:"app"`
Method string `json:"method"`
Route string `json:"route"`
TrafficTotals
}
type TrafficPoint ¶
type TrafficPoint struct {
AuthenticatedCallers int64 `json:"authenticatedCallers"`
Bucket string `json:"bucket"`
Requests int64 `json:"requests"`
Successful int64 `json:"successful"`
ClientErrors int64 `json:"clientErrors"`
ServerErrors int64 `json:"serverErrors"`
OtherResponses int64 `json:"otherResponses,omitempty"`
AverageLatencyMS float64 `json:"averageLatencyMs"`
P50LatencyMS float64 `json:"p50LatencyMs"`
P95LatencyMS float64 `json:"p95LatencyMs"`
Views int64 `json:"views"`
UniqueVisitors int64 `json:"uniqueVisitors"`
IdentifiedViews int64 `json:"identifiedViews"`
VisitorCoveragePC float64 `json:"visitorCoveragePercent"`
}
type TrafficRange ¶
type TrafficRange string
const ( Range48Hours TrafficRange = "48h" Range7Days TrafficRange = "7d" Range30Days TrafficRange = "30d" DefaultTrafficRange = Range30Days )
func ParseTrafficRange ¶
func ParseTrafficRange(value string) (TrafficRange, error)
type TrafficReport ¶
type TrafficReport struct {
Space string `json:"space"`
App string `json:"app,omitempty"`
Source string `json:"source"`
Range TrafficRange `json:"range"`
Granularity string `json:"granularity"`
From time.Time `json:"from"`
To time.Time `json:"to"`
Totals TrafficTotals `json:"totals"`
Series []TrafficPoint `json:"series"`
Definitions Definitions `json:"definitions"`
Endpoints []TrafficEndpoint `json:"endpoints"`
MCP MCPReport `json:"mcp"`
}
TrafficReport is one app or one whole space over a bounded UTC window. Edge and in-app telemetry are deliberately queried separately: adding them would count the same public request twice.
type TrafficTotals ¶
type TrafficTotals struct {
AuthenticatedCallers int64 `json:"authenticatedCallers"`
Requests int64 `json:"requests"`
Successful int64 `json:"successful"`
ClientErrors int64 `json:"clientErrors"`
ServerErrors int64 `json:"serverErrors"`
OtherResponses int64 `json:"otherResponses,omitempty"`
AverageLatencyMS float64 `json:"averageLatencyMs"`
P50LatencyMS float64 `json:"p50LatencyMs"`
P95LatencyMS float64 `json:"p95LatencyMs"`
Views int64 `json:"views"`
UniqueVisitors int64 `json:"uniqueVisitors"`
IdentifiedViews int64 `json:"identifiedViews"`
VisitorCoveragePC float64 `json:"visitorCoveragePercent"`
}
type UsageReport ¶
type UsageReport struct {
// Days is the window the counts cover: UsageDays, or the store's
// retention when that is shorter.
Days int `json:"days"`
Apps []AppUsage `json:"apps"`
}
UsageReport is how many people use each app, for every app at once, so the console can tell which apps are popular without a report per app.
type ViewEvent ¶
type ViewEvent struct {
TimeUnixNano uint64 `json:"timeUnixNano"`
Space string `json:"space"`
App string `json:"app"`
AppVisitorHash string `json:"appVisitorHash,omitempty"`
SpaceVisitorHash string `json:"spaceVisitorHash,omitempty"`
}
ViewEvent is the gateway's privacy-bounded document-navigation event. Hashes are HMACs made by the gateway; the subject, email, IP, user agent, path and query string never enter the telemetry service.
type WebEvent ¶
type WebEvent struct {
TimeUnixMilli int64 `json:"time"`
Space string `json:"space"`
App string `json:"app"`
Visitor string `json:"visitor"`
Kind string `json:"kind"`
Path string `json:"path"`
Name string `json:"name,omitempty"`
Referrer string `json:"referrer,omitempty"`
Channel string `json:"channel,omitempty"`
UTMSource string `json:"utmSource,omitempty"`
UTMMedium string `json:"utmMedium,omitempty"`
UTMCampaign string `json:"utmCampaign,omitempty"`
Browser string `json:"browser,omitempty"`
OS string `json:"os,omitempty"`
Device string `json:"device,omitempty"`
Country string `json:"country,omitempty"`
Language string `json:"language,omitempty"`
EngagedMS int64 `json:"engagedMs,omitempty"`
Props map[string]string `json:"props,omitempty"`
}
WebEvent is one page view, custom event or engagement ping. Visitor is a gateway-made HMAC: per app and per day for anonymous visitors, per app for signed-in ones.