insights

package
v0.0.21 Latest Latest
Warning

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

Go to latest
Published: Sep 12, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Breakdown

type Breakdown struct {
	ByModel   []dao.LeaderRow `json:"by_model,omitempty"`
	ByChannel []dao.LeaderRow `json:"by_channel,omitempty"`
	ByAgent   []dao.LeaderRow `json:"by_agent,omitempty"`
	ByUser    []dao.LeaderRow `json:"by_user,omitempty"`
	ByToken   []dao.LeaderRow `json:"by_token,omitempty"`
}

Breakdown 是 entity 的下钻维度。不同 provider 填不同子集:

agent provider → ByModel + ByChannel (一个 agent 内 model 用量、channel 用量)
其它 provider → 自行选择

空 slice 用 omitempty 隐藏。

type Context

type Context interface {
	DAO() dao.AdminQuery
	Scope() dao.Scope
	RequestScope() *middleware.RequestScope
}

Context 是 InsightProvider 收到的执行上下文。 抽出来一个最小接口而不是直接传 (q, scope, app), 方便测试时 mock,也避免每个 provider method 都重复 4 个参数。

type EntityMeta

type EntityMeta struct {
	ID       string `json:"id"`
	Name     string `json:"name"`
	Online   bool   `json:"online,omitempty"`
	LastSeen int64  `json:"last_seen,omitempty"`
	Region   string `json:"region,omitempty"`
	Version  string `json:"version,omitempty"`
	JoinedAt int64  `json:"joined_at,omitempty"`
}

EntityMeta 是 entity 自身的描述信息。 字段语义按 type 不同:

agent:   ID=agent_id, Name=agent.Name, Online/LastSeen 由 agents 表填
其它:   暂未实现 (stub)

type ErrorSample

type ErrorSample struct {
	Ts      int64  `json:"ts"`
	Stage   string `json:"stage,omitempty"`
	Channel string `json:"channel,omitempty"`
	Model   string `json:"model,omitempty"`
	Message string `json:"message"`
}

ErrorSample 是 entity 最近的失败样本 (按时间倒序前 N 条)。 字段集尽量稳定:前端用来展示一张 "最近错误" 表,允许部分字段为空。

type GetRequest

type GetRequest struct {
	Type  string `form:"type"`
	ID    string `form:"id"`
	Start int64  `form:"start"`
	End   int64  `form:"end"`
	Gran  string `form:"gran"`
}

GetRequest 是 /v1/insights 入参。 type=agent|channel|model|user|token; id 是该 entity 的主键 (agent_id, channel_id, ...)。 start/end 缺省 now-86400 / now;gran 缺省 "day"。

type GetResponse

type GetResponse struct {
	Meta         EntityMeta        `json:"meta"`
	Summary      SummaryKpis       `json:"summary"`
	Trend        TrendBlock        `json:"trend"`
	StageLatency *dao.StageLatency `json:"stage_latency"`
	Breakdown    Breakdown         `json:"breakdown"`
	Errors       []ErrorSample     `json:"errors"`
}

GetResponse 是 /v1/insights 返回结构。 字段保持稳定:即便某个 provider 不填 StageLatency,也返回 null 而不是 omitempty 缺失; 这样前端不用判断字段存在性,只判 null。

type Handler

type Handler struct {
	// Tracker 用于 EnrichLastSeen,覆盖 agent Meta 的 last_seen。
	// nil 时跳过 enrich(DB 值 fallback)。
	Tracker               *msync.HeartbeatTracker
	LogDatabaseReady      func() bool
	InsightProviderFinder func(string) (InsightProvider, bool)
}

Handler 是 /v1/insights 端点的容器。 实际 entity-type 维度的查询由 InsightProvider 实现 (见 provider.go); Handler 仅做参数校验、type 路由和响应组装。

func (*Handler) Get

func (h *Handler) Get(c *app.Context, req GetRequest) (GetResponse, error)

Get 是 /v1/insights 的总入口。

流程:

  1. 必填校验 (type/id)。
  2. registry 查不到 type → 404 InsightTypeUnsupported。
  3. 命中 stubProvider → 501 NotImplemented (区分 type 不存在 vs 暂未实现)。
  4. 窗口校验越界 → 400 RangeOutOfBounds。
  5. user scope 访问 user/token 维度但 id != self → 403 (admin-only operational view)。 Phase 1: 简化为 monitoring 同策略,整页 admin-only 也行,但 spec 要求按 type 区分, 我们仅在 user/token 维度做这个检查。
  6. provider.Meta 失败 → 透传 (Meta 内部决定 404 / 500 等)。
  7. 日志库不可用统一返回 503;其余子查询失败被静默吞掉。

type InsightProvider

type InsightProvider interface {
	Meta(ctx Context, id string) (EntityMeta, error)
	Summary(ctx Context, id string, r dao.ObsRange) (SummaryKpis, error)
	Trend(ctx Context, id string, r dao.ObsRange) ([]dao.TimeBucket, error)
	StageLatency(ctx Context, id string, r dao.ObsRange) (*dao.StageLatency, error)
	Breakdown(ctx Context, id string, r dao.ObsRange) (Breakdown, error)
	RecentErrors(ctx Context, id string, r dao.ObsRange, limit int) ([]ErrorSample, error)
}

InsightProvider 是 entity 维度的查询契约。 每个 entity-type (agent/channel/model/...) 一个 provider 实例,实现下面这 6 个方法, 由 handler 拼装成统一的 GetResponse。

设计要点:

  1. Meta 是入口:返回 404 NotFound 时 handler 立刻终止 (entity 不存在); 其他方法的错误一般被静默吞掉 (子查询 best-effort)。
  2. StageLatency 允许返回 nil (前端 null);不是所有 entity-type 都有 stage 时延概念。
  3. RecentErrors 给定 limit;provider 自己决定是否复用,以及如何过滤。

type SummaryKpis

type SummaryKpis struct {
	Requests    int64   `json:"requests"`
	Cost        int64   `json:"cost"`
	Tokens      int64   `json:"tokens"`
	SuccessRate float64 `json:"success_rate"`
	TTFTP95Ms   int64   `json:"ttft_p95_ms"`
	TPSAvg      float64 `json:"tps_avg"`
}

SummaryKpis 是 entity 在窗口期内的统计概览。 这些数字对应前端右侧 "KPI 速览" 区域,与 stage_latency / breakdown 是不同抽屉。

type TrendBlock

type TrendBlock struct {
	Buckets []dao.TimeBucket `json:"buckets"`
	Metrics []string         `json:"metrics"`
}

TrendBlock 是 /v1/insights 的时间序列块。 Metrics 列出 buckets 中含哪些字段 (cost/requests/tokens),给前端选择 y-axis。

Jump to

Keyboard shortcuts

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