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 的总入口。
流程:
- 必填校验 (type/id)。
- registry 查不到 type → 404 InsightTypeUnsupported。
- 命中 stubProvider → 501 NotImplemented (区分 type 不存在 vs 暂未实现)。
- 窗口校验越界 → 400 RangeOutOfBounds。
- user scope 访问 user/token 维度但 id != self → 403 (admin-only operational view)。 Phase 1: 简化为 monitoring 同策略,整页 admin-only 也行,但 spec 要求按 type 区分, 我们仅在 user/token 维度做这个检查。
- provider.Meta 失败 → 透传 (Meta 内部决定 404 / 500 等)。
- 日志库不可用统一返回 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。
设计要点:
- Meta 是入口:返回 404 NotFound 时 handler 立刻终止 (entity 不存在); 其他方法的错误一般被静默吞掉 (子查询 best-effort)。
- StageLatency 允许返回 nil (前端 null);不是所有 entity-type 都有 stage 时延概念。
- 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。