Documentation
¶
Overview ¶
Package native implements three of the machine-telemetry package's routes in the package itself: the administrator's hourly traffic series and user traffic ranking, and the dashboard. The traffic routes read the kernel's traffic log through the read-only kernel view kapi_traffic_log_v1 (the user, bytes, rate and time of each node traffic report in v2_server_log), and users' e-mail addresses through kapi_user_directory_v1. The kernel writes the log when a node reports traffic; the package never writes it. The dashboard is the snapshot the kernel caches, read through KernelTelemetry (kernel.telemetry.dashboard.v1); without that contract it stays legacy. Responses are byte-compatible with the legacy handlers (internal/tests/machinetelemetrycompat).
Two routes are kernel-owned; the reasons are in the host's bridgedRoutes (packages/machine-telemetry/control/service.go): the system information (the kernel binary's build metadata) and the monitoring WebSocket.
Index ¶
- Constants
- Variables
- type Dashboard
- type HourlyTraffic
- type NodeServices
- type Service
- func (s *Service) Dashboard(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
- func (s *Service) Handlers() map[string]pluginhostsdk.NativeHandler
- func (s *Service) HourlyTraffic(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
- func (s *Service) NodeServices(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
- func (s *Service) UserTrafficRanking(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
- type ServiceUnit
- type ServicesSummary
- type Telemetry
- type TrafficLogMeta
- type UserTrafficRank
Constants ¶
const ( // PackageID is the package's id. PackageID = "machine-telemetry" // NodesRoute is the control route that serves the table: the kernel // matches the request path against it and dispatches the request with // NodesRouteID. NodesRoute = "/api/v3/plugins/machine-telemetry/nodes/*" )
The per-node systemd services table (docs/architecture/package-reports.md): GET /api/v3/plugins/machine-telemetry/nodes/:id/services, read-only. The Agent's collector reports the table as a systemd.services package report; the kernel sanitizes and keeps the latest one per node, which the package reads through kapi_package_report_v1. Whether the node is enabled, and its unit globs, come from the package's Agent installation configuration, read through kapi_plugin_configuration_v1.
const DashboardRouteID = "telemetry.admin.dashboard.get"
DashboardRouteID is GET /api/v2/admin/dashboard.
Variables ¶
var NodesRouteID = controlRouteID(NodesRoute)
NodesRouteID is the route id the kernel gives NodesRoute: the package id, ".control." and the hex SHA-256 of the package id, a NUL byte and the route (the kernel's service.PluginControlBridgeRouteID).
Functions ¶
This section is empty.
Types ¶
type Dashboard ¶
type Dashboard struct {
TotalUsers int64 `json:"total_users"`
ActiveUsers int64 `json:"active_users"`
ExpiredUsers int64 `json:"expired_users"`
BannedUsers int64 `json:"banned_users"`
TodayNewUsers int64 `json:"today_new_users"`
TotalOrders int64 `json:"total_orders"`
PendingOrders int64 `json:"pending_orders"`
PaidOrders int64 `json:"paid_orders"`
TotalRevenue int64 `json:"total_revenue"`
MonthlyIncome int64 `json:"monthly_income"`
TodayIncome int64 `json:"today_income"`
TotalNodes int64 `json:"total_nodes"`
ActiveNodes int64 `json:"active_nodes"`
OnlineUsers int64 `json:"online_users"`
TotalTrafficUsed int64 `json:"total_traffic_used"`
TodayTraffic int64 `json:"today_traffic"`
CachedAt time.Time `json:"cached_at"`
}
Dashboard is the dashboard snapshot, with the fields and tags of the kernel's service.DashboardStats.
type HourlyTraffic ¶
HourlyTraffic is one hour of the series, as the kernel's service.HourlyTraffic.
type NodeServices ¶ added in v4.2.0
type NodeServices struct {
NodeID uint64 `json:"node_id"`
// Enabled is the node's setting; without it the collector is off and
// the table is empty.
Enabled bool `json:"enabled"`
// Include and Exclude are the node's unit globs.
Include []string `json:"include"`
Exclude []string `json:"exclude"`
// Reported is true once the node has a stored report.
Reported bool `json:"reported"`
// Supported and UnsupportedReason are the report's: false, with a
// reason, on a node without systemd or cgroup v2.
Supported bool `json:"supported"`
UnsupportedReason string `json:"unsupported_reason"`
// Stale is true when the report is older than 25 minutes.
Stale bool `json:"stale"`
ObservedAt *time.Time `json:"observed_at"`
Version string `json:"version"`
WindowSeconds int `json:"window_seconds"`
Summary ServicesSummary `json:"summary"`
Units []ServiceUnit `json:"units"`
}
NodeServices is the route's answer.
type Service ¶
type Service struct {
// Open returns the package's storage connection, on which the
// kapi_traffic_log_v1 and kapi_user_directory_v1 views are visible.
Open func(ctx context.Context) (*gorm.DB, error)
// Telemetry is the kernel's KernelTelemetry; without it the dashboard
// has no native handler and stays legacy.
Telemetry Telemetry
// Now defaults to time.Now. The hourly buckets are in the local time
// zone, as the kernel's; the kernel passes its TZ to the host.
Now func() time.Time
}
Service holds what the native routes need.
func (*Service) Dashboard ¶
func (s *Service) Dashboard(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
Dashboard is GET /api/v2/admin/dashboard: the snapshot the kernel caches for 60 seconds, read through KernelTelemetry.GetDashboard. The kernel keeps the one cache both modes read, so a native answer carries the snapshot and cached_at the legacy handler would, and refresh=true (only that exact value, as gin's c.Query) rebuilds it. The online users arrive as a count; the set stays in the kernel.
func (*Service) Handlers ¶
func (s *Service) Handlers() map[string]pluginhostsdk.NativeHandler
Handlers returns the native handlers by route id.
func (*Service) HourlyTraffic ¶
func (s *Service) HourlyTraffic(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
HourlyTraffic is GET /api/v2/admin/traffic/hourly: the traffic of each of the last hours (default 24, at most 720), of all users or of user_id, and when traffic was last reported.
func (*Service) NodeServices ¶ added in v4.2.0
func (s *Service) NodeServices(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
NodeServices is GET /api/v3/plugins/machine-telemetry/nodes/:id/services: the node's latest systemd services table, for administrators.
func (*Service) UserTrafficRanking ¶
func (s *Service) UserTrafficRanking(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
UserTrafficRanking is GET /api/v2/admin/traffic/user-ranking: users by their traffic over the last hours (default 24), the top limit (default 20, at most 200). With include_zero_users it ranks every user, those without traffic too (at most 1000).
type ServiceUnit ¶ added in v4.2.0
type ServiceUnit struct {
Name string `json:"name"`
ActiveState string `json:"active_state"`
SubState string `json:"sub_state"`
CPUAvgPercent float64 `json:"cpu_avg_percent"`
CPUPeakPercent float64 `json:"cpu_peak_percent"`
MemoryBytes uint64 `json:"memory_bytes"`
MemoryPeakBytes uint64 `json:"memory_peak_bytes"`
}
ServiceUnit is one unit of the table.
type ServicesSummary ¶ added in v4.2.0
type ServicesSummary struct {
Total int `json:"total"`
Failed int `json:"failed"`
Active int `json:"active"`
Inactive int `json:"inactive"`
}
ServicesSummary counts the units by ActiveState. Units activating, deactivating or reloading count only in Total.
type Telemetry ¶
type Telemetry interface {
GetDashboard(ctx context.Context, in *kerneltelemetryv1.GetDashboardRequest, opts ...grpc.CallOption) (*kerneltelemetryv1.GetDashboardResponse, error)
}
Telemetry is the kernel's KernelTelemetry as the dashboard reads it (kernel.telemetry.dashboard.v1).
type TrafficLogMeta ¶
type TrafficLogMeta struct {
LatestLogAt int64 `json:"latest_log_at"`
}
TrafficLogMeta is the kernel's service.TrafficLogMeta.
type UserTrafficRank ¶
type UserTrafficRank struct {
UserID uint `json:"user_id"`
Email string `json:"email"`
Traffic int64 `json:"traffic"`
}
UserTrafficRank is one ranking entry, as the kernel's service.UserTrafficRank.