usageapi

Documentation

Overview

Package usageapi builds what magpie tells of its usage log: the Usage page's summary and its requests, a page at a time. The GUI's /api/usage and the gateway's /v1/magpie/usage answer the same JSON from here, so an app reading one reads the other.

Index

• Constants
• Variables
• func FilterOf(q url.Values) usage.Filter
• func PeriodOf(s string) usage.Period
• func Tilde(p string) string
• type Account
• type Client
• type Group
• type Ledger
  • func LedgerPage(p usage.Period, f usage.Filter, offset, limit int) Ledger
  • func OwnPage(l Ledger, key string) Ledger
• type Named
• type Row
• type Share
• type Usage
  • func Page(p usage.Period) Usage
  • func State(p usage.Period) Usage

Constants

const PageSessions = 100

PageSessions is how many sessions Page lists: the Usage page draws none of them, and SessionCount says how many there are.

Variables

var Clients func() []Client

Clients are the agents magpie knows, for their names and logos: set by the GUI (internal/agent imports the gateway, which imports this). Unset, an agent is named by its id.

Functions

func FilterOf

func FilterOf(q url.Values) usage.Filter

func PeriodOf

func PeriodOf(s string) usage.Period

PeriodOf is the period a ?period= names: a preset, or days picked as "2026-10-01..2026-10-07" (#1492); 30 days for anything else.

func Tilde

func Tilde(p string) string

Tilde is p with the home folder written ~.

Types

type Account

type Account struct {
	ID        string   `json:"id"`
	Providers []string `json:"providers"`
}

Account is a subscription account the Account filter offers: its name, and the providers it answered for, by name.

type Client

type Client struct{ ID, Name, Icon string }

Client is an agent as the usage JSON names it.

type Group

type Group struct {
	usage.Group
	Name string `json:"name"`
	Sub  string `json:"sub,omitempty"`  // models: the provider's name
	Icon string `json:"icon,omitempty"` // a real logo, or "generic" for an unknown client
}

Group is a usage.Group with what the UI needs to draw it.

type Ledger

type Ledger struct {
	CallerKeys []Group      `json:"callerKeys"`
	Period     usage.Period `json:"period"`
	Rows       []Row        `json:"rows"`
	Offset     int          `json:"offset"`
	Total      int          `json:"total"` // the rows the filter keeps, on every page
	// Series: the period by hour, day or week (Bucket), before the day filter
	Bucket string              `json:"bucket"`
	Series []usage.SeriesPoint `json:"series"`
	// By: the rows told apart by provider, agent, model and model at each
	// provider ("modelAt", named "model · provider"), the most tokens
	// first. The one by a dimension the filter has picked is of the rows
	// without that pick, so the others are still there to switch to.
	By      map[string][]Share `json:"by"`
	ChartBy map[string][]Share `json:"chartBy,omitempty"`
	Day     string             `json:"day,omitempty"`
	usage.Totals
	// Through and Direct: the rows the gateway served, and the rows read
	// from the agents' own session files, which it never saw. Totals is
	// the two together, so the page can show all three (#the usage report).
	Through usage.Totals `json:"through"`
	Direct  usage.Totals `json:"direct"`
	// Reported: the calls a client told magpie of through POST
	// /v1/magpie/usage/requests (#1874), which went straight to their vendor
	Reported usage.Totals `json:"reported"`
	// Agents, Providers and Purposes: those with calls in the period, for the filters
	Agents    []Named  `json:"agents"`
	Providers []Named  `json:"providers"`
	Purposes  []string `json:"purposes"`
	// Accounts: the subscription accounts that answered calls in the
	// period, for the Account filter (#557)
	Accounts []Account `json:"accounts"`
	// Computers: this one ("this", no name) and the others whose usage
	// sync brought (#542), for the filter; none while there are none
	Computers []Share `json:"computers,omitempty"`
}

func LedgerPage

func LedgerPage(p usage.Period, f usage.Filter, offset, limit int) Ledger

LedgerPage is one page of the ledger: limit rows (100 when none is given, 500 at most) from offset.

func OwnPage

func OwnPage(l Ledger, key string) Ledger

OwnPage is l, a page filtered to the gateway key key's own calls, with its filter lists cut to what those calls had: they are drawn from every call in the period, and so would name the other keys, and the agents, providers and accounts only someone else's calls reached. The split by key is counted without the key's pick, so it is cut to the key's own share too, or it would tell a holder every other key's calls (#2521).

type Named

type Named struct {
	ID   string `json:"id"`
	Name string `json:"name"`
	Icon string `json:"icon"`
}

type Row

type Row struct {
	usage.Row
	CallerKeyLabel string `json:"callerKeyLabel,omitempty"`
	AgentName      string `json:"agentName"`
	Icon           string `json:"icon"` // the agent's
	ProviderName   string `json:"providerName"`
	Access         string `json:"access,omitempty"` // known account/route type, independent of model maker
	PricingModel   string `json:"pricing_model,omitempty"`
	// ComputerName is the other computer a call was made on, shared through sync (#542)
	ComputerName string `json:"computerName,omitempty"`
}

Row is a usage.Row with the names the page shows it by.

type Share

type Share struct {
	usage.Share
	Name string `json:"name"`
	Icon string `json:"icon,omitempty"`
}

Share is a usage.Share with the name and logo the page shows it by.

type Usage

type Usage struct {
	usage.Summary
	Agents     []Group `json:"agents"`
	Models     []Group `json:"models"`
	Accounts   []Group `json:"accounts"`
	CallerKeys []Group `json:"callerKeys"`
	Path       string  `json:"path"`
}

func Page

func Page(p usage.Period) Usage

Page is State with the top PageSessions sessions only, which is what the Usage page asks for: over a long history (Vantiboo1ean, ~750k requests) State sent the page every one of ~84k sessions (22 MB) and worked the summary out again for each refresh.

func State

func State(p usage.Period) Usage

State is the Usage page's summary of a period: what /api/usage and the gateway's GET /v1/magpie/usage answer.