analytics

package
v0.20.0 Latest Latest
Warning

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

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

Documentation

Index

Constants

View Source
const (
	VisibilityAggregate = "aggregate"
	VisibilityPerson    = "person"
)

Member visibility of per-person activation data.

View Source
const MinGroup = 5

MinGroup is the smallest group a member sees in an aggregate. A smaller one could point at one person.

Variables

This section is empty.

Functions

func RegisterRoutes

func RegisterRoutes(api huma.API, store *Store, opts Options)

RegisterRoutes wires up all analytics-related HTTP endpoints onto the provided Huma API.

Types

type ActivationSummary

type ActivationSummary struct {
	TotalCount    int            `json:"total_count"`
	UniqueDevs    int            `json:"unique_devs"`
	LastTriggered *time.Time     `json:"last_triggered"`
	ByAgent       map[string]int `json:"by_agent"`
	BySource      map[string]int `json:"by_source"`

	// HookActivations and AutomatedActivations split TotalCount by who observed
	// the activation: a hook on a developer machine or a consumer's report.
	HookActivations      int            `json:"hook_activations"`
	AutomatedActivations int            `json:"automated_activations"`
	ByConsumer           map[string]int `json:"by_consumer"`
}

ActivationSummary summarises activations for a specific skill over a time window.

type AgentDailyCount

type AgentDailyCount struct {
	Date   string         `json:"date"`
	Agents map[string]int `json:"-"`
}

AgentDailyCount holds per-agent activation counts for a single day.

func (AgentDailyCount) MarshalJSON

func (a AgentDailyCount) MarshalJSON() ([]byte, error)

MarshalJSON produces a flat object: {"date":"2026-05-20","claude-code":5,"cursor":2}

type AnalyticsConsumersBody added in v0.16.0

type AnalyticsConsumersBody struct {
	Consumers []string `json:"consumers"`
	Roles     []string `json:"roles"`
}

AnalyticsConsumersBody lists the values the consumer and role filters accept.

type Breakdown added in v0.19.0

type Breakdown struct {
	Days             int            `json:"days"`
	Visibility       string         `json:"visibility"`
	IdentityRecorded bool           `json:"identity_recorded"`
	ByModel          []BreakdownRow `json:"by_model"`
	ByHarness        []BreakdownRow `json:"by_harness"`
	// ByPerson is set for an admin, and for a member when visibility is person.
	ByPerson []BreakdownRow `json:"by_person"`
	// Mine is the caller's own activations.
	Mine int `json:"mine"`
	// Hidden counts the groups below MinGroup left out for a member.
	Hidden int `json:"hidden"`
}

Breakdown is who used skills, on which model and harness, over a window.

type BreakdownRow added in v0.19.0

type BreakdownRow struct {
	Key         string `json:"key"`
	Label       string `json:"label"`
	Activations int    `json:"activations"`
	People      int    `json:"people"`
}

BreakdownRow is one model, harness or person.

type DailyCount

type DailyCount struct {
	Date  string `json:"date"`
	Count int    `json:"count"`
}

DailyCount holds the activation count for a single day.

type Event

type Event struct {
	SkillName     string `json:"skill_name"`
	Agent         string `json:"agent"`
	TriggerType   string `json:"trigger_type"`
	ProjectHash   string `json:"project_hash"`
	DeveloperHash string `json:"developer_hash"`

	// EventSource records how the activation was observed. "tool_invocation" is
	// an agent reporting an explicit skill call; "transcript_scan" is a hook
	// deriving activations by reading a session transcript afterwards. The two
	// are not the same measurement and must never be summed unlabelled.
	EventSource string `json:"event_source"`

	// UserID is the person whose key sent the event, empty when the org
	// records no identity. Model, Version and HarnessVersion are empty or 0
	// when the hook could not tell.
	UserID         string `json:"-"`
	Model          string `json:"model,omitempty"`
	Version        int    `json:"version,omitempty"`
	HarnessVersion string `json:"harness_version,omitempty"`
}

Event represents a single skill activation telemetry record.

type EventFilter added in v0.16.0

type EventFilter struct {
	Consumer string `query:"consumer" doc:"Count only activations this consumer reported"`
	Role     string `query:"role" doc:"Count only activations reported for this role"`
}

EventFilter narrows activation counts to one consumer and one role. An empty field applies no filter. Hook events have neither, so any filter excludes them.

type Options added in v0.19.0

type Options struct {
	// RecordIdentity false stores no user on an event. Nil records it.
	RecordIdentity func() bool
	// MemberVisibility is "aggregate" or "person". Nil is aggregate.
	MemberVisibility func() string
}

Options are the org's activation settings, read on each request.

type OverviewData

type OverviewData struct {
	TotalSkills      int             `json:"total_skills"`
	ActiveSkills     int             `json:"active_skills"`
	TotalActivations int             `json:"total_activations"`
	UnreviewedSkills int             `json:"unreviewed_skills"`
	Security         SecuritySummary `json:"security"`

	// UnregisteredActivations counts events whose skill name was not in the
	// registry when they arrived. They are deliberately excluded from
	// TotalActivations — unvalidated names are not proof of use.
	UnregisteredActivations int `json:"unregistered_activations"`
}

OverviewData holds top-level KPI metrics for the analytics overview strip.

type QualitySummary added in v0.10.0

type QualitySummary struct {
	Version       int       `json:"version"`
	Headline      float64   `json:"headline_score"`
	Verified      bool      `json:"verified"`
	PanelComplete bool      `json:"panel_complete"`
	ScoredAt      time.Time `json:"scored_at"`
	Lift          *float64  `json:"lift,omitempty"`
}

QualitySummary is the compact quality state a list row needs to render a badge: enough to draw the meter and to say whether it may be trusted, and nothing more. The full report is a separate endpoint.

type SecuritySummary

type SecuritySummary struct {
	Clean    int `json:"clean"`
	Warning  int `json:"warning"`
	Critical int `json:"critical"`
}

SecuritySummary aggregates skill security statuses. The scanner produces "warn" and "high" status strings; both are counted under the Warning field. "critical" maps to Critical. Everything else (including "clean", "info", and skills with no scan results) maps to Clean.

type SkillAnalytics

type SkillAnalytics struct {
	Name           string     `json:"name"`
	Description    string     `json:"description"`
	Tags           []string   `json:"tags"`
	Author         string     `json:"author"`
	SpecCompliance string     `json:"spec_compliance"`
	Activations    int        `json:"activations"`
	UniqueDevs     int        `json:"unique_devs"`
	LastTriggered  *time.Time `json:"last_triggered"`
	SecurityStatus string     `json:"security_status"`
	ReviewedAt     *time.Time `json:"reviewed_at"`
	LatestVersion  int        `json:"latest_version"`
	UpdatedAt      time.Time  `json:"updated_at"`

	// Quality is nil when the skill has never been scored. Nil, not a zero
	// value: an unscored skill and a skill that scored zero are different
	// facts, and every surface renders them differently.
	Quality *QualitySummary `json:"quality,omitempty"`
}

SkillAnalytics holds per-skill analytics data for the table view.

type SkillsQuery added in v0.4.0

type SkillsQuery struct {
	Limit  int
	Offset int
	Sort   string // "activations" (default) | "name" | "updated" | "quality" | "lift"
	Query  string // case-insensitive substring on name/description
	Tag    string // frontmatter tag membership
	// Order is "asc" or "desc"; anything else uses the sort clause's own
	// default direction.
	Order string
	// Scored filters to skills that have ("yes") or have not ("no") been
	// scored. Empty means no filter.
	Scored string
	// Filter counts only matching activations. An active filter also drops the
	// skills with no matching activation, so the table shows what was used.
	Filter EventFilter
}

GetSkillsAnalytics returns per-skill analytics for all skills over the last `days` days, ordered by activation count descending. SkillsQuery holds optional list filters/pagination for GetSkillsAnalytics.

type Store

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

Store handles Postgres persistence for skill_events.

func NewStore

func NewStore(pool *pgxpool.Pool) *Store

NewStore constructs a Store backed by the given connection pool.

func (*Store) CleanupOldEvents added in v0.7.0

func (s *Store) CleanupOldEvents(ctx context.Context, retentionDays int) (int64, error)

CleanupOldEvents deletes events older than retentionDays and returns the number of rows removed. Pass 0 to disable (caller should check before calling).

func (*Store) DismissSkill

func (s *Store) DismissSkill(ctx context.Context, name string) error

DismissSkill inserts a name into dismissed_skills. Idempotent.

func (*Store) GetActivations

func (s *Store) GetActivations(ctx context.Context, skillName string, days int, filter EventFilter) (*ActivationSummary, error)

GetActivations returns an ActivationSummary for the given skill over the last `days` days. Returns a zero-value summary (no error) when no events exist.

func (*Store) GetAllTags added in v0.4.0

func (s *Store) GetAllTags(ctx context.Context) ([]string, error)

GetAllTags returns the distinct, sorted set of tags across all skills.

func (*Store) GetBreakdown added in v0.19.0

func (s *Store) GetBreakdown(ctx context.Context, days int, skill, userID string, admin bool, visibility string) (*Breakdown, error)

GetBreakdown returns the breakdown the caller may see.

func (*Store) GetConsumers added in v0.16.0

func (s *Store) GetConsumers(ctx context.Context) (*AnalyticsConsumersBody, error)

GetConsumers returns the distinct consumers and roles in stored events.

func (*Store) GetOverview

func (s *Store) GetOverview(ctx context.Context, days int, filter EventFilter) (*OverviewData, error)

GetOverview returns aggregate KPI data covering the last `days` days.

func (*Store) GetSkillTimeSeries

func (s *Store) GetSkillTimeSeries(ctx context.Context, skillName string, days int, filter EventFilter) ([]AgentDailyCount, error)

GetSkillTimeSeries returns daily per-agent activation counts for a specific skill over the last `days` days. Days with zero activations are included.

func (*Store) GetSkillsAnalytics

func (s *Store) GetSkillsAnalytics(ctx context.Context, days int, opts SkillsQuery) ([]SkillAnalytics, int, error)

func (*Store) GetTimeSeries

func (s *Store) GetTimeSeries(ctx context.Context, days int, filter EventFilter) ([]DailyCount, error)

GetTimeSeries returns daily activation counts for the last `days` days. Days with zero activations are included (filled with 0).

func (*Store) GetUnregisteredSkills

func (s *Store) GetUnregisteredSkills(ctx context.Context, days int) ([]UnregisteredSkill, error)

GetUnregisteredSkills returns skill names from events that don't exist in the skills table or dismissed_skills table, with activation stats.

func (*Store) Insert

func (s *Store) Insert(ctx context.Context, e Event) error

Insert writes a single activation event into skill_events.

type UnregisteredSkill

type UnregisteredSkill struct {
	Name          string     `json:"name"`
	Activations   int        `json:"activations"`
	UniqueDevs    int        `json:"unique_devs"`
	LastTriggered *time.Time `json:"last_triggered"`
	FirstSeen     *time.Time `json:"first_seen"`
}

UnregisteredSkill represents a skill name found in events but not in the registry.

Jump to

Keyboard shortcuts

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