Documentation
¶
Overview ¶
Package sessions maintains the in-memory active-session tracker updated by the session poll loop and snapshotted by the collector. The tracker exposes its map and per-session fields (the mutex stays unexported) so package server can orchestrate lock scope without a wall of getter methods; SnapshotSessions and UpdateLibraryLabels are the snapshot/apply helpers callers use for lock-safe access.
Exported symbols: State with ParseState and the StatePlaying / StateStopped / StatePaused / StateOther constants; the MaxSessionKeyLen / MaxTrackedSessions bounds; the Session DTO; the transcode classifiers TranscodeKind and SubtitleAction; and Tracker with NewTracker, Update, UpdateLibraryLabels, MarkAbsentStopped, SnapshotSessions, MediaResolved, Prune, and RunPruneLoop.
Index ¶
- Constants
- func SubtitleAction(ts *plexapi.WSTranscodeSession) string
- func TranscodeKind(ts *plexapi.WSTranscodeSession) string
- type Session
- type State
- type Tracker
- func (t *Tracker) MarkAbsentStopped(presentKeys []string)
- func (t *Tracker) MediaResolved(id, ratingKey string) bool
- func (t *Tracker) Prune()
- func (t *Tracker) RunPruneLoop(ctx context.Context)
- func (t *Tracker) SnapshotSessions() map[string]Session
- func (t *Tracker) Update(id string, newState State, meta, mediaMeta *plexapi.SessionMetadata)
- func (t *Tracker) UpdateLibraryLabels(id string, fn func(*Session))
Constants ¶
const ( MaxSessionKeyLen = 64 MaxTrackedSessions = 256 )
MaxSessionKeyLen and MaxTrackedSessions bound the session tracker against a compromised or buggy Plex server that streams unbounded distinct sessionKey values. SessionKey is used both as a map key and as a Prometheus label value, so unbounded growth would OOM the exporter and inflate Mimir's active-series count.
Variables ¶
This section is empty.
Functions ¶
func SubtitleAction ¶
func SubtitleAction(ts *plexapi.WSTranscodeSession) string
SubtitleAction classifies a transcode session's subtitle handling. Return values are one of ValBurn, ValCopy, ValTranscode, ValNone, or "other".
func TranscodeKind ¶
func TranscodeKind(ts *plexapi.WSTranscodeSession) string
TranscodeKind classifies a transcode session by audio/video decision and codec changes. Return values are one of ValVideo, ValAudio, ValBoth, or ValNone.
Types ¶
type Session ¶
type Session struct {
PlayStarted time.Time
LastUpdate time.Time
TranscodeType string
SubtitleAction string
LibName string
LibID string
LibType string
// MediaKey is the rating key MediaMeta was fetched for; empty until a
// successful /library/metadata fetch lands. It lets the session poll
// skip refetching immutable per-key metadata while the session stays
// on the same item (see Tracker.MediaResolved).
MediaKey string
State State
Meta plexapi.SessionMetadata
MediaMeta plexapi.SessionMetadata
PrevPlayedTime time.Duration
}
Session is a single tracked Plex playback session. All fields are exported so callers (the Prometheus collector and the session poll handler in package server) can read and mutate the tracked state under the tracker's mutex without a wall of getter methods.
type State ¶
type State string
State is a normalised session playback state derived from the Plex /status/sessions Player.State string.
const ( StatePlaying State = "playing" StateStopped State = "stopped" StatePaused State = "paused" StateOther State = "other" )
State values observed from Plex session polling.
func ParseState ¶
ParseState maps a raw Plex wire-protocol state string to a typed State constant. Unknown values map to StateOther so the state machine handles them intentionally rather than silently.
type Tracker ¶
Tracker is the in-memory active-session map. All lock-protected operations are encapsulated as methods; external callers must not access the mutex directly.
func NewTracker ¶
func NewTracker() *Tracker
NewTracker returns an empty session tracker ready for use.
func (*Tracker) MarkAbsentStopped ¶
MarkAbsentStopped transitions every tracked session whose key is not in presentKeys to StateStopped, so a stream that vanished from the poll moves onto the 60s stopped-prune path instead of lingering to the 5-minute stale timeout. A session already stopped is left untouched; a playing session banks its elapsed play time on the implicit playing->stopped transition.
func (*Tracker) MediaResolved ¶ added in v2.1.0
MediaResolved reports whether the tracked session id already carries library metadata fetched for exactly ratingKey AND resolved library labels, so the session poll can skip the /library/metadata refetch. MediaMeta is immutable per rating key; a rating-key change (episode auto-advance within one session) or unresolved labels (a degraded start before the library list is known) returns false and forces a refetch.
func (*Tracker) Prune ¶
func (t *Tracker) Prune()
Prune reclaims stopped sessions past the session timeout and non-stopped sessions idle past the stale-session timeout. Safe to call concurrently with Update.
func (*Tracker) RunPruneLoop ¶
RunPruneLoop invokes Prune every pruneInterval until ctx is cancelled.
func (*Tracker) SnapshotSessions ¶
SnapshotSessions returns a copy of the sessions map under the tracker's lock.
func (*Tracker) Update ¶
func (t *Tracker) Update(id string, newState State, meta, mediaMeta *plexapi.SessionMetadata)
Update records a state transition for the given session key. The meta and mediaMeta arguments may be nil; when non-nil they replace the cached metadata on the tracked session. On a playing→non-playing transition the elapsed play time is banked into PrevPlayedTime to keep plex_play_seconds_total monotonic.
func (*Tracker) UpdateLibraryLabels ¶
UpdateLibraryLabels applies fn to the session identified by id under the tracker's lock. No-op if the session does not exist.