monitoredunits

package
v0.0.776 Latest Latest
Warning

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

Go to latest
Published: Nov 19, 2026 License: Apache-2.0 Imports: 4 Imported by: 0

Documentation

Overview

Package monitoredunits holds the wire types of the monitored units message: a sensor reports which units (a pod, later a VM or another kind) it monitors, and from when to when. The consumer builds monitoring coverage from it.

The message is JSON. Wire contract and rules: docs/features/monitored-units.md

Index

Constants

View Source
const SchemaVersion = 1

SchemaVersion is the current value of Message.SchemaVersion. It is raised only by a change that breaks an existing field. A new optional field does not raise it.

Variables

This section is empty.

Functions

This section is empty.

Types

type Entry

type Entry struct {
	Type   EntryType `json:"type"`
	Reason Reason    `json:"reason"`
	// Unit is the monitored unit. A stop entry carries only Kind and ID.
	Unit Unit `json:"unit"`
	// MonitoredFrom is when the sensor started to monitor the unit. Set on a
	// start entry.
	MonitoredFrom *time.Time `json:"monitoredFrom,omitempty"`
	// MonitoredUntil is when the sensor stopped monitoring the unit. Set on a
	// stop entry.
	MonitoredUntil *time.Time `json:"monitoredUntil,omitempty"`
	// CI is the CI identity that the sensor reports about itself. Nil when the
	// sensor does not know it. See armotypes.CIIdentity.
	CI *armotypes.CIIdentity `json:"ci,omitempty"`
}

Entry is the start or the stop of the monitoring of one unit.

type EntryType

type EntryType string

EntryType says whether an entry starts or stops the monitoring of a unit.

const (
	EntryTypeStart EntryType = "start"
	EntryTypeStop  EntryType = "stop"
)

type K8sPodAttributes

type K8sPodAttributes struct {
	PodName   string `json:"podName"`
	Namespace string `json:"namespace"`
	// Labels holds the labels of the pod.
	Labels map[string]string `json:"labels,omitempty"`
	// WorkloadKind and WorkloadName name the pod's owner workload, as the sensor
	// resolves it. For a pod with no owner they name the pod itself.
	WorkloadKind string `json:"workloadKind,omitempty"`
	WorkloadName string `json:"workloadName,omitempty"`
	// WorkloadLabels holds the labels of the owner workload. Nil when the
	// workload is the pod itself. Non-nil whenever it is not, also when the
	// owner has no labels: an empty map is sent as {}. Same rule as
	// armotypes.RuntimeAlertK8sDetails.WorkloadLabels.
	WorkloadLabels map[string]string `json:"workloadLabels,omitzero"`
}

K8sPodAttributes is Unit.Attributes for UnitKindK8sPod.

type Message

type Message struct {
	SchemaVersion int `json:"schemaVersion"`
	// AgentVersion is the version of the sensor.
	AgentVersion string `json:"agentVersion"`
	// AgentStartedAt is when this sensor process started. It identifies the
	// sensor run: a change tells the consumer that the sensor restarted.
	AgentStartedAt time.Time `json:"agentStartedAt"`
	// ClusterName is the Kubernetes cluster of the sensor. A sensor in a cluster
	// must set it: it is the only cluster identity that the consumer uses, and a
	// k8s-pod entry of a message without it is dropped. Empty when the sensor
	// does not run in a cluster.
	ClusterName string `json:"clusterName,omitempty"`
	// Node is the node name in a cluster, or the host name elsewhere.
	Node string `json:"node"`
	// CloudMetadata describes the machine that the sensor runs on (provider,
	// account, region, instance). Nil when the sensor does not report it.
	CloudMetadata *armotypes.CloudMetadata `json:"cloudMetadata,omitempty"`
	// SentAt is when the message was sent.
	SentAt time.Time `json:"sentAt"`
	// IntervalSeconds is the interval of the periodic list, as configured on
	// this sensor.
	IntervalSeconds int `json:"intervalSeconds"`
	// Entries holds start and stop entries. It may be empty. It is always sent
	// as a list: a nil slice is encoded as [].
	Entries []Entry `json:"entries"`
	// MonitoredUnitIDs holds the IDs of all units that this sensor run monitors
	// now. It is set only in a periodic list. A nil slice means that the message
	// is not a periodic list, and the field is not sent. A non-nil empty slice
	// means that the sensor is alive and monitors nothing, and is sent as [].
	// Use IsPeriodicList and SetMonitoredUnitIDs.
	MonitoredUnitIDs []string `json:"monitoredUnitIds,omitzero"`
}

Message is one monitored units message. A sensor sends one per machine: when monitoring of a unit starts or stops, and as a periodic list.

func (*Message) IsPeriodicList

func (m *Message) IsPeriodicList() bool

IsPeriodicList reports whether the message carries the list of monitored unit IDs.

func (Message) MarshalJSON

func (m Message) MarshalJSON() ([]byte, error)

MarshalJSON encodes a nil Entries as [] and not as null, because the field is a list on the wire also when it is empty.

func (*Message) SetMonitoredUnitIDs

func (m *Message) SetMonitoredUnitIDs(ids []string)

SetMonitoredUnitIDs makes the message a periodic list. A nil or empty ids is stored as an empty list, which is sent as [].

type Reason

type Reason string

Reason says why monitoring of a unit started or stopped.

It is a plain string on purpose: a consumer keeps a value it does not know, and does not reject the entry.

const (

	// ReasonUnitStarted: the sensor saw the unit start.
	ReasonUnitStarted Reason = "unit-started"
	// ReasonAgentStarted: the unit was already running when the sensor started
	// or restarted.
	ReasonAgentStarted Reason = "agent-started"

	// ReasonUnitEnded: the unit ended while it was monitored. The normal end.
	ReasonUnitEnded Reason = "unit-ended"
	// ReasonAgentStopping: the sensor shuts down while the unit still runs.
	ReasonAgentStopping Reason = "agent-stopping"

	// ReasonTimeout: the consumer closed the period, because the unit left the
	// periodic lists or the lists stopped arriving.
	ReasonTimeout Reason = "timeout"
)

type Unit

type Unit struct {
	Kind UnitKind `json:"kind"`
	// ID is unique for the kind. For UnitKindK8sPod it is the pod UID.
	ID string `json:"id"`
	// StartedAt is when the unit started. Set on a start entry.
	StartedAt *time.Time `json:"startedAt,omitempty"`
	// Attributes describes the unit. Set on a start entry. Its shape depends on
	// Kind, so it is kept as raw JSON: a consumer can store and forward the
	// attributes of a kind it does not know. For UnitKindK8sPod use
	// K8sPodAttributes.
	Attributes json.RawMessage `json:"attributes,omitempty"`
}

Unit identifies a monitored unit.

func NewK8sPodUnit

func NewK8sPodUnit(podUID string, startedAt time.Time, attrs K8sPodAttributes) (Unit, error)

NewK8sPodUnit builds the unit of a start entry for a pod.

func (Unit) K8sPodAttributes

func (u Unit) K8sPodAttributes() (*K8sPodAttributes, error)

K8sPodAttributes decodes the attributes of a UnitKindK8sPod unit. It returns an error for another kind, and for a unit with no attributes (a stop entry), also when the attributes are a JSON null.

type UnitKind

type UnitKind string

UnitKind names the kind of a monitored unit. It selects the shape of Unit.Attributes. A plain string, for the same reason as Reason.

const (
	// UnitKindK8sPod is a Kubernetes pod. Unit.ID is the pod UID, and
	// Unit.Attributes is a K8sPodAttributes.
	UnitKindK8sPod UnitKind = "k8s-pod"
)

Jump to

Keyboard shortcuts

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