native

package
v4.2.0 Latest Latest
Warning

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

Go to latest
Published: Oct 11, 2026 License: MIT Imports: 17 Imported by: 0

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

View Source
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.

View Source
const DashboardRouteID = "telemetry.admin.dashboard.get"

DashboardRouteID is GET /api/v2/admin/dashboard.

Variables

View Source
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

type HourlyTraffic struct {
	HourTs  int64 `json:"hour_ts"`
	Traffic int64 `json:"traffic"`
}

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

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

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

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.

Jump to

Keyboard shortcuts

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