wire

package module
v0.0.0-...-3efa1df Latest Latest
Warning

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

 Go to latest Published: Aug 3, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	AggAvg    = "avg"
	AggAvgMax = "avg+max"
	AggMax    = "max"
	AggLast   = "last"
	AggDelta  = "delta"
)

Valid values for CatalogEntry.Agg. avg collapses a window to its mean, avg+max emits both the mean and a ".max" companion key, max keeps the window peak (so a transient spike is not averaged away), last keeps the most recent sample (cumulative counters and static gauges), delta is reserved for future use.

View Source 
const (
	WildcardMount  = "mount"
	WildcardDev    = "dev"
	WildcardIface  = "iface"
	WildcardGPU    = "gpu"
	WildcardTarget = "target"
)

Valid values for CatalogEntry.Wildcard.

Variables

View Source 
var (
	EventType_name = map[int32]string{
		0:  "EVENT_TYPE_UNSPECIFIED",
		1:  "EVENT_TYPE_INSTALL",
		2:  "EVENT_TYPE_ENROLL",
		3:  "EVENT_TYPE_BOOT",
		4:  "EVENT_TYPE_UNEXPECTED_REBOOT",
		5:  "EVENT_TYPE_REBOOT_SCHEDULED",
		6:  "EVENT_TYPE_CLEAN_SHUTDOWN",
		7:  "EVENT_TYPE_OOM_KILL",
		8:  "EVENT_TYPE_FS_READONLY",
		9:  "EVENT_TYPE_DISK_FULL",
		10: "EVENT_TYPE_CLOCK_SKEW_DETECTED",
		11: "EVENT_TYPE_AGENT_UPDATE_STARTED",
		12: "EVENT_TYPE_AGENT_UPDATE_APPLIED",
		13: "EVENT_TYPE_AGENT_UPDATE_FAILED",
		14: "EVENT_TYPE_CONFIG_APPLIED",
		15: "EVENT_TYPE_CONFIG_ERROR",
		16: "EVENT_TYPE_BUFFER_OVERFLOW",
		17: "EVENT_TYPE_UNINSTALL",
		18: "EVENT_TYPE_UNIT_FAILED",
		19: "EVENT_TYPE_UNIT_RESTARTED",
		20: "EVENT_TYPE_UNIT_FLAPPING",
	}
	EventType_value = map[string]int32{
		"EVENT_TYPE_UNSPECIFIED":          0,
		"EVENT_TYPE_INSTALL":              1,
		"EVENT_TYPE_ENROLL":               2,
		"EVENT_TYPE_BOOT":                 3,
		"EVENT_TYPE_UNEXPECTED_REBOOT":    4,
		"EVENT_TYPE_REBOOT_SCHEDULED":     5,
		"EVENT_TYPE_CLEAN_SHUTDOWN":       6,
		"EVENT_TYPE_OOM_KILL":             7,
		"EVENT_TYPE_FS_READONLY":          8,
		"EVENT_TYPE_DISK_FULL":            9,
		"EVENT_TYPE_CLOCK_SKEW_DETECTED":  10,
		"EVENT_TYPE_AGENT_UPDATE_STARTED": 11,
		"EVENT_TYPE_AGENT_UPDATE_APPLIED": 12,
		"EVENT_TYPE_AGENT_UPDATE_FAILED":  13,
		"EVENT_TYPE_CONFIG_APPLIED":       14,
		"EVENT_TYPE_CONFIG_ERROR":         15,
		"EVENT_TYPE_BUFFER_OVERFLOW":      16,
		"EVENT_TYPE_UNINSTALL":            17,
		"EVENT_TYPE_UNIT_FAILED":          18,
		"EVENT_TYPE_UNIT_RESTARTED":       19,
		"EVENT_TYPE_UNIT_FLAPPING":        20,
	}
)

Enum value maps for EventType.

View Source 
var File_wire_proto protoreflect.FileDescriptor

Functions

func CatalogVersion 

func CatalogVersion() int

CatalogVersion returns the version of the embedded catalog.

func Validate 

func Validate() error

Validate checks the embedded catalog for internal consistency. It runs at package init and is exported so contract tests can assert it directly.

Types

type CatalogEntry 

type CatalogEntry struct {
	// Key is the metric key. For wildcard entries it contains the placeholder
	// segment literally, e.g. "sys.disk.{mount}.used_pct".
	Key string `json:"key"`
	// Unit is a normalized unit token, e.g. "percent", "bytes", "seconds",
	// "count", "float", "bytes_per_second", "per_second".
	Unit string `json:"unit"`
	// Source is where the agent reads the value, e.g. "/proc/stat" or "self".
	Source string `json:"source"`
	// Agg is how per-sample values collapse into one report value. One of the
	// Agg* constants.
	Agg string `json:"agg"`
	// Wildcard names the placeholder segment for per-device keys, or is empty.
	// One of the Wildcard* constants.
	Wildcard string `json:"wildcard,omitempty"`
}

CatalogEntry describes one sys.* metric key.

func Catalog 

func Catalog() []CatalogEntry

Catalog returns a copy of all catalog entries in file order.

func Lookup 

func Lookup(key string) (CatalogEntry, bool)

Lookup returns the catalog entry for an exact key. Wildcard entries are keyed by their literal template (e.g. "sys.disk.{mount}.used_pct"); Lookup does not resolve a concrete key like "sys.disk./.used_pct" against a template.

type Event 

type Event struct {

	// UUIDv4. Dedupe anchor.
	EventId string `protobuf:"bytes,1,opt,name=event_id,json=eventId,proto3" json:"event_id,omitempty"`
	// Wall clock when the event occurred, milliseconds.
	OccurredAtUnixMs int64 `protobuf:"varint,2,opt,name=occurred_at_unix_ms,json=occurredAtUnixMs,proto3" json:"occurred_at_unix_ms,omitempty"`
	// Event type. An unknown enum value is dropped by the server plus counted.
	Type EventType `protobuf:"varint,3,opt,name=type,proto3,enum=livck.wire.v1.EventType" json:"type,omitempty"`
	// Type-validated metadata. reason, if present, is capped at 200 chars.
	Meta map[string]string `` /* 135-byte string literal not displayed */
	// contains filtered or unexported fields
}

Event is a discrete lifecycle or health signal. Dedupe anchor is event_id; pulse sets the dedupe key only after a successful produce (mark-after-deliver).

func (*Event) Descriptor deprecated 

func (*Event) Descriptor() ([]byte, []int)

Deprecated: Use Event.ProtoReflect.Descriptor instead.

func (*Event) GetEventId 

func (x *Event) GetEventId() string

func (*Event) GetMeta 

func (x *Event) GetMeta() map[string]string

func (*Event) GetOccurredAtUnixMs 

func (x *Event) GetOccurredAtUnixMs() int64

func (*Event) GetType 

func (x *Event) GetType() EventType

func (*Event) ProtoMessage 

func (*Event) ProtoMessage()

func (*Event) ProtoReflect 

func (x *Event) ProtoReflect() protoreflect.Message

func (*Event) Reset 

func (x *Event) Reset()

func (*Event) String 

func (x *Event) String() string

type EventType 

type EventType int32

EventType is the closed event catalog. Adding a value is additive; removing or renumbering is breaking. Value 0 is the proto3 default: an agent that sends a type the server does not know maps to UNSPECIFIED and the event is dropped. 

const (
	EventType_EVENT_TYPE_UNSPECIFIED EventType = 0
	// Agent installed / enrolled. meta: version.
	EventType_EVENT_TYPE_INSTALL EventType = 1
	EventType_EVENT_TYPE_ENROLL  EventType = 2
	// First run after a reboot. meta: boot_id, downtime_seconds (optional).
	EventType_EVENT_TYPE_BOOT EventType = 3
	// Dirty boot: new boot_id with no clean_shutdown before it. meta:
	// downtime_seconds.
	EventType_EVENT_TYPE_UNEXPECTED_REBOOT EventType = 4
	// logind ScheduledShutdown change. meta: type (reboot/poweroff), at, reason.
	EventType_EVENT_TYPE_REBOOT_SCHEDULED EventType = 5
	// logind PrepareForShutdown plus delay-inhibitor lock. meta: type, reason
	// (optional).
	EventType_EVENT_TYPE_CLEAN_SHUTDOWN EventType = 6
	// OOM kill from /proc/vmstat delta. meta: count (v1 has no comm/process).
	EventType_EVENT_TYPE_OOM_KILL EventType = 7
	// Mount went read-only. meta: mount.
	EventType_EVENT_TYPE_FS_READONLY EventType = 8
	// Mount reached 100 percent. meta: mount.
	EventType_EVENT_TYPE_DISK_FULL EventType = 9
	// Clock skew above 30s detected. meta: skew_ms.
	EventType_EVENT_TYPE_CLOCK_SKEW_DETECTED EventType = 10
	// Self-updater. meta: from, to, error (optional).
	EventType_EVENT_TYPE_AGENT_UPDATE_STARTED EventType = 11
	EventType_EVENT_TYPE_AGENT_UPDATE_APPLIED EventType = 12
	EventType_EVENT_TYPE_AGENT_UPDATE_FAILED  EventType = 13
	// Config module. meta: version, error (optional).
	EventType_EVENT_TYPE_CONFIG_APPLIED EventType = 14
	EventType_EVENT_TYPE_CONFIG_ERROR   EventType = 15
	// RAM ring dropped reports. meta: dropped_count.
	EventType_EVENT_TYPE_BUFFER_OVERFLOW EventType = 16
	// livck-agent uninstall (best effort).
	EventType_EVENT_TYPE_UNINSTALL EventType = 17
	// systemd unit feature. meta: unit, exec_status (optional), n_restarts.
	EventType_EVENT_TYPE_UNIT_FAILED    EventType = 18
	EventType_EVENT_TYPE_UNIT_RESTARTED EventType = 19
	EventType_EVENT_TYPE_UNIT_FLAPPING  EventType = 20
)

func (EventType) Descriptor 

func (EventType) Descriptor() protoreflect.EnumDescriptor

func (EventType) Enum 

func (x EventType) Enum() *EventType

func (EventType) EnumDescriptor deprecated 

func (EventType) EnumDescriptor() ([]byte, []int)

Deprecated: Use EventType.Descriptor instead.

func (EventType) Number 

func (x EventType) Number() protoreflect.EnumNumber

func (EventType) String 

func (x EventType) String() string

func (EventType) Type 

func (EventType) Type() protoreflect.EnumType

type MetricBatch 

type MetricBatch struct {

	// Wire schema version. Must be 1 in v1. 0 => 400 UNSUPPORTED_SCHEMA_VERSION.
	// Deprecation band: pulse fully accepts {N, N-1}, accepts N-2..min_supported
	// with a warning, rejects below min_supported with 400. min_supported is
	// published in /v1/me and pulse config.
	SchemaVersion uint32 `protobuf:"varint,1,opt,name=schema_version,json=schemaVersion,proto3" json:"schema_version,omitempty"`
	// UUIDv4 batch idempotency key. Longer than 64 chars => 400
	// IDEMPOTENCY_KEY_TOO_LONG. Not UUIDv4 form => 400 MALFORMED_BODY.
	IdempotencyKey string `protobuf:"bytes,2,opt,name=idempotency_key,json=idempotencyKey,proto3" json:"idempotency_key,omitempty"`
	// Agent build version, e.g. "1.0.0".
	AgentVersion string `protobuf:"bytes,3,opt,name=agent_version,json=agentVersion,proto3" json:"agent_version,omitempty"`
	// Agent instance UUID from the state directory. Also the clone signal: pulse
	// compares it against the bound_instance_id in the token claims; a mismatch
	// is 409 INSTANCE_CONFLICT. No separate wire field carries the binding.
	AgentInstanceId string `protobuf:"bytes,4,opt,name=agent_instance_id,json=agentInstanceId,proto3" json:"agent_instance_id,omitempty"`
	// Wall clock send time, milliseconds. Used only to measure skew. |skew| > 5
	// min => 422 CLOCK_SKEW (batch is final; a 422 does not refresh liveness,
	// only a 2xx does). Sample timestamps live on each Report, not here.
	SentAtUnixMs int64 `protobuf:"varint,5,opt,name=sent_at_unix_ms,json=sentAtUnixMs,proto3" json:"sent_at_unix_ms,omitempty"`
	// Config version the agent currently has applied (echo). pulse piggybacks the
	// authoritative version in the response so the agent knows to pull config.
	AppliedConfigVersion uint32 `protobuf:"varint,6,opt,name=applied_config_version,json=appliedConfigVersion,proto3" json:"applied_config_version,omitempty"`
	// Host fingerprint: machine_id_hash, boot_id, cloud_instance_id (optional),
	// hostname. Sent on the first batch after start and whenever it changes.
	Fingerprint map[string]string `` /* 149-byte string literal not displayed */
	// 1..200 reports. More than one is backfill. Server enforces caps.max_reports.
	Reports []*Report `protobuf:"bytes,8,rep,name=reports,proto3" json:"reports,omitempty"`
	// 1..20 events, enforced server side (caps.max_events). Overflow is dropped
	// item-wise with reason "event_budget", never a batch reject.
	Events []*Event `protobuf:"bytes,9,rep,name=events,proto3" json:"events,omitempty"`
	// Empty for managed tokens (otherwise 400 SERVICE_ADDRESSING_FORBIDDEN).
	// Required and claims-matched for user tokens; empty for a user
	// token => 400 SERVICE_ADDRESSING_REQUIRED.
	ServicePublicId string `protobuf:"bytes,10,opt,name=service_public_id,json=servicePublicId,proto3" json:"service_public_id,omitempty"`
	// contains filtered or unexported fields
}

MetricBatch is one ingest request body: reports and/or events collected by an agent, sent to pulse. A batch may carry only events (empty reports) or only reports.

func (*MetricBatch) Descriptor deprecated 

func (*MetricBatch) Descriptor() ([]byte, []int)

Deprecated: Use MetricBatch.ProtoReflect.Descriptor instead.

func (*MetricBatch) GetAgentInstanceId 

func (x *MetricBatch) GetAgentInstanceId() string

func (*MetricBatch) GetAgentVersion 

func (x *MetricBatch) GetAgentVersion() string

func (*MetricBatch) GetAppliedConfigVersion 

func (x *MetricBatch) GetAppliedConfigVersion() uint32

func (*MetricBatch) GetEvents 

func (x *MetricBatch) GetEvents() []*Event

func (*MetricBatch) GetFingerprint 

func (x *MetricBatch) GetFingerprint() map[string]string

func (*MetricBatch) GetIdempotencyKey 

func (x *MetricBatch) GetIdempotencyKey() string

func (*MetricBatch) GetReports 

func (x *MetricBatch) GetReports() []*Report

func (*MetricBatch) GetSchemaVersion 

func (x *MetricBatch) GetSchemaVersion() uint32

func (*MetricBatch) GetSentAtUnixMs 

func (x *MetricBatch) GetSentAtUnixMs() int64

func (*MetricBatch) GetServicePublicId 

func (x *MetricBatch) GetServicePublicId() string

func (*MetricBatch) ProtoMessage 

func (*MetricBatch) ProtoMessage()

func (*MetricBatch) ProtoReflect 

func (x *MetricBatch) ProtoReflect() protoreflect.Message

func (*MetricBatch) Reset 

func (x *MetricBatch) Reset()

func (*MetricBatch) String 

func (x *MetricBatch) String() string

type Report 

type Report struct {

	// Wall clock at the END of the aggregation window, milliseconds. Sample time,
	// never send time: retried batches must not collapse.
	SampledAtUnixMs int64 `protobuf:"varint,1,opt,name=sampled_at_unix_ms,json=sampledAtUnixMs,proto3" json:"sampled_at_unix_ms,omitempty"`
	// Metric values. sys.* keys are the fixed catalog in catalog.json; custom.*
	// keys are rejected in v1. An empty map is allowed (event-carrier batch).
	Metrics map[string]float64 `` /* 143-byte string literal not displayed */
	// Report-level metadata, flat. Sent on change and on the first report after
	// start. Never carries ips_* (IP data is enroll-only). Optional key
	// window_samples marks a partial window.
	Meta map[string]string `` /* 135-byte string literal not displayed */
	// contains filtered or unexported fields
}

Report is one aggregation window of sys.* (and later custom.*) metrics.

func (*Report) Descriptor deprecated 

func (*Report) Descriptor() ([]byte, []int)

Deprecated: Use Report.ProtoReflect.Descriptor instead.

func (*Report) GetMeta 

func (x *Report) GetMeta() map[string]string

func (*Report) GetMetrics 

func (x *Report) GetMetrics() map[string]float64

func (*Report) GetSampledAtUnixMs 

func (x *Report) GetSampledAtUnixMs() int64

func (*Report) ProtoMessage 

func (*Report) ProtoMessage()

func (*Report) ProtoReflect 

func (x *Report) ProtoReflect() protoreflect.Message

func (*Report) Reset 

func (x *Report) Reset()

func (*Report) String 

func (x *Report) String() string

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.