Files
coder/codersdk/appname.go
T
Ehab Younes 0aae890d03 feat: return per-app session counts from workspace agent stats queries (#29134)
- Make all six raw session-count queries return a session_counts JSONB
object keyed by app name instead of fixed per-family columns. Fold the
results into existing family fields in Go using the shared SDK registry,
including unrecognized names under unknown.
- Remove the registry parameters and associated dbauthz validation from
these queries, which no longer perform family attribution in SQL.
Preserve existing deployment stats, Prometheus, and telemetry outputs.
- Select session maps directly in the two latest-row queries instead of
decomposing and reaggregating a single row. Keep byte, connection, and
latency aggregates independent of per-app expansion.
- Add regressions for latest eligible rows, empty session maps, distinct
same-family app names, labels, and unchanged traffic aggregates.
2026-09-10 14:07:03 +02:00

174 lines
6.5 KiB
Go

package codersdk
import (
"encoding/json"
"slices"
"strings"
"golang.org/x/xerrors"
utilstrings "github.com/coder/coder/v2/coderd/util/strings"
)
// maxAppNameLength caps an app name in runes.
const maxAppNameLength = 64
// AppFamilyName is the bounded set of names that arbitrary app names group
// into, for callers that need a fixed value such as a metric label or the
// Connection_Type enum. Server-side only, not part of the HTTP API.
//
// @typescript-ignore AppFamilyName
type AppFamilyName string
const (
AppFamilyVSCode AppFamilyName = "vscode"
AppFamilyJetBrains AppFamilyName = "jetbrains"
AppFamilySSH AppFamilyName = "ssh"
AppFamilyReconnectingPTY AppFamilyName = "reconnecting_pty"
AppFamilyUnknown AppFamilyName = "unknown"
)
// appNameFamilies never gates storage, so a missing alias only costs an
// AppFamilyUnknown label. Keys are the IDs Coder's registry modules use.
var appNameFamilies = map[string]AppFamilyName{
"vscode": AppFamilyVSCode,
"vscode_insiders": AppFamilyVSCode,
"vscode_web": AppFamilyVSCode,
"code_server": AppFamilyVSCode,
"cursor": AppFamilyVSCode,
"windsurf": AppFamilyVSCode,
"positron": AppFamilyVSCode,
"vscodium": AppFamilyVSCode,
"codium": AppFamilyVSCode,
"antigravity": AppFamilyVSCode,
"trae": AppFamilyVSCode,
"kiro": AppFamilyVSCode,
"devin": AppFamilyVSCode,
"jetbrains": AppFamilyJetBrains,
// Zed has no Connection_Type or session count field of its own, so it
// rolls up under SSH. The raw name still reaches storage.
"zed": AppFamilySSH,
"ssh": AppFamilySSH,
"reconnecting_pty": AppFamilyReconnectingPTY,
}
// attributedAppFamilies are the families usage reporting has somewhere to
// put, and the single definition of the families the session count read
// queries know about. Every value in appNameFamilies must appear here or its
// sessions go uncounted, which TestEveryFamilyIsAttributed enforces.
//
// Adding a family here is not enough on its own: see AttributedAppFamilies.
var attributedAppFamilies = []AppFamilyName{
AppFamilyVSCode,
AppFamilyJetBrains,
AppFamilySSH,
AppFamilyReconnectingPTY,
}
// AttributedAppFamilies returns the families session count reporting can
// attribute to, in registry order. It is the source of truth that dbauthz
// validates the query parameter against, so a family that exists here but not
// in the queries (or the reverse) fails loudly instead of silently reporting
// zero.
func AttributedAppFamilies() []AppFamilyName {
return slices.Clone(attributedAppFamilies)
}
// AppNamesInFamily returns the app names belonging to a family, sorted so
// query parameters stay stable across calls.
func AppNamesInFamily(family AppFamilyName) []string {
var names []string
for appName, appFamily := range appNameFamilies {
if appFamily == family {
names = append(names, appName)
}
}
slices.Sort(names)
return names
}
// SessionCountAppFamilies returns the session count attribution registry:
// every attributed family mapped to its sorted app names. The session count
// read queries take it as one parameter, so a new app name reaches every
// caller by being added to appNameFamilies alone.
//
// A new family costs more. sqlc output columns are static, so each family
// needs, in addition to its attributedAppFamilies entry, one probe expression
// in every query that reports per-family session counts (see
// coderd/database/queries/workspaceagentstats.sql and insights.sql) plus the
// matching output column. dbauthz validation rejects a registry whose
// families do not match AttributedAppFamilies, and
// TestAttributedAppFamiliesMatchQueries pins that list to what the queries
// probe, so neither half can drift unnoticed.
func SessionCountAppFamilies() map[AppFamilyName][]string {
families := make(map[AppFamilyName][]string, len(attributedAppFamilies))
for _, family := range attributedAppFamilies {
families[family] = AppNamesInFamily(family)
}
return families
}
// SessionCountAppFamiliesJSON is SessionCountAppFamilies marshaled for the
// jsonb parameter the session count read queries accept.
func SessionCountAppFamiliesJSON() json.RawMessage {
// Marshaling a map with a string-keyed type cannot fail.
data, err := json.Marshal(SessionCountAppFamilies())
if err != nil {
panic("developer error: marshal session count app families: " + err.Error())
}
return data
}
// SessionCountsByFamily folds per-app session counts, as the session count
// queries report them, into per-family totals. Counts are additive: an agent
// running Cursor and VS Code at once contributes both to the VS Code family.
// App names with no registry entry total under AppFamilyUnknown rather than
// being dropped.
func SessionCountsByFamily(appCounts map[string]int64) map[AppFamilyName]int64 {
familyCounts := make(map[AppFamilyName]int64, len(appCounts))
for appName, count := range appCounts {
familyCounts[AppNameFamily(appName)] += count
}
return familyCounts
}
// SessionCountsByFamilyJSON is SessionCountsByFamily over the jsonb object of
// app name to session count that the session count queries return. An absent
// or JSON null object means no sessions, not an error, because a query with
// no matching rows aggregates to SQL NULL.
func SessionCountsByFamilyJSON(appCounts json.RawMessage) (map[AppFamilyName]int64, error) {
var counts map[string]int64
if len(appCounts) > 0 {
if err := json.Unmarshal(appCounts, &counts); err != nil {
return nil, xerrors.Errorf("unmarshal session counts by app name: %w", err)
}
}
return SessionCountsByFamily(counts), nil
}
// AppNameFamily normalizes an app name and returns its family, or
// AppFamilyUnknown.
func AppNameFamily(appName string) AppFamilyName {
if family, ok := appNameFamilies[NormalizeAppName(appName)]; ok {
return family
}
return AppFamilyUnknown
}
// NormalizeAppName prepares a client-supplied app name for storage and
// lookup: it strips the null bytes Postgres TEXT rejects, trims, truncates,
// lowercases, and folds hyphens to underscores. Empty becomes
// AppFamilyUnknown.
func NormalizeAppName(appName string) string {
appName = strings.ReplaceAll(appName, "\x00", "")
// Trim before truncating so padding does not spend the budget, and after
// in case the cut lands in whitespace.
appName = strings.TrimSpace(appName)
appName = strings.TrimSpace(utilstrings.Truncate(appName, maxAppNameLength))
if appName == "" {
return string(AppFamilyUnknown)
}
return strings.ReplaceAll(strings.ToLower(appName), "-", "_")
}