Documentation
¶
Overview ¶
Package views provides explicit JSON view models for the HTTP API.
Handlers MUST NOT serialize GORM storage models directly — doing so leaks ORM bookkeeping (CreatedAt, UpdatedAt, DeletedAt) and tenant_id to the wire, and couples the UI contract to the schema. Each type here is the stable JSON shape consumed by the UI and by MCP clients.
Rules:
- No GORM bookkeeping fields (DeletedAt, CreatedAt, UpdatedAt).
- No tenant_id — auth already scopes the request.
- Preserve JSON field names that consumers rely on.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AffectedEntry ¶
type AffectedEntry struct {
Service string `json:"service"`
Depth int `json:"depth"`
CallCount int64 `json:"call_count"`
ImpactScore float64 `json:"impact_score"`
}
AffectedEntry is a service affected by an upstream failure.
type AnomalyNode ¶
type AnomalyNode struct {
ID string `json:"id"`
Type string `json:"type"`
Severity string `json:"severity"`
Service string `json:"service"`
Evidence string `json:"evidence"`
Timestamp time.Time `json:"timestamp"`
}
AnomalyNode is an anomaly detected by the anomaly engine.
func AnomalyNodeFromModel ¶
func AnomalyNodeFromModel(a graphrag.AnomalyNode) AnomalyNode
AnomalyNodeFromModel converts a GraphRAG anomaly node into its view.
type DashboardStats ¶
type DashboardStats struct {
TotalTraces int64 `json:"total_traces"`
TotalLogs int64 `json:"total_logs"`
TotalErrors int64 `json:"total_errors"`
AvgLatencyMs float64 `json:"avg_latency_ms"`
ErrorRate float64 `json:"error_rate"`
ActiveServices int64 `json:"active_services"`
P99LatencyMs float64 `json:"p99_latency_ms"`
LatencyProvenance *latency.Provenance `json:"latency_provenance,omitempty"`
TopFailingServices []ServiceError `json:"top_failing_services"`
Requests int64 `json:"requests,omitempty"`
RequestErrors int64 `json:"request_errors,omitempty"`
RequestErrorRate float64 `json:"request_error_rate,omitempty"`
Spans int64 `json:"spans,omitempty"`
SpanErrors int64 `json:"span_errors,omitempty"`
SpanErrorRate float64 `json:"span_error_rate,omitempty"`
Coverage string `json:"coverage,omitempty"`
CoverageNote string `json:"coverage_note,omitempty"`
Accuracy *aggregate.AccuracyMetadata `json:"accuracy,omitempty"`
Epoch string `json:"epoch,omitempty"`
Revision uint64 `json:"revision,omitempty"`
}
DashboardStats is the aggregated dashboard metric view.
The coverage/accuracy/epoch/revision fields and the six basis fields are ADDITIVE and only populated in aggregate mode: `omitempty` keeps the legacy payload byte-for-byte what it has always been.
total_traces / total_errors / error_rate are REQUEST-basis in both modes — legacy counts trace rows, aggregate counts root/SERVER spans (#194 blocker 5). requests/request_errors/request_error_rate restate that basis by name, and spans/span_errors/span_error_rate carry the span basis the old aggregate payload was mislabelling as traces. Both rates are percents, like error_rate.
func DashboardStatsFromAggregate ¶ added in v0.5.0
func DashboardStatsFromAggregate(r *aggregate.DashboardResult) DashboardStats
DashboardStatsFromAggregate converts an engine dashboard query into the same view the legacy path produces, plus the additive coverage and accuracy metadata. Field names, units and structure are deliberately identical: a client cannot tell which mode served it except by reading the new fields.
func DashboardStatsFromModel ¶
func DashboardStatsFromModel(s *storage.DashboardStats) DashboardStats
DashboardStatsFromModel converts repo stats into the view form.
type ImpactResult ¶
type ImpactResult struct {
Service string `json:"service"`
AffectedServices []AffectedEntry `json:"affected_services"`
TotalDownstream int `json:"total_downstream"`
}
ImpactResult describes the blast radius of a service failure.
func ImpactResultFromModel ¶
func ImpactResultFromModel(r *graphrag.ImpactResult) *ImpactResult
ImpactResultFromModel converts a GraphRAG impact result into its view.
type Investigation ¶
type Investigation struct {
ID string `json:"id"`
CreatedAt time.Time `json:"created_at"`
Status string `json:"status"`
Severity string `json:"severity"`
TriggerService string `json:"trigger_service"`
TriggerOperation string `json:"trigger_operation"`
ErrorMessage string `json:"error_message"`
RootService string `json:"root_service"`
RootOperation string `json:"root_operation"`
CausalChain any `json:"causal_chain"`
TraceIDs any `json:"trace_ids"`
ErrorLogs any `json:"error_logs"`
AnomalousMetrics any `json:"anomalous_metrics"`
AffectedServices any `json:"affected_services"`
SpanChain any `json:"span_chain"`
}
Investigation is the wire shape of an automated investigation record. The raw-JSON fields (CausalChain, TraceIDs, etc.) are passed through verbatim — they are already JSON on the wire.
func InvestigationFromModel ¶
func InvestigationFromModel(m graphrag.Investigation) Investigation
InvestigationFromModel converts a persisted GraphRAG Investigation into its view. The RawMessage fields are unwrapped to `any` so JSON output is the decoded structure, not a base64 blob.
func InvestigationsFromModels ¶
func InvestigationsFromModels(ms []graphrag.Investigation) []Investigation
InvestigationsFromModels is the slice form of InvestigationFromModel.
type Log ¶
type Log struct {
ID uint `json:"id"`
TraceID string `json:"trace_id"`
SpanID string `json:"span_id"`
Severity string `json:"severity"`
Body string `json:"body"`
ServiceName string `json:"service_name"`
AttributesJSON string `json:"attributes_json"`
AIInsight string `json:"ai_insight"`
Timestamp time.Time `json:"timestamp"`
}
Log is the wire shape of an ingested log record.
func LogFromModel ¶
LogFromModel converts a storage.Log into its view.
func LogsFromModels ¶
LogsFromModels is the slice form of LogFromModel.
type LogClusterNode ¶
type LogClusterNode struct {
ID string `json:"id"`
Template string `json:"template"`
TemplateID uint64 `json:"template_id,omitempty"`
TemplateTokens []string `json:"template_tokens,omitempty"`
SampleLog string `json:"sample_log,omitempty"`
Count int64 `json:"count"`
FirstSeen time.Time `json:"first_seen"`
LastSeen time.Time `json:"last_seen"`
SeverityDist map[string]int64 `json:"severity_distribution"`
}
LogClusterNode is the wire shape of a log cluster (Drain template).
func LogClusterNodeFromModel ¶
func LogClusterNodeFromModel(n graphrag.LogClusterNode) LogClusterNode
LogClusterNodeFromModel converts a GraphRAG log cluster into its view.
type MetricBucket ¶
type MetricBucket struct {
ID uint `json:"id"`
Name string `json:"name"`
ServiceName string `json:"service_name"`
TimeBucket time.Time `json:"time_bucket"`
Min float64 `json:"min"`
Max float64 `json:"max"`
Sum float64 `json:"sum"`
Count int64 `json:"count"`
AttributesJSON string `json:"attributes_json"`
}
MetricBucket is the wire shape of a pre-aggregated metric window.
func MetricBucketFromModel ¶
func MetricBucketFromModel(m storage.MetricBucket) MetricBucket
MetricBucketFromModel converts a storage.MetricBucket into its view.
func MetricBucketsFromModels ¶
func MetricBucketsFromModels(ms []storage.MetricBucket) []MetricBucket
MetricBucketsFromModels is the slice form of MetricBucketFromModel.
type RootCauseInfo ¶
type RootCauseInfo struct {
Service string `json:"service"`
Operation string `json:"operation"`
ErrorMessage string `json:"error_message"`
SpanID string `json:"span_id"`
TraceID string `json:"trace_id"`
}
RootCauseInfo identifies the responsible service/operation behind an error chain.
func RootCauseInfoFromModel ¶
func RootCauseInfoFromModel(r *graphrag.RootCauseInfo) *RootCauseInfo
RootCauseInfoFromModel converts a GraphRAG root-cause node into its view.
type ServiceError ¶
type ServiceError struct {
ServiceName string `json:"service_name"`
ErrorCount int64 `json:"error_count"`
TotalCount int64 `json:"total_count"`
ErrorRate float64 `json:"error_rate"`
}
ServiceError is the top-failing-service entry on the dashboard.
type ServiceMapEdge ¶
type ServiceMapEdge struct {
Source string `json:"source"`
Target string `json:"target"`
CallCount int64 `json:"call_count"`
AvgLatencyMs float64 `json:"avg_latency_ms"`
ErrorRate float64 `json:"error_rate"`
}
ServiceMapEdge is an edge on the service topology view.
type ServiceMapMetrics ¶
type ServiceMapMetrics struct {
Nodes []ServiceMapNode `json:"nodes"`
Edges []ServiceMapEdge `json:"edges"`
Source string `json:"source,omitempty"`
Coverage string `json:"coverage,omitempty"`
CoverageNote string `json:"coverage_note,omitempty"`
Epoch string `json:"epoch,omitempty"`
Revision uint64 `json:"revision,omitempty"`
Truncated bool `json:"truncated,omitempty"`
DroppedServices uint64 `json:"dropped_services,omitempty"`
DroppedOperations uint64 `json:"dropped_operations,omitempty"`
DroppedEdges uint64 `json:"dropped_edges,omitempty"`
DroppedMetrics uint64 `json:"dropped_metrics,omitempty"`
}
ServiceMapMetrics is the full topology view. Coverage is additive and only populated in aggregate mode.
func ServiceMapMetricsFromAggregate ¶ added in v0.5.0
func ServiceMapMetricsFromAggregate(r *aggregate.TopologyResult) ServiceMapMetrics
ServiceMapMetricsFromAggregate converts an engine topology query into the topology view.
Nodes AND edges come from the one result: they were read from one tenant, one range and one ownership snapshot, and the coverage the engine reported describes both. Nothing is supplemented from a second store here — that supplementation is #194 finding 15.
func ServiceMapMetricsFromModel ¶
func ServiceMapMetricsFromModel(m *storage.ServiceMapMetrics) ServiceMapMetrics
ServiceMapMetricsFromModel converts repo topology into the view form.
func ServiceMapMetricsFromTopology ¶ added in v0.5.0
func ServiceMapMetricsFromTopology(snapshot topology.Snapshot) ServiceMapMetrics
ServiceMapMetricsFromTopology converts the mode-selected provider snapshot without exposing its owning package on the HTTP wire.
type ServiceMapNode ¶
type ServiceMapNode struct {
Name string `json:"name"`
TotalTraces int64 `json:"total_traces"`
ErrorCount int64 `json:"error_count"`
AvgLatencyMs float64 `json:"avg_latency_ms"`
P99LatencyMs float64 `json:"p99_latency_ms,omitempty"`
LatencyProvenance *latency.Provenance `json:"latency_provenance,omitempty"`
// Additive host projection (#288): kind is service|host, hosts is sorted
// and capped at topology.MaxHostsPerNode, host_count is the full total.
Kind string `json:"kind,omitempty"`
HostCount int `json:"host_count,omitempty"`
Hosts []string `json:"hosts,omitempty"`
}
ServiceMapNode is a node on the service topology view.
type Span ¶
type Span struct {
ID uint `json:"id"`
TraceID string `json:"trace_id"`
SpanID string `json:"span_id"`
ParentSpanID string `json:"parent_span_id"`
OperationName string `json:"operation_name"`
StartTime time.Time `json:"start_time"`
EndTime time.Time `json:"end_time"`
Duration int64 `json:"duration"`
ServiceName string `json:"service_name"`
Status string `json:"status"`
AttributesJSON string `json:"attributes_json"`
}
Span is the wire shape of a single operation inside a trace.
func SpanFromModel ¶
SpanFromModel converts a storage.Span into its view.
func SpansFromModels ¶
SpansFromModels is the slice form of SpanFromModel.
type Trace ¶
type Trace struct {
ID uint `json:"id"`
TraceID string `json:"trace_id"`
ServiceName string `json:"service_name"`
Operation string `json:"operation"`
Status string `json:"status"`
Duration int64 `json:"duration"` // microseconds, preserved for legacy consumers
DurationMs float64 `json:"duration_ms"`
SpanCount int `json:"span_count"`
Timestamp time.Time `json:"timestamp"`
Spans []Span `json:"spans,omitempty"`
Logs []Log `json:"logs,omitempty"`
}
Trace is the wire shape of a distributed trace summary.
func TraceFromModel ¶
TraceFromModel converts a storage.Trace (with possibly-Preloaded children) into its wire-facing view.
func TracesFromModels ¶
TracesFromModels is the slice form of TraceFromModel.
type TracesResponse ¶
type TracesResponse struct {
Traces []Trace `json:"traces"`
Total int64 `json:"total"`
Limit int `json:"limit"`
Offset int `json:"offset"`
}
TracesResponse is the paginated trace-list response.
func TracesResponseFromModel ¶
func TracesResponseFromModel(r *storage.TracesResponse) TracesResponse
TracesResponseFromModel wraps a repo TracesResponse into the view form.
Source Files