analytics

README

togo-framework/analytics

App-internal product analytics for togo — event tracking, funnels, retention & dashboards.

Install

togo install togo-framework/analytics

A self-hosted, Mixpanel-lite analytics layer inside your togo app: track events, then query volume over time, top events/properties, funnels, retention cohorts, and active users (DAU/WAU) — over a Go API and REST. Ships with a tiny JS snippet to post events from the browser.

Track

import "github.com/togo-framework/analytics"

a, _ := analytics.FromKernel(k)
a.Track(ctx, analytics.Event{
	Name:       "order_completed",
	UserID:     "u_123",
	Properties: map[string]any{"plan": "pro", "amount": 49},
})
a.Identify("u_123", map[string]any{"country": "EG"})

Or POST batches to POST /api/analytics/events from the JS snippet.

Metrics

a.Volume("order_completed", from, to, analytics.Daily)            // time series
a.TopEvents(from, to, 10)                                         // most frequent events
a.TopProperties("order_completed", "plan", from, to, 10)          // value distribution
a.Funnel([]string{"visit", "signup", "order_completed"}, from, to) // ordered conversion
a.Retention(from, []int{0, 1, 7})                                 // cohort retention
a.ActiveUsers(from, to)                                           // distinct users (DAU/WAU)
a.DashboardSummary(7)                                             // overview snapshot

REST

Method	Path	Purpose
POST	/api/analytics/events	batch ingest {events:[…]}
POST	/api/analytics/identify	{user_id, traits}
GET	/api/analytics/volume	volume time series (event, bucket=day|hour, from, to)
GET	/api/analytics/top	top events, or top values of property
GET	/api/analytics/funnel	conversion (?step=a&step=b&…)
GET	/api/analytics/retention	cohort retention
GET	/api/analytics/active	active users
GET	/api/analytics/dashboard	overview

See docs/usage.md for the full API + the client snippet.

Configuration

No required env. The default event store is in-memory and bounded (great for dev + recent-window analytics). For durable history, implement the analytics.Store interface against your database (or stream events to a warehouse) and pass it to analytics.New(store).

---

Premium sponsors

ID8 Media  ·  One Studio

_{Support togo — become a sponsor.}

Documentation

Overview

Package analytics is an app-internal product-analytics plugin for togo — event tracking with volume, top-events, funnels, retention and active-user metrics (a Mixpanel-lite you self-host inside your togo app).

a, _ := analytics.FromKernel(k)
a.Track(ctx, analytics.Event{Name: "signup", UserID: "u1", Properties: map[string]any{"plan": "pro"}})
vol := a.Volume("signup", from, to, analytics.Daily)

Index

• type Bucket
• type Count
• type Dashboard
• type Event
• type FunnelStep
• type RetentionRow
• type Service
  • func FromKernel(k *togo.Kernel) (*Service, bool)
  • func New(store Store) *Service
  • func (s *Service) ActiveUsers(from, to time.Time) int
  • func (s *Service) DashboardSummary(days int) Dashboard
  • func (s *Service) Funnel(steps []string, from, to time.Time) []FunnelStep
  • func (s *Service) Identify(userID string, traits map[string]any)
  • func (s *Service) Retention(from time.Time, offsets []int) []RetentionRow
  • func (s *Service) TopEvents(from, to time.Time, limit int) []Count
  • func (s *Service) TopProperties(event, prop string, from, to time.Time, limit int) []Count
  • func (s *Service) Track(ctx context.Context, e Event)
  • func (s *Service) Traits(userID string) map[string]any
  • func (s *Service) Volume(name string, from, to time.Time, b Bucket) []VolumePoint
• type Store
• type VolumePoint

Types

type Bucket

type Bucket string

Bucket granularity for time-series volume.

const (
	Hourly Bucket = "hour"
	Daily  Bucket = "day"
)

type Count

type Count struct {
	Key   string `json:"key"`
	Count int    `json:"count"`
}

Count is a name/value with a count (top-events, top-properties).

type Dashboard

type Dashboard struct {
	TotalEvents int     `json:"total_events"`
	DAU         int     `json:"dau"`
	WAU         int     `json:"wau"`
	TopEvents   []Count `json:"top_events"`
}

Dashboard is a summary snapshot for an overview UI.

type Event

type Event struct {
	Name       string         `json:"name"`
	UserID     string         `json:"user_id,omitempty"`
	AnonID     string         `json:"anon_id,omitempty"`
	Properties map[string]any `json:"properties,omitempty"`
	Timestamp  time.Time      `json:"timestamp"`
}

Event is a tracked product event.

type FunnelStep

type FunnelStep struct {
	Event      string  `json:"event"`
	Count      int     `json:"count"`
	Conversion float64 `json:"conversion"` // fraction of step 0 that reached here
}

FunnelStep is one step's conversion in a funnel.

type RetentionRow

type RetentionRow struct {
	OffsetDays int `json:"offset_days"`
	Returned   int `json:"returned"`
}

RetentionRow is a cohort retention row (returning users at an offset).

type Service

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

Service is the analytics runtime stored on the kernel (k.Get("analytics")).

func FromKernel

func FromKernel(k *togo.Kernel) (*Service, bool)

FromKernel returns the analytics Service registered on the kernel.

func New

func New(store Store) *Service

New builds a standalone Service (handy for tests / a custom store).

func (*Service) ActiveUsers

func (s *Service) ActiveUsers(from, to time.Time) int

ActiveUsers counts distinct users active in [from,to).

func (*Service) DashboardSummary

func (s *Service) DashboardSummary(days int) Dashboard

Dashboard returns a summary over the last `days` days (default 7).

func (*Service) Funnel

func (s *Service) Funnel(steps []string, from, to time.Time) []FunnelStep

Funnel computes ordered conversion: of users who did step 0, how many went on to do each subsequent step (in order, by time) within [from,to).

func (*Service) Identify

func (s *Service) Identify(userID string, traits map[string]any)

Identify attaches traits to a user.

func (*Service) Retention

func (s *Service) Retention(from time.Time, offsets []int) []RetentionRow

Retention: of users first seen in [from,from+1d), how many returned on day offsets (0,1,7 by default) — simple activity-based retention.

func (*Service) TopEvents

func (s *Service) TopEvents(from, to time.Time, limit int) []Count

TopEvents ranks event names by volume.

func (*Service) TopProperties

func (s *Service) TopProperties(event, prop string, from, to time.Time, limit int) []Count

TopProperties ranks values of a property for a given event.

func (*Service) Track

func (s *Service) Track(ctx context.Context, e Event)

Track records an event (timestamp defaults to now).

func (*Service) Traits

func (s *Service) Traits(userID string) map[string]any

Traits returns a user's identified traits.

func (*Service) Volume

func (s *Service) Volume(name string, from, to time.Time, b Bucket) []VolumePoint

Volume returns the event count per time bucket for an event name ("" = all).

type Store

type Store interface {
	Append(Event)
	Range(from, to time.Time) []Event
}

Store is the pluggable event backend (in-memory default; DB-backed later).

type VolumePoint

type VolumePoint struct {
	Time  time.Time `json:"time"`
	Count int       `json:"count"`
}

VolumePoint is one time bucket of an event-volume series.