collector

package
v1.11.2 Latest Latest
Warning

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

 Go to latest Published: Sep 23, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type CollectorDetail added in v1.2.0 

type CollectorDetail struct {
	Name           string            `json:"name"`
	Type           string            `json:"type"`
	Status         string            `json:"status"`
	MetricsCount   int               `json:"metrics_count"`
	LastCollection time.Time         `json:"last_collection"`
	Metrics        map[string]any    `json:"metrics"`
	Metadata       map[string]string `json:"metadata"`
}

CollectorDetail contains comprehensive collector information for the detail page.

type CollectorInfo 

type CollectorInfo struct {
	Name           string    `json:"name"`
	Type           string    `json:"type"`
	MetricsCount   int       `json:"metrics_count"`
	LastCollection time.Time `json:"last_collection"`
	Status         string    `json:"status"`
}

CollectorInfo contains information about a metrics collector.

type CounterDetail added in v1.2.0 

type CounterDetail struct {
	Value     float64        `json:"value"`
	Exemplars []ExemplarInfo `json:"exemplars"`
}

CounterDetail contains counter metric details.

type DashboardSnapshot 

type DashboardSnapshot struct {
	Timestamp   time.Time     `json:"timestamp"`
	Overview    OverviewData  `json:"overview"`
	Health      HealthData    `json:"health"`
	Metrics     MetricsData   `json:"metrics"`
	Services    []ServiceInfo `json:"services"`
	GeneratedBy string        `json:"generated_by"`
}

DashboardSnapshot contains complete dashboard state for export.

type DashboardSpanExporter added in v1.2.0 

type DashboardSpanExporter struct {
	// contains filtered or unexported fields
}

DashboardSpanExporter implements observability.SpanExporter and feeds completed spans into a TraceStore for the dashboard tracing UI.

func NewDashboardSpanExporter added in v1.2.0 

func NewDashboardSpanExporter(store *TraceStore) *DashboardSpanExporter

NewDashboardSpanExporter creates a new exporter backed by the given TraceStore.

func (*DashboardSpanExporter) ExportSpans added in v1.2.0 

func (e *DashboardSpanExporter) ExportSpans(_ context.Context, spans []*observability.Span) error

ExportSpans converts observability spans to SpanView and adds them to the store.

func (*DashboardSpanExporter) Shutdown added in v1.2.0 

func (e *DashboardSpanExporter) Shutdown(_ context.Context) error

Shutdown is a no-op for the in-memory dashboard exporter.

type DataCollector 

type DataCollector struct {
	// contains filtered or unexported fields
}

DataCollector collects dashboard data periodically.

func NewDataCollector 

func NewDataCollector(
	healthManager forge.HealthManager,
	metrics forge.Metrics,
	container shared.Container,
	logger forge.Logger,
	history *DataHistory,
) *DataCollector

NewDataCollector creates a new data collector.

func (*DataCollector) CollectCollectorDetail added in v1.2.0 

func (dc *DataCollector) CollectCollectorDetail(_ context.Context, collectorName string) *CollectorDetail

CollectCollectorDetail collects detailed information about a specific collector.

func (*DataCollector) CollectHealth 

func (dc *DataCollector) CollectHealth(ctx context.Context) *HealthData

CollectHealth returns health check data, using a short-lived cache. It merges health report data with ALL container services so that services without registered health checks still appear (as "unknown" status).

func (*DataCollector) CollectMetricDetail added in v1.2.0 

func (dc *DataCollector) CollectMetricDetail(_ context.Context, metricName string) *MetricDetail

CollectMetricDetail collects detailed information about a specific metric.

func (*DataCollector) CollectMetrics 

func (dc *DataCollector) CollectMetrics(ctx context.Context) *MetricsData

CollectMetrics returns current metrics, using a short-lived cache.

func (*DataCollector) CollectMetricsReport 

func (dc *DataCollector) CollectMetricsReport(_ context.Context) *MetricsReport

CollectMetricsReport collects comprehensive metrics report.

func (*DataCollector) CollectOverview 

func (dc *DataCollector) CollectOverview(ctx context.Context) *OverviewData

CollectOverview returns overview data, using a short-lived cache to avoid redundant allocations across page renders, API calls, and bridge requests.

func (*DataCollector) CollectServiceDetail 

func (dc *DataCollector) CollectServiceDetail(_ context.Context, serviceName string) *ServiceDetail

CollectServiceDetail collects detailed information about a specific service.

func (*DataCollector) CollectServices 

func (dc *DataCollector) CollectServices(_ context.Context) []ServiceInfo

CollectServices collects service information with health status.

func (*DataCollector) SetCacheTTL added in v1.6.0 

func (dc *DataCollector) SetCacheTTL(ttl time.Duration)

SetCacheTTL sets the cache TTL for collected data. Should match RefreshInterval.

func (*DataCollector) SetOnCollect added in v1.2.0 

func (dc *DataCollector) SetOnCollect(fn OnCollectFunc)

SetOnCollect registers a callback invoked after each data collection cycle.

func (*DataCollector) Start 

func (dc *DataCollector) Start(ctx context.Context, interval time.Duration)

Start starts periodic data collection.

func (*DataCollector) Stop 

func (dc *DataCollector) Stop()

Stop stops data collection. Safe to call multiple times.

type DataHistory 

type DataHistory struct {
	// contains filtered or unexported fields
}

DataHistory manages historical time-series data with a ring buffer. Overview and health snapshots are stored locally. Metric time-series data is delegated to the metrics package's TimeSeriesQueryProvider.

func NewDataHistory 

func NewDataHistory(maxPoints int, retentionPeriod time.Duration, tsProvider internalmetrics.TimeSeriesQueryProvider) *DataHistory

NewDataHistory creates a new data history manager. tsProvider is optional and used for metric time-series queries.

func (*DataHistory) AddHealth 

func (dh *DataHistory) AddHealth(snapshot HealthSnapshot)

AddHealth adds a health snapshot.

func (*DataHistory) AddOverview 

func (dh *DataHistory) AddOverview(snapshot OverviewSnapshot)

AddOverview adds an overview snapshot.

func (*DataHistory) Clear 

func (dh *DataHistory) Clear()

Clear clears all historical data.

func (*DataHistory) GetAll 

func (dh *DataHistory) GetAll() HistoryData

GetAll returns all historical data.

func (*DataHistory) GetHealth 

func (dh *DataHistory) GetHealth() []HealthSnapshot

GetHealth returns all health snapshots.

func (*DataHistory) GetMetricTimeSeries added in v1.2.0 

func (dh *DataHistory) GetMetricTimeSeries(metricName string) []DataPoint

GetMetricTimeSeries returns time-series data for a single metric by querying the metrics package's time-series storage directly.

func (*DataHistory) GetOverview 

func (dh *DataHistory) GetOverview() []OverviewSnapshot

GetOverview returns all overview snapshots.

type DataPoint 

type DataPoint struct {
	Timestamp time.Time         `json:"timestamp"`
	Value     float64           `json:"value"`
	Labels    map[string]string `json:"labels,omitempty"`
	Metadata  map[string]any    `json:"metadata,omitempty"`
}

DataPoint represents a time-series data point.

type ExemplarInfo added in v1.2.0 

type ExemplarInfo struct {
	Value     float64           `json:"value"`
	Timestamp time.Time         `json:"timestamp"`
	TraceID   string            `json:"trace_id"`
	SpanID    string            `json:"span_id"`
	Labels    map[string]string `json:"labels"`
}

ExemplarInfo contains exemplar information linking metrics to traces.

type ExportFormat 

type ExportFormat string

ExportFormat represents data export format. 

const (
	ExportFormatJSON       ExportFormat = "json"
	ExportFormatCSV        ExportFormat = "csv"
	ExportFormatPrometheus ExportFormat = "prometheus"
)

type GaugeDetail added in v1.2.0 

type GaugeDetail struct {
	Value float64 `json:"value"`
}

GaugeDetail contains gauge metric details.

type HTTPExchange added in v1.11.2 

type HTTPExchange struct {
	Request  HTTPMessage `json:"request"`
	Response HTTPMessage `json:"response"`
}

HTTPExchange contains request and response data retained with an HTTP span. The dashboard middleware limits headers to an allowlist and captures only opt-in JSON request bodies. Other instrumentation may supply either body.

type HTTPMessage added in v1.11.2 

type HTTPMessage struct {
	Headers map[string]string `json:"headers,omitempty"`
	Body    string            `json:"body,omitempty"`
}

type HealthData 

type HealthData struct {
	OverallStatus string                   `json:"overall_status"`
	Services      map[string]ServiceHealth `json:"services"`
	CheckedAt     time.Time                `json:"checked_at"`
	Duration      time.Duration            `json:"duration"`
	Summary       HealthSummary            `json:"summary"`
}

HealthData contains health check results.

type HealthSnapshot 

type HealthSnapshot struct {
	Timestamp      time.Time `json:"timestamp"`
	OverallStatus  string    `json:"overall_status"`
	HealthyCount   int       `json:"healthy_count"`
	DegradedCount  int       `json:"degraded_count"`
	UnhealthyCount int       `json:"unhealthy_count"`
}

HealthSnapshot is a timestamped health snapshot.

type HealthSummary 

type HealthSummary struct {
	Healthy   int `json:"healthy"`
	Degraded  int `json:"degraded"`
	Unhealthy int `json:"unhealthy"`
	Unknown   int `json:"unknown"`
	Total     int `json:"total"`
}

HealthSummary provides count of services by status.

type HistogramDetail added in v1.2.0 

type HistogramDetail struct {
	Count     uint64            `json:"count"`
	Sum       float64           `json:"sum"`
	Mean      float64           `json:"mean"`
	StdDev    float64           `json:"std_dev"`
	Min       float64           `json:"min"`
	Max       float64           `json:"max"`
	P50       float64           `json:"p50"`
	P90       float64           `json:"p90"`
	P95       float64           `json:"p95"`
	P99       float64           `json:"p99"`
	Buckets   map[string]uint64 `json:"buckets"`
	Exemplars []ExemplarInfo    `json:"exemplars"`
}

HistogramDetail contains histogram metric details.

type HistoryData 

type HistoryData struct {
	StartTime time.Time        `json:"start_time"`
	EndTime   time.Time        `json:"end_time"`
	Series    []TimeSeriesData `json:"series"`
}

HistoryData contains historical dashboard data.

type IngestGateFunc added in v1.11.0 

type IngestGateFunc func() bool

IngestGateFunc reports whether spans should be retained right now. It is called on the request path for every span, so it must be cheap and must not block. A nil gate means retain everything.

type MetricActivity 

type MetricActivity struct {
	Metric    string    `json:"metric"`
	Action    string    `json:"action"`
	Value     float64   `json:"value"`
	Timestamp time.Time `json:"timestamp"`
}

MetricActivity represents recent metric activity.

type MetricDetail added in v1.2.0 

type MetricDetail struct {
	Name        string            `json:"name"`
	Type        string            `json:"type"`
	Description string            `json:"description"`
	Unit        string            `json:"unit"`
	Namespace   string            `json:"namespace"`
	Subsystem   string            `json:"subsystem"`
	Labels      map[string]string `json:"labels"`
	ConstLabels map[string]string `json:"const_labels"`
	Value       any               `json:"value"`
	Created     time.Time         `json:"created"`
	Updated     time.Time         `json:"updated"`

	// Type-specific data
	CounterData   *CounterDetail   `json:"counter_data,omitempty"`
	GaugeData     *GaugeDetail     `json:"gauge_data,omitempty"`
	HistogramData *HistogramDetail `json:"histogram_data,omitempty"`
	TimerData     *TimerDetail     `json:"timer_data,omitempty"`
}

MetricDetail contains detailed information about a single metric.

type MetricEntry 

type MetricEntry struct {
	Name      string    `json:"name"`
	Type      string    `json:"type"`
	Value     any       `json:"value"`
	Tags      []string  `json:"tags,omitempty"`
	Timestamp time.Time `json:"timestamp"`
}

MetricEntry represents a single metric entry.

type MetricsData 

type MetricsData struct {
	Timestamp time.Time      `json:"timestamp"`
	Metrics   map[string]any `json:"metrics"`
	Stats     MetricsStats   `json:"stats"`
}

MetricsData contains current metrics information.

type MetricsReport 

type MetricsReport struct {
	Timestamp      time.Time          `json:"timestamp"`
	TotalMetrics   int                `json:"total_metrics"`
	MetricsByType  map[string]int     `json:"metrics_by_type"`
	Collectors     []CollectorInfo    `json:"collectors"`
	Stats          MetricsReportStats `json:"stats"`
	TopMetrics     []MetricEntry      `json:"top_metrics"`
	RecentActivity []MetricActivity   `json:"recent_activity"`
}

MetricsReport contains comprehensive metrics information.

type MetricsReportStats 

type MetricsReportStats struct {
	CollectionInterval time.Duration `json:"collection_interval"`
	LastCollection     time.Time     `json:"last_collection"`
	TotalCollections   int64         `json:"total_collections"`
	ErrorCount         int           `json:"error_count"`
	Uptime             time.Duration `json:"uptime"`
}

MetricsReportStats contains statistics about metrics.

type MetricsStats 

type MetricsStats struct {
	TotalMetrics int       `json:"total_metrics"`
	Counters     int       `json:"counters"`
	Gauges       int       `json:"gauges"`
	Histograms   int       `json:"histograms"`
	LastUpdate   time.Time `json:"last_update"`
}

MetricsStats contains metrics statistics.

type OnCollectFunc added in v1.2.0 

type OnCollectFunc func(overview *OverviewData, health *HealthData, metrics *MetricsData)

OnCollectFunc is called after each data collection cycle with the collected data.

type OnTraceAddedFunc added in v1.2.0 

type OnTraceAddedFunc func(traceID string, spanCount int)

OnTraceAddedFunc is called when a new span is added to the store.

type OverviewData 

type OverviewData struct {
	Timestamp       time.Time      `json:"timestamp"`
	OverallHealth   string         `json:"overall_health"`
	TotalServices   int            `json:"total_services"`
	HealthyServices int            `json:"healthy_services"`
	TotalMetrics    int            `json:"total_metrics"`
	Uptime          time.Duration  `json:"uptime"`
	Version         string         `json:"version"`
	Environment     string         `json:"environment"`
	Summary         map[string]any `json:"summary"`
}

OverviewData contains dashboard overview information.

type OverviewSnapshot 

type OverviewSnapshot struct {
	Timestamp    time.Time `json:"timestamp"`
	HealthStatus string    `json:"health_status"`
	ServiceCount int       `json:"service_count"`
	HealthyCount int       `json:"healthy_count"`
	MetricsCount int       `json:"metrics_count"`
}

OverviewSnapshot is a timestamped overview snapshot.

type ServiceDetail 

type ServiceDetail struct {
	Name            string         `json:"name"`
	Type            string         `json:"type"`
	Status          string         `json:"status"`
	Health          *ServiceHealth `json:"health,omitempty"`
	Metrics         map[string]any `json:"metrics"`
	Dependencies    []string       `json:"dependencies"`
	Configuration   map[string]any `json:"configuration,omitempty"`
	LastHealthCheck time.Time      `json:"last_health_check"`
	Uptime          time.Duration  `json:"uptime,omitempty"`
}

ServiceDetail contains detailed information about a specific service.

type ServiceHealth 

type ServiceHealth struct {
	Name      string         `json:"name"`
	Status    string         `json:"status"`
	Message   string         `json:"message"`
	Duration  time.Duration  `json:"duration"`
	Critical  bool           `json:"critical"`
	Timestamp time.Time      `json:"timestamp"`
	Details   map[string]any `json:"details,omitempty"`
}

ServiceHealth contains individual service health information.

type ServiceInfo 

type ServiceInfo struct {
	Name         string    `json:"name"`
	Type         string    `json:"type"`
	Status       string    `json:"status"`
	RegisteredAt time.Time `json:"registered_at,omitempty"` //nolint:modernize // omitempty intentional for API compat
}

ServiceInfo contains information about a registered service.

type SpanEventView added in v1.2.0 

type SpanEventView struct {
	Name       string            `json:"name"`
	Timestamp  time.Time         `json:"timestamp"`
	Attributes map[string]string `json:"attributes"`
}

SpanEventView is a display-friendly span event.

type SpanKind added in v1.2.0 

type SpanKind int

SpanKind represents the kind of span. 

const (
	SpanKindUnspecified SpanKind = iota
	SpanKindInternal
	SpanKindServer
	SpanKindClient
	SpanKindProducer
	SpanKindConsumer
)

type SpanStatus added in v1.2.0 

type SpanStatus int

SpanStatus represents the status of a span. 

const (
	SpanStatusUnset SpanStatus = iota
	SpanStatusOK
	SpanStatusError
)

type SpanView added in v1.2.0 

type SpanView struct {
	SpanID       string            `json:"span_id"`
	ParentSpanID string            `json:"parent_span_id,omitempty"`
	TraceID      string            `json:"trace_id"`
	Name         string            `json:"name"`
	Kind         SpanKind          `json:"kind"`
	Status       SpanStatus        `json:"status"`
	StartTime    time.Time         `json:"start_time"`
	EndTime      time.Time         `json:"end_time"`
	Duration     time.Duration     `json:"duration"`
	Attributes   map[string]string `json:"attributes"`
	Events       []SpanEventView   `json:"events"`
	HTTP         *HTTPExchange     `json:"http,omitempty"`

	// Computed display fields (populated by TraceStore.buildTraceDetail)
	Depth         int     `json:"depth"`
	OffsetPercent float64 `json:"offset_percent"`
	WidthPercent  float64 `json:"width_percent"`
}

SpanView is a display-friendly span with computed fields for waterfall rendering.

type TimeSeriesData 

type TimeSeriesData struct {
	Name        string      `json:"name"`
	Points      []DataPoint `json:"points"`
	Unit        string      `json:"unit,omitempty"`
	Aggregation string      `json:"aggregation,omitempty"`
}

TimeSeriesData contains time-series data.

type TimerDetail added in v1.2.0 

type TimerDetail struct {
	Count     uint64         `json:"count"`
	Sum       time.Duration  `json:"sum"`
	Mean      time.Duration  `json:"mean"`
	StdDev    time.Duration  `json:"std_dev"`
	Min       time.Duration  `json:"min"`
	Max       time.Duration  `json:"max"`
	P50       time.Duration  `json:"p50"`
	P95       time.Duration  `json:"p95"`
	P99       time.Duration  `json:"p99"`
	Exemplars []ExemplarInfo `json:"exemplars"`
}

TimerDetail contains timer metric details.

type TraceDetail added in v1.2.0 

type TraceDetail struct {
	TraceID   string        `json:"trace_id"`
	RootSpan  *SpanView     `json:"root_span"`
	Spans     []*SpanView   `json:"spans"`
	SpanCount int           `json:"span_count"`
	Duration  time.Duration `json:"duration"`
	Status    SpanStatus    `json:"status"`
	StartTime time.Time     `json:"start_time"`
	EndTime   time.Time     `json:"end_time"`
	Protocol  string        `json:"protocol"`
}

TraceDetail contains a full trace with all spans for the detail view.

type TraceFilter added in v1.2.0 

type TraceFilter struct {
	Search      string        `json:"search,omitempty"`
	Status      string        `json:"status,omitempty"`   // "ok", "error", "all"
	Protocol    string        `json:"protocol,omitempty"` // "REST", "WS", "SSE", "Event", "all"
	MinDuration time.Duration `json:"min_duration,omitempty"`
	Limit       int           `json:"limit,omitempty"`
	Offset      int           `json:"offset,omitempty"`
}

TraceFilter holds filtering options for trace queries.

type TraceStats added in v1.2.0 

type TraceStats struct {
	TotalTraces  int           `json:"total_traces"`
	AvgDuration  time.Duration `json:"avg_duration"`
	ErrorRate    float64       `json:"error_rate"`
	ActiveTraces int           `json:"active_traces"`
}

TraceStats holds aggregate trace statistics.

type TraceStore added in v1.2.0 

type TraceStore struct {
	// contains filtered or unexported fields
}

TraceStore is a thread-safe in-memory store for completed traces. It organises spans by TraceID and supports listing, filtering, and detail retrieval for the dashboard tracing UI.

func NewTraceStore added in v1.2.0 

func NewTraceStore(maxTraces int, retention time.Duration, opts ...TraceStoreOption) *TraceStore

NewTraceStore creates a new TraceStore. maxTraces controls the maximum number of distinct traces kept in memory. retention controls the maximum age of traces before they are evicted.

func (*TraceStore) AddSpan added in v1.2.0 

func (ts *TraceStore) AddSpan(span *SpanView)

AddSpan adds a completed span to the store, grouping it under its TraceID.

func (*TraceStore) Close added in v1.11.0 

func (ts *TraceStore) Close()

Close stops the drain goroutine. It is safe to call more than once, and safe to call on a store that never had a callback registered.

func (*TraceStore) DroppedNotifications added in v1.11.0 

func (ts *TraceStore) DroppedNotifications() uint64

DroppedNotifications returns the number of trace-added events discarded because the drain queue was full.

func (*TraceStore) DroppedSpans added in v1.11.0 

func (ts *TraceStore) DroppedSpans() uint64

DroppedSpans returns the number of spans refused because their trace had already reached maxSpansPerTrace.

func (*TraceStore) GetTrace added in v1.2.0 

func (ts *TraceStore) GetTrace(traceID string) *TraceDetail

GetTrace returns the full detail for a single trace, including computed waterfall display fields.

func (*TraceStore) LastAccessed added in v1.11.0 

func (ts *TraceStore) LastAccessed() time.Time

LastAccessed reports when the dashboard was last used, or the zero time if it never has been. A TTL gate built on this is therefore shut at startup.

func (*TraceStore) ListTraces added in v1.2.0 

func (ts *TraceStore) ListTraces(filter TraceFilter) ([]TraceSummary, TraceStats)

ListTraces returns a filtered, paginated list of trace summaries plus aggregate statistics.

func (*TraceStore) MarkAccessed added in v1.11.0 

func (ts *TraceStore) MarkAccessed()

MarkAccessed records that the dashboard was used just now. It is safe to call concurrently and is cheap enough for the request path.

func (*TraceStore) SetIngestGate added in v1.11.0 

func (ts *TraceStore) SetIngestGate(fn IngestGateFunc)

SetIngestGate installs the predicate that decides whether spans are retained. Pass nil to retain everything.

func (*TraceStore) SetOnTraceAdded added in v1.2.0 

func (ts *TraceStore) SetOnTraceAdded(fn OnTraceAddedFunc)

SetOnTraceAdded registers a callback invoked when a new span is added. The callback runs on a single drain goroutine, started on first use, and is never invoked from the request path. Call Close to stop that goroutine.

type TraceStoreOption added in v1.11.0 

type TraceStoreOption func(*TraceStore)

TraceStoreOption configures a TraceStore at construction.

func WithMaxSpansPerTrace added in v1.11.0 

func WithMaxSpansPerTrace(n int) TraceStoreOption

WithMaxSpansPerTrace caps how many spans a single trace retains. Spans arriving after the cap are dropped and counted. Values below 1 are ignored.

type TraceSummary added in v1.2.0 

type TraceSummary struct {
	TraceID      string        `json:"trace_id"`
	RootSpanName string        `json:"root_span_name"`
	SpanCount    int           `json:"span_count"`
	Duration     time.Duration `json:"duration"`
	Status       SpanStatus    `json:"status"`
	StartTime    time.Time     `json:"start_time"`
	Protocol     string        `json:"protocol"` // REST, WS, SSE, Event, Internal
}

TraceSummary is a condensed representation of a complete trace for list views.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.