redmetrics

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

type Clock interface {
	Now() time.Time
}

type Config struct {
	// ConnTTL is how long a connection's state survives without an observation.
	//
	// It is a leak backstop rather than the mechanism that reclaims connections. The
	// probe attaches to tcp_close, so a socket going away says so and its state is
	// released at that point; this bounds only the entries whose close was never
	// seen -- an event lost to a full ring buffer, or a socket already open when the
	// probe attached.
	//
	// Which is why it can be generous, and why it should be. When idleness was the
	// only available death signal this had to be short enough to bound the table,
	// and a short one is actively destructive: a gRPC stream or an HTTP keep-alive
	// connection quiet for longer than the TTL was swept, then decoded again from
	// the middle when it resumed -- where nothing parses, so it landed opaque -- or,
	// if its next syscall was a send, classified outbound and ignored for the rest
	// of its life. Neither is a small loss on a node serving long-lived connections.
	//
	// Keep it at or above RequestTTL. Below it, a connection can be reclaimed while
	// it still holds requests the sweep has not yet had cause to file, and those
	// requests are lost rather than counted unanswered.
	ConnTTL time.Duration

	// MaxConnections caps concurrently tracked connections. Beyond it, new
	// connections are dropped rather than tracked -- the alternative is an
	// unbounded map on a DaemonSet that shares a node with the workloads it
	// measures.
	//
	// Outbound connections count against it too, even though nothing is measured
	// about them. The cap bounds memory, and an outbound entry occupies the table
	// exactly as an inbound one does; excluding them would make the number stop
	// describing the thing it exists to bound. On a node whose outbound churn is
	// large enough to fill the table this does cost inbound coverage, which the
	// one-shot capacity log is there to make visible.
	//
	// What the cap holds changed with the close probe. It used to hold every
	// connection seen within ConnTTL, which on a node churning short-lived
	// connections is overwhelmingly sockets the kernel had already freed -- so the
	// table filled with corpses and refused live connections at a fraction of the
	// offered rate. It now holds connections that are actually open, which is a
	// number set by concurrency rather than by rate.
	MaxConnections int

	// RequestTTL is how long a request may stay outstanding before it is filed as
	// unanswered: counted in request_count, in no latency bucket, and not in
	// error_count.
	//
	// It is a deadline on the agent's patience, not a statement about the service.
	// A request answered after it has been swept is not filed twice -- the response
	// finds nothing outstanding and is dropped -- so raising this trades memory for
	// the latency of genuinely slow requests being measured rather than merely
	// counted, and lowering it trades the other way.
	//
	// It applies only to a request left outstanding on a connection that stays open.
	// A connection that closes settles everything it was still holding at the close,
	// so this does not have to be long enough to cover a client that hangs up.
	RequestTTL time.Duration

	// MaxInFlightRequests caps outstanding requests across all connections. A
	// request arriving with no room takes its connection opaque; see
	// startRequestLocked for why the connection cannot simply skip it.
	MaxInFlightRequests int

	// MaxBufferedBytes caps the bytes held over across socket events, across all
	// connections, for units that arrived split. It exists because the per-buffer
	// cap alone does not bound the agent: MaxConnections connections each holding
	// two halves of one legitimately-split frame is a ceiling in the gigabytes, on
	// a DaemonSet that shares a node with the workloads it measures.
	//
	// A connection that cannot get room takes itself opaque rather than resuming
	// from the wrong offset, so exhausting this degrades coverage into conn_count
	// instead of degrading the node.
	MaxBufferedBytes int
}

type ContainerKey struct {
	PodName       string
	PodNamespace  string
	PodUID        string
	ContainerName string
}

type PodLookup interface {
	GetPodByIP(ip netaddr.IP) (*corev1.Pod, bool)
}

type SocketEvent struct {
	// SocketCookie identifies the socket the bytes crossed. It is opaque and only
	// unique among sockets alive at the same instant: the kernel recycles the
	// structure it derives from, so it must be paired with the connection's
	// four-tuple before two observations can be called the same connection.
	SocketCookie uint64

	// Path is the syscall the bytes crossed on.
	Path SyscallPath

	// LocalAddr and LocalPort are this node's side of the connection. For an
	// inbound service request these are the served pod and the port it listens on,
	// which is what attribution keys off.
	LocalAddr netip.Addr
	LocalPort uint16

	// RemoteAddr and RemotePort are the peer's side of the connection. They are
	// recorded but never aggregated by: keying on the caller is exactly what would
	// make the in-memory map grow with caller cardinality.
	RemoteAddr netip.Addr
	RemotePort uint16

	// TrueLen is the length the syscall actually carried, whatever prefix of it the
	// probe copied. The decoder walks by this rather than by len(Payload), which is
	// what lets a body larger than the copy limit be stepped over without losing the
	// stream position.
	TrueLen uint32

	// Payload is the prefix of those bytes the probe copied, at most PayloadCap of
	// them and often fewer. It is a copy rather than a view of the ring buffer
	// sample, which the kernel reuses the moment the record is released.
	//
	// It may be shorter than TrueLen and may be empty. A decoder must treat a
	// boundary that falls beyond it as unreadable rather than as absent.
	Payload []byte

	// Timestamp is when the kernel saw the call, already mapped onto wall clock.
	Timestamp time.Time
}

type SyscallPath uint8

type SystemClock struct{}