{ "swagger": "2.0", "info": { "title": "evey/v1/admin_system.proto", "version": "version not set" }, "tags": [ { "name": "AdminSystemService" } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "paths": { "/api/v1/admin/config": { "get": { "operationId": "AdminSystemService_GetServerConfig", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1ServerConfig" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "tags": [ "AdminSystemService" ] }, "put": { "operationId": "AdminSystemService_UpdateServerConfig", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1ServerConfig" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1UpdateServerConfigRequest" } } ], "tags": [ "AdminSystemService" ] } }, "/api/v1/admin/dashboard": { "get": { "operationId": "AdminSystemService_GetDashboard", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1DashboardInfo" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "tags": [ "AdminSystemService" ] } }, "/api/v1/admin/load-test": { "get": { "operationId": "AdminSystemService_GetLoadTestStatus", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1LoadTestStatus" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "tags": [ "AdminSystemService" ] }, "delete": { "operationId": "AdminSystemService_CancelLoadTest", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1LoadTestStatus" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "tags": [ "AdminSystemService" ] }, "post": { "summary": "Built-in load test: the server plays synthetic viewers against its own\nHTTP stack and reports measured capacity. Admin-only; refuses to start\nwhile real streams are active.", "operationId": "AdminSystemService_StartLoadTest", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1LoadTestStatus" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1StartLoadTestRequest" } } ], "tags": [ "AdminSystemService" ] } }, "/api/v1/admin/setup": { "post": { "operationId": "AdminSystemService_SetupWizard", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1SetupWizardResponse" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1SetupWizardRequest" } } ], "tags": [ "AdminSystemService" ] } }, "/api/v1/admin/system": { "get": { "operationId": "AdminSystemService_GetSystemInfo", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1SystemInfo" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "tags": [ "AdminSystemService" ] } }, "/api/v1/admin/system/restart": { "post": { "summary": "RestartServer triggers a graceful shutdown; a process supervisor (Docker\n`restart: unless-stopped`, systemd) then brings the server back up. Admin\nonly. Has no effect when the process is not supervised (bare run / dev).", "operationId": "AdminSystemService_RestartServer", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1RestartServerResponse" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/v1RestartServerRequest" } } ], "tags": [ "AdminSystemService" ] } }, "/api/v1/setup/status": { "get": { "operationId": "AdminSystemService_GetSetupStatus", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/v1SetupStatusResponse" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "tags": [ "AdminSystemService" ] } } }, "definitions": { "protobufAny": { "type": "object", "properties": { "@type": { "type": "string" } }, "additionalProperties": {} }, "rpcStatus": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/protobufAny" } } } }, "v1DashboardInfo": { "type": "object", "properties": { "activeStreams": { "type": "integer", "format": "int32" }, "activeTranscodes": { "type": "integer", "format": "int32" }, "cpuPercent": { "type": "number", "format": "double" }, "memoryPercent": { "type": "number", "format": "double" }, "storage": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1StorageInfo" } }, "totalMediaItems": { "type": "integer", "format": "int32" }, "totalUsers": { "type": "integer", "format": "int32" }, "streamingBps": { "type": "string", "format": "int64", "description": "Measured streaming throughput: bytes actually written to stream/HLS/\ndownload responses since the previous GetDashboard call, as bits/s.\n-1 on the very first call (no previous sample to diff against)." }, "streamingBytesTotal": { "type": "string", "format": "int64", "description": "Cumulative streaming bytes served since the server started." }, "activeSessionsBps": { "type": "string", "format": "int64", "description": "Theoretical outgoing rate: the summed source bitrate of every active\nplay session - what the server would push if every client pulled at\nfull speed." }, "eveyCpuPercent": { "type": "number", "format": "double", "description": "The part of cpu_percent taken by Evey itself: the server and every\nprocess it forked (ffmpeg, ffprobe). The rest is the host's other work." }, "iowaitPercent": { "type": "number", "format": "double", "description": "The machine's share of CPU time spent idle with a disk request\noutstanding. cpu_percent does not include it: a waiting core is free." }, "disks": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1DiskIOInfo" }, "description": "Every physical disk the machine exposes, over the last sampling window.\nEmpty when /proc does not expose them (not a machine with idle disks)." }, "idleDiskAwaitMs": { "type": "number", "format": "double", "description": "The disks' wait at rest (from the last day of history, floored at 4 ms)\nand the wait above which a disk counts as saturated. The same line the\nhistory chart draws, so the live card and the trend agree." }, "saturationAwaitMs": { "type": "number", "format": "double" } } }, "v1DecodeThroughput": { "type": "object", "properties": { "codec": { "type": "string" }, "height": { "type": "integer", "format": "int32" }, "fps": { "type": "number", "format": "double" } }, "description": "DecodeThroughput is one measured DECODE-only rate, per source codec." }, "v1DiskIOInfo": { "type": "object", "properties": { "label": { "type": "string", "description": "Stable label: model and the tail of the wwid or serial. Two identical\ndisks of a VM differ only by that tail." }, "device": { "type": "string", "description": "Kernel name (sda), shown for the operator who runs iostat; it can move\nbetween boots, so it is never an identity." }, "rotational": { "type": "boolean" }, "awaitMs": { "type": "number", "format": "double", "description": "Mean time a READ waited and was served (a read queued behind writes\ncounts that queueing): the wait the load test judges on too. The one\nsignal that separates a disk that keeps up from one that does not; see\nsaturated. Averaged reads and writes together before 2026-10-18." }, "utilPercent": { "type": "number", "format": "double", "description": "Share of the window with at least one request in flight. Reaches 100 on\na healthy SSD or array, so it only corroborates the wait." }, "readBps": { "type": "string", "format": "int64" }, "writeBps": { "type": "string", "format": "int64" }, "requestsPerSecond": { "type": "number", "format": "double" }, "saturated": { "type": "boolean", "description": "The wait is above the saturation line and either the disk was busy or\nthe CPUs were waiting on it." } }, "description": "DiskIOInfo is one physical disk's activity over the sampling window. The\ncounters are the whole machine's: a neighbour's copy onto the same disk\nshows here too." }, "v1HWAccelType": { "type": "string", "enum": [ "HW_ACCEL_TYPE_NONE", "HW_ACCEL_TYPE_VAAPI", "HW_ACCEL_TYPE_NVENC", "HW_ACCEL_TYPE_QSV", "HW_ACCEL_TYPE_RKMPP" ], "default": "HW_ACCEL_TYPE_NONE" }, "v1HWDevice": { "type": "object", "properties": { "type": { "$ref": "#/definitions/v1HWAccelType" }, "name": { "type": "string" }, "devicePath": { "type": "string" }, "supportedCodecs": { "type": "array", "items": { "type": "string" } }, "supportedDecoders": { "type": "array", "items": { "type": "string" } }, "supportedEncoders": { "type": "array", "items": { "type": "string" } } } }, "v1LoadTestDeviceMapping": { "type": "object", "properties": { "location": { "type": "string", "description": "location is the branch of a pooled mount, or the mount point." }, "device": { "type": "string", "description": "device is the whole block device (\"sda\", \"nvme0n1\", \"dm-0\"); empty when\nnone on this machine could be tied to the location." }, "resolved": { "type": "string", "description": "resolved says how: \"stat\" (the filesystem's device id), \"read\" (a cold\nread moved its sectors), \"\" when unresolved." }, "disks": { "type": "array", "items": { "type": "string" }, "description": "disks are the physical disks under device: the device itself for a\nplain disk, the members of a volume (md, LVM, both stacked)." } }, "description": "LoadTestDeviceMapping ties a library location to the block device it is\nread from." }, "v1LoadTestDiskActivity": { "type": "object", "properties": { "device": { "type": "string" }, "utilPercentAvg": { "type": "number", "format": "double" }, "utilPercentPeak": { "type": "number", "format": "double" }, "readBytesPerSecAvg": { "type": "string", "format": "int64" }, "awaitMsAvg": { "type": "number", "format": "double" }, "readBytesPerSecPeak": { "type": "string", "format": "int64", "description": "One-second peaks and the mean queue depth (aqu-sz): a burst the average\nflattens, and the queue a saturated disk forms." }, "awaitMsPeak": { "type": "number", "format": "double" }, "queueDepthAvg": { "type": "number", "format": "double" } }, "description": "LoadTestDiskActivity is one physical drive's activity over the sustained\ntier. util_percent is the share of time the drive had a request in flight\n(iostat %util); await_ms is the mean time one read took, queueing included." }, "v1LoadTestDiskVerdict": { "type": "object", "properties": { "device": { "type": "string" }, "awaitMs": { "type": "number", "format": "double" }, "awaitBaselineMs": { "type": "number", "format": "double" }, "awaitMsPeak": { "type": "number", "format": "double" }, "queueDepth": { "type": "number", "format": "double" }, "utilPercent": { "type": "number", "format": "double" }, "readBytesPerSec": { "type": "string", "format": "int64" }, "iowaitPercent": { "type": "number", "format": "double" }, "saturated": { "type": "boolean" } }, "description": "LoadTestDiskVerdict is the busiest disk of a hold, judged against the\nserver at rest: a read waiting past the bar, with the device busy or the\nmachine in iowait to corroborate it." }, "v1LoadTestGridTier": { "type": "object", "properties": { "viewers": { "type": "integer", "format": "int32" }, "windows": { "type": "integer", "format": "int32" }, "passed": { "type": "integer", "format": "int32" }, "held": { "type": "boolean" }, "reason": { "type": "string" }, "resources": { "$ref": "#/definitions/v1LoadTestResources" } }, "description": "LoadTestGridTier is one audience size of the grid and how its windows went." }, "v1LoadTestPoolBranch": { "type": "object", "properties": { "branch": { "type": "string" }, "viewers": { "type": "integer", "format": "int32" } }, "description": "LoadTestPoolBranch is how many of the run's viewers were placed on one branch\n(underlying disk) of a pooled mount." }, "v1LoadTestReport": { "type": "object", "properties": { "scenario": { "type": "string" }, "sustainedViewers": { "type": "integer", "format": "int32" }, "stopReason": { "type": "string" }, "stopDetail": { "type": "string" }, "ttffMsP50": { "type": "integer", "format": "int32" }, "ttffMsP95": { "type": "integer", "format": "int32" }, "segmentMsP50": { "type": "integer", "format": "int32" }, "segmentMsP95": { "type": "integer", "format": "int32" }, "segmentSloMs": { "type": "integer", "format": "int32" }, "samples": { "type": "integer", "format": "int32" }, "sharedCacheViewers": { "type": "integer", "format": "int32" }, "startedAt": { "type": "string", "format": "date-time" }, "endedAt": { "type": "string", "format": "date-time" }, "skippedCandidates": { "type": "integer", "format": "int32", "description": "skipped_candidates counts titles the mkvgo scenario had to pass over\n(not eligible for the on-demand packager)." }, "viewerMix": { "type": "object", "additionalProperties": { "type": "integer", "format": "int32" }, "description": "viewer_mix is the composition at the sustained tier, per viewer type\n(\"mkvgo\", \"transcode\", \"natural\") - the answer to \"how many DIFFERENT\nkinds of users at once\"." }, "segmentMsP95ByType": { "type": "object", "additionalProperties": { "type": "integer", "format": "int32" }, "description": "segment_ms_p95_by_type breaks the p95 down per viewer type, so a slow\nmkvgo path cannot hide behind slow transcodes (or vice versa)." }, "mode": { "type": "string", "description": "mode is the behavior axis this run used (see StartLoadTestRequest.mode)." }, "segmentSloMsByType": { "type": "object", "additionalProperties": { "type": "integer", "format": "int32" }, "description": "segment_slo_ms_by_type is the latency budget each path was JUDGED against.\nThe paths do not share a segment length (mkvgo packages on keyframe\nboundaries, the ffmpeg ladder emits 3s segments), so they cannot share a\nbudget. segment_slo_ms above is only the loosest of these." }, "resources": { "$ref": "#/definitions/v1LoadTestResources", "description": "resources is what the server CONSUMED while sustaining that viewer count -\nthe evidence behind a cpu_saturated / memory_saturated stop_reason." }, "perViewerCost": { "$ref": "#/definitions/v1LoadTestResources", "description": "per_viewer_cost is what ONE more viewer costs, measured as the slope across\ntiers rather than a naive total/viewers (which would charge the idle\nserver's own consumption to the viewers). Absent when fewer than two tiers\nwere measured." }, "resourceBaseline": { "$ref": "#/definitions/v1LoadTestResources", "description": "resource_baseline is what the server consumed BEFORE the first viewer\njoined: the floor the per-viewer cost is read against." }, "throughputCeilingBytesPerSec": { "type": "string", "format": "int64", "description": "throughput_ceiling_bytes_per_sec is the byte rate the server could not\nexceed, set when stop_reason is throughput_saturated. On a media server this\nis the usual ceiling - not the CPU, not the RAM, but how fast it can READ\nthe films - and no CPU or memory gauge can see it." }, "diskReadStarved": { "type": "boolean", "description": "disk_read_starved: the server pushed real traffic while the kernel's I/O\ncounter barely moved. Either the page cache served everything, or the media\ndo not live on a block device (a network share, a 9p/virtiofs mount) where\nper-cgroup I/O accounting is simply blind. Zero read is NOT the same as no\ndisk activity, and the panel must not present it as a fact." }, "endpoint": { "type": "string", "description": "endpoint is the origin the viewers actually hit (the reverse proxy when it\nwas reachable, the server's own loopback otherwise). Runs against different\nendpoints are not comparable." }, "viaProxy": { "type": "boolean" }, "diskReadCeilingBytesPerSec": { "type": "string", "format": "int64", "description": "disk_read_ceiling_bytes_per_sec is how fast this box can READ its media,\nmeasured directly by the run (several files, scattered offsets, read at\nonce - the shape of load an audience creates). On a direct-play server this\nis usually the real ceiling, and the kernel cannot report it when the\nlibrary sits on anything but a plain block device." }, "diskCeilingAtReaders": { "type": "integer", "format": "int32", "description": "disk_ceiling_at_readers is the concurrency width at which that ceiling was\nreached. Indispensable next to the figure above: a peak measured at 4\nsequential readers says nothing about what 21 scrubbing viewers will get." }, "diskReadAtAudienceBytesPerSec": { "type": "string", "format": "int64", "description": "disk_read_at_audience_bytes_per_sec is what the SAME storage delivered at the\nconcurrency the sustained audience actually imposes on it. This is the figure\nthe run was competing against; the ceiling above is what the hardware gives\nunder laboratory conditions production never sees.\n\nReporting only the ceiling is how a disk at its knees gets read as 40% busy." }, "tiers": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1LoadTestTierCost" }, "description": "tiers is one row per audience size the run measured, smallest first: the\nclimb itself, not just the rung it stopped on. Read the per-viewer cost down\nthe rows and it either holds steady (the server is scaling) or bends upward\n(it is not) - which a single headline figure cannot say." }, "harnessCpuFraction": { "type": "number", "format": "double", "description": "harness_cpu_fraction is the share of the measured CPU burned by the load\nGENERATOR rather than by the server. Every CPU figure above already has it\nsubtracted. harness_cpu_measured is false when no profile could be taken, in\nwhich case all the CPU is charged to the server (the pessimistic reading)." }, "harnessCpuMeasured": { "type": "boolean" }, "memCacheBytes": { "type": "string", "format": "int64", "description": "mem_cache_bytes is the page cache the run accumulated by reading films. NOT\nconsumption: the kernel hands it straight back. Reported so an operator can\nsee why a naive memory gauge climbs to fill the box during a load test." }, "slowestDiskBytesPerSec": { "type": "string", "format": "int64", "description": "slowest_disk_bytes_per_sec is what the WEAKEST drive delivered. A library\nspread over several disks is not one big disk: each drive saturates on its\nown, and the film a viewer picks decides which. This is what sets how bad it\ngets when viewers happen to land on that drive." }, "disksProbed": { "type": "integer", "format": "int32", "description": "disks_probed is how many distinct drives the library was found to span." }, "readAmplification": { "type": "number", "format": "double", "description": "read_amplification is how many bytes the DISK delivered per byte served -\nwhat the hardware actually paid. Zero when the kernel cannot account the\nreads (a library on a network share or a 9p/virtiofs mount)." }, "appReadAmplification": { "type": "number", "format": "double", "description": "app_read_amplification is how many bytes the SERVER ASKED FOR per byte\nserved - the packager's own appetite, page cache or not.\n\nThe pair names the culprit, and the two have entirely different fixes:\n app 1.3 / disk 1.3 -\u003e the code reads what it serves; nothing to win.\n app 2.5 / disk 2.5 -\u003e the CODE traverses data it discards. Fix the packager.\n app 1.3 / disk 2.6 -\u003e the KERNEL reads ahead into data nobody wanted. The\n code is near-optimal; the fix is in HOW the file is\n read, not in what it reads.\nThe disk figure alone leaves an operator guessing which of the three they\nare looking at." }, "storageCollapsesAtReaders": { "type": "integer", "format": "int32", "description": "storage_collapses_at_readers is the number of concurrent readers past which\nthe storage stops merely plateauing and FALLS OVER - throughput halves or\nworse, and a single read starts taking seconds. Zero when it never did.\n\nWhen it is not zero it is the most important number in the report: on a\ndirect-play server it is roughly how many people can watch at once before\nthe STORAGE - not the CPU, not Evey - makes playback crawl. No CPU or memory\ngauge shows any of this." }, "coldCache": { "type": "boolean", "description": "cold_cache is true when the run kept evicting the library from the page\ncache (and the eviction actually landed): the figures were measured\nagainst the storage, not the RAM. A warm and a cold run of the same box\nare two different answers - never compare them as one." }, "sourceMix": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1LoadTestSourceMix" }, "description": "source_mix is what the run actually SERVED, per source class, counted as\neach title was handed to a viewer. The candidate pool is drawn by duration\nalone, so two runs on the same host land on different viewer counts purely\nby codec draw - a verdict that cannot name what it decoded cannot be read." }, "storageFsType": { "type": "string", "description": "storage_fs_type names the filesystem type(s) the library's files sit on\n(\"ext4\", \"fuse.mergerfs\", \"nfs4\"...), comma-joined when several." }, "storageOpaque": { "type": "boolean", "description": "storage_opaque is true when one of those mounts hides the disks from the\nserver's kernel (a FUSE pool, a network or VM share): the disk counter\ncannot see its reads, a cold-cache eviction stops at the mount and a pool\ncounts as one disk. The storage figures then describe the delivery path." }, "poolBranches": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1LoadTestPoolBranch" }, "description": "pool_branches is where the audience's titles sit on a pooled mount, one\nentry per branch (disk), most viewers first. Empty when the library is not\non a pool that can say. A pool is not a RAID: a file lives on ONE disk, so\na skewed placement is a skewed load whatever the pool's total capacity." }, "disks": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1LoadTestDiskActivity" }, "description": "disks is what each physical drive did over the sustained tier, busiest\nfirst. Read from the host-wide block counters, so it also includes whatever\nelse was reading those disks: it describes the drives, not only this run." }, "servedPaths": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1LoadTestServedPath" }, "description": "served_paths is what the server decided for each viewer type over the\nwhole run: how a client-mix verdict says what it was measured on." }, "breakViewers": { "type": "integer", "format": "int32", "description": "break_viewers is the lowest audience that broke, and break_disks /\nbreak_cpu_percent_peak what the drives and the CPU did under it: where the\ncause of a stop shows (disks above describe the tier that held). 0 and\nempty when no tier broke." }, "breakDisks": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1LoadTestDiskActivity" } }, "breakCpuPercentPeak": { "type": "number", "format": "double" }, "seed": { "type": "string", "format": "uint64", "description": "seed is the title draw's seed; passing it back to StartLoadTestRequest\nreplays the same draw." }, "diskDevices": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1LoadTestDeviceMapping" }, "description": "disk_devices is the mapping the run resolved at its start: which block\ndevice each library location (a pool branch, a mount) is read from.\nDevice letters rotate at reboot; this is what makes the disk lines\nreadable later. disk_read_measured is false when no device could be tied\nto the library: the disk read figures are then absent, not zero." }, "diskReadMeasured": { "type": "boolean" }, "appReadMeasured": { "type": "boolean", "description": "app_read_measured is false when nothing counts, in-process, the bytes the\npackager read from its sources: the app-read figures are then absent." }, "windows": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1LoadTestWindow" }, "description": "windows is every hold the run made, in order, broken ones included: the\nclimb as it happened, one row per window. A tier measured twice is two." }, "diskVerdict": { "$ref": "#/definitions/v1LoadTestDiskVerdict", "description": "disk_verdict judges the busiest disk under the audience the stop is read\non (the lowest tier that broke, else the sustained one)." }, "breakReason": { "type": "string", "description": "break_reason / break_detail name what broke break_viewers, when a tier did." }, "breakDetail": { "type": "string" }, "breakResources": { "$ref": "#/definitions/v1LoadTestResources", "description": "break_resources is everything the machine did under the lowest audience\nthat broke (break_disks and break_cpu_percent_peak are two of its fields)." }, "grid": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1LoadTestGridTier" }, "description": "grid is every candidate the bisection judged on measured windows, in the\norder judged, with how many of its windows passed (held at four of at\nmost five). sustained_viewers is the last one held: range_low is it,\nrange_high the first broken above it." }, "rangeLow": { "type": "integer", "format": "int32" }, "rangeHigh": { "type": "integer", "format": "int32" }, "limiter": { "type": "string", "description": "limiter names what gave out first, in plain terms the panel words:\n\"disk\", \"cpu\", \"memory\", \"proxy\", \"server\", \"unknown\", \"none\".\nlimiter_location is the library location of a limiting disk. advice is\nset only when one follows: \"spread_titles\"." }, "limiterLocation": { "type": "string" }, "advice": { "type": "string" }, "strata": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1LoadTestStratum" }, "description": "strata is the retained audience's split by stratum (disk x bitrate\nquarter); strata_by_disk / strata_by_band sum it each way." }, "strataByDisk": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1LoadTestStratum" } }, "strataByBand": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1LoadTestStratum" } }, "proxyAddress": { "type": "string", "description": "proxy_address is the local address the proxy was reached at when it sits\non the server's network: the run dials it there instead of turning\nthrough the router's public address, which no outside viewer does. Empty\nwhen the viewers took the public address." }, "uplinkBytesPerSec": { "type": "string", "format": "int64", "description": "uplink_* is what the line in front of the server sent to a speed-test\nservice (uplink_service, served from its nearest point of presence)\nbefore the run: the upload real viewers come through, which the run's\nown viewers never cross." }, "uplinkMeasured": { "type": "boolean" }, "uplinkService": { "type": "string" }, "remoteViewers": { "type": "integer", "format": "int32", "description": "remote_viewers is how many viewers outside the line carries (at what one\nviewer of this run pulled, 80 % of the line) and the server holds,\nwhichever is smaller; remote_by_line is true when the line is the\nsmaller. Zero when the line was not measured." }, "remoteByLine": { "type": "boolean" }, "appCopyReadAmplification": { "type": "number", "format": "double", "description": "app_copy_read_amplification is what the packager read AGAIN per byte\nserved, to copy its segments out (mkvgo CopyReadBytes). A local file's\nsegments are copied from the page cache its window walk just filled: it\ncosts no disk, and is kept apart from app_read_amplification, the walks." } }, "description": "LoadTestReport is what the box MEASURED, next to what the admission model\npredicted - the panel shows both so the operator sees promises kept." }, "v1LoadTestResources": { "type": "object", "properties": { "cpuPercentAvg": { "type": "number", "format": "double" }, "cpuPercentPeak": { "type": "number", "format": "double" }, "memUsedBytesAvg": { "type": "string", "format": "int64" }, "memUsedBytesMax": { "type": "string", "format": "int64" }, "memLimitBytes": { "type": "string", "format": "int64" }, "diskReadBytesPerSec": { "type": "string", "format": "int64" }, "servedBytesPerSec": { "type": "string", "format": "int64" }, "samples": { "type": "integer", "format": "int32" }, "goHeapLiveBytesAvg": { "type": "string", "format": "int64", "description": "go_heap_live_bytes_avg / _max: the heap the server's last garbage collections\nfound reachable, over the tier. go_mem_limit_bytes is GOMEMLIMIT (0 = unset).\ngo_gc_cpu_percent_avg / _peak: the share of the Go runtime's CPU time spent\ncollecting. A latency verdict with a high GC share and a heap at its limit is\nthe collector, not the disk." }, "goHeapLiveBytesMax": { "type": "string", "format": "int64" }, "goMemLimitBytes": { "type": "string", "format": "int64" }, "goGcCpuPercentAvg": { "type": "number", "format": "double" }, "goGcCpuPercentPeak": { "type": "number", "format": "double" }, "machineCpuPercentAvg": { "type": "number", "format": "double", "description": "The whole machine beside the container (/proc/stat): busy share, and the\nshare of time its cores waited on I/O - the storage path saturating." }, "machineCpuPercentPeak": { "type": "number", "format": "double" }, "machineIowaitPercentAvg": { "type": "number", "format": "double" }, "machineIowaitPercentPeak": { "type": "number", "format": "double" }, "processRssBytesAvg": { "type": "string", "format": "int64", "description": "The server process alone (VmRSS); mem_used_bytes_avg is the container." }, "processRssBytesMax": { "type": "string", "format": "int64" }, "appReadBytesPerSec": { "type": "string", "format": "int64", "description": "What the packager asked its sources for, counted in-process; absent when\napp_read_measured is false." }, "appReadMeasured": { "type": "boolean" }, "diskReadMeasured": { "type": "boolean" }, "appCopyReadBytesPerSec": { "type": "string", "format": "int64", "description": "What the packager read again to copy its segments out; 0 when nothing\ncounts it." } }, "description": "LoadTestResources is what the box was actually spending. The figures come\nfrom the server's own cgroup, so every ffmpeg it spawned is already counted;\nserved_bytes_per_sec is tallied by the viewers themselves (they reach the\nserver over loopback, where no NIC counter would see the traffic)." }, "v1LoadTestServedPath": { "type": "object", "properties": { "viewerType": { "type": "string", "description": "viewer_type is \"mkvgo\", \"transcode\", \"natural\" or \"client:\u003cprofile\u003e\"." }, "path": { "type": "string", "description": "path is the server's X-Evey-Served-By: \"mkvgo\" (packaged from the source,\nno encode), \"ffmpeg-copy\" (remuxed by ffmpeg, no encode), \"transcode\"." }, "viewers": { "type": "integer", "format": "int32" } }, "description": "LoadTestServedPath is how many viewers of one type the server served by one\npath, counted once per viewer by the path its first segment came from." }, "v1LoadTestSourceMix": { "type": "object", "properties": { "codec": { "type": "string" }, "height": { "type": "integer", "format": "int32" }, "count": { "type": "integer", "format": "int32" }, "videoRange": { "type": "string", "description": "video_range is the class's dynamic range: \"sdr\", \"hdr10\", \"hlg\", \"dovi\",\n\"dovi5\" (Dolby Vision profile 5, encoded for every client), \"\" unprobed." } }, "description": "LoadTestSourceMix is one source class and how many viewers were placed on it." }, "v1LoadTestStatus": { "type": "object", "properties": { "running": { "type": "boolean" }, "phase": { "type": "string" }, "viewers": { "type": "integer", "format": "int32" }, "elapsedMs": { "type": "string", "format": "int64" }, "lastReport": { "$ref": "#/definitions/v1LoadTestReport" } } }, "v1LoadTestStratum": { "type": "object", "properties": { "stratum": { "type": "string" }, "viewers": { "type": "integer", "format": "int32" } }, "description": "LoadTestStratum is how many viewers sat in one stratum (\"/mnt/disk_1|q3\"),\none disk, or one bitrate quarter." }, "v1LoadTestTierCost": { "type": "object", "properties": { "viewers": { "type": "integer", "format": "int32" }, "cpuPercent": { "type": "number", "format": "double" }, "memUsedBytes": { "type": "string", "format": "int64" }, "diskReadBytesPerSec": { "type": "string", "format": "int64" }, "servedBytesPerSec": { "type": "string", "format": "int64" }, "cpuPercentPerViewer": { "type": "number", "format": "double", "description": "Deprecated, never filled any more: 6 and 7 carried the row's cost divided\nby its headcount - the idle server's own consumption charged to the\nviewers. The per-viewer cost is the slope between tiers (per_viewer_cost)\nand nothing else. Kept declared so the published contract loses no field." }, "memBytesPerViewer": { "type": "string", "format": "int64" }, "samples": { "type": "integer", "format": "int32" }, "goHeapLiveBytes": { "type": "string", "format": "int64", "description": "go_heap_live_bytes / go_gc_cpu_percent: the server's Go runtime over this\ntier (see LoadTestResources)." }, "goGcCpuPercent": { "type": "number", "format": "double" }, "machineCpuPercent": { "type": "number", "format": "double", "description": "machine_cpu_percent / machine_iowait_percent: the whole machine's busy and\niowait shares beside the container's cpu_percent." }, "machineIowaitPercent": { "type": "number", "format": "double" }, "processRssBytes": { "type": "string", "format": "int64", "description": "process_rss_bytes is the server process alone; mem_used_bytes is the whole\ncontainer (Meilisearch and Postgres included in the image)." } }, "description": "LoadTestTierCost is what ONE audience size cost the server: one row of the\nreport's table. Every CPU figure is the SERVER's share - the load generator's\nown overhead has already been subtracted - and mem_used_bytes is anonymous\nmemory, never the page cache of the films being read." }, "v1LoadTestWindow": { "type": "object", "properties": { "viewers": { "type": "integer", "format": "int32" }, "phase": { "type": "string", "description": "phase is the climb phase (\"ramping\", \"narrowing\", \"confirming\",\n\"measuring\"); measured says it was a full window rather than a FAST hunt." }, "measured": { "type": "boolean" }, "broke": { "type": "boolean" }, "reason": { "type": "string" }, "detail": { "type": "string" }, "resources": { "$ref": "#/definitions/v1LoadTestResources" }, "segmentMsP50": { "type": "integer", "format": "int32", "description": "segment_ms_p50 / segment_ms_p95 are the raw fetch times of the hold's\nsegments; segment_ms_p95_scaled is the p95 of the same fetches scaled to\nthe reference segment length, the figure the stall verdict is read on." }, "segmentMsP95": { "type": "integer", "format": "int32" }, "segmentMsP95Scaled": { "type": "integer", "format": "int32" }, "segmentSamples": { "type": "integer", "format": "int32" }, "ttffMsP95": { "type": "integer", "format": "int32" }, "diskVerdict": { "$ref": "#/definitions/v1LoadTestDiskVerdict" }, "startedAt": { "type": "string", "format": "date-time" }, "endedAt": { "type": "string", "format": "date-time" } }, "description": "LoadTestWindow is one hold of the climb: the tier, how it was observed,\nwhether it held, what the machine did meanwhile, and the latencies the\nverdict was read on." }, "v1RestartServerRequest": { "type": "object" }, "v1RestartServerResponse": { "type": "object", "properties": { "restarting": { "type": "boolean" }, "message": { "type": "string" } } }, "v1ServerConfig": { "type": "object", "properties": { "values": { "type": "object", "additionalProperties": { "type": "string" } } } }, "v1SetupStatusResponse": { "type": "object", "properties": { "setupComplete": { "type": "boolean" }, "serverLanguage": { "type": "string", "description": "server_language/server_region expose the server-wide defaults so the\nSPA can render pre-auth routes (login, setup) in the admin-picked\nlanguage instead of falling back to navigator.language." }, "serverRegion": { "type": "string" }, "passwordRecoveryEnabled": { "type": "boolean", "description": "password_recovery_enabled lets the (unauthenticated) login page decide\nwhether to show the \"Forgot password?\" link. The same flag lives on the\nadmin-only SystemInfo; this is its public projection (it only reveals\nwhether SMTP + recovery are configured, no sensitive detail)." }, "serverName": { "type": "string", "description": "server_name is the admin-chosen instance name (Server settings, default\n\"Evey\"): the pre-auth screens (login, tab title) brand the instance with\nit. Public projection of the same value /healthz advertises." }, "demoMode": { "type": "boolean", "description": "demo_mode says this is the public demo instance (EVEY_DEMO=1): the\nclients show a banner and grey out what the server reports locked. The\nserver refuses the locked operations whether or not a client honours it." }, "demoExtended": { "type": "boolean", "description": "demo_extended says this is a private, extended demo (EVEY_DEMO=extended):\ndemo_mode is FALSE there, since the clients' read-only locks and shared-\naccount behaviour must not apply, and the login screen publishes no\ncredentials. The clients use it only to keep their hands off the network settings." }, "demoLocked": { "type": "array", "items": { "type": "string" }, "description": "demo_locked lists, on the extended demo only, what the server still\nrefuses there: gRPC full method names (\"/evey.v1.AdminSessionService/GetAuditLog\")\nand HTTP route patterns (\"GET /api/v1/admin/logs\"). The clients grey or\nhide the matching controls from it instead of a copy of the policy that\ndrifts; empty everywhere else." } } }, "v1SetupWizardRequest": { "type": "object", "properties": { "adminUsername": { "type": "string" }, "adminPassword": { "type": "string" }, "adminEmail": { "type": "string" }, "serverName": { "type": "string", "description": "server_name is optional: blank keeps the default, otherwise it is\npersisted as server.name (the admin settings key) and applied live." }, "baseUrl": { "type": "string", "description": "base_url was never read: the public URL is Remote access -\u003e External URL\n(EVEY_SERVER_BASE_URL for the LAN one). Kept for wire compatibility only." }, "serverLanguage": { "type": "string", "description": "Optional: locale+region chosen during the wizard. Persisted as\nserver.language / server.region so new profiles inherit them." }, "serverRegion": { "type": "string" } } }, "v1SetupWizardResponse": { "type": "object", "properties": { "accessToken": { "type": "string" }, "refreshToken": { "type": "string" }, "serverId": { "type": "string" } } }, "v1SourceClass": { "type": "object", "properties": { "codec": { "type": "string" }, "height": { "type": "integer", "format": "int32" } }, "description": "SourceClass is a decode workload: the source codec and the height it is\ndecoded at. See apptranscoding / transcoding.SourceClass." }, "v1StartLoadTestRequest": { "type": "object", "properties": { "scenario": { "type": "string", "description": "scenario is WHO the simulated viewers are: \"transcode\", \"natural\",\n\"mkvgo\", the ratio mixes \"light\"/\"balanced\"/\"heavy\", \"mkvgo+N\"\n(N pinned transcodes then pure direct-play), or a client mix:\n\"clients:history\" (the proportions of the last 30 days' playbacks) or\n\"clients:tv=40,mobile=40,web-chrome=20\" (profiles: tv, tv-browser, mobile,\nweb-chrome, web-safari), where each viewer declares what that player\ndeclares and the server picks its path." }, "maxViewers": { "type": "integer", "format": "int32", "description": "max_viewers caps the ramp; 0 = server default (12, sized for a weak NAS)." }, "mode": { "type": "string", "description": "mode is HOW they behave: \"\" (ramp, default), \"flash\" (everyone arrives at\nonce - the sunday-evening stampede), \"seek\" (viewers jump around the\ntimeline - session churn), \"endurance\" (hold the tier for the duration -\nslow-drift hunting)." }, "durationSec": { "type": "integer", "format": "int32", "description": "duration_sec bounds the run; 0 = mode default (4min ramp/flash/seek,\n30min endurance)." }, "coldCache": { "type": "boolean", "description": "cold_cache keeps evicting the library's files from the OS page cache for\nthe whole run, so the server's reads hit the actual storage. A box whose\nlibrary fits in RAM otherwise measures its memory bus and overstates the\nviewer count, sometimes by a factor of several. Cold measures the day the\nlibrary dwarfs the RAM; warm (the default) measures today. Both are true,\nand the report says which one was measured." }, "direct": { "type": "boolean", "description": "direct is kept for older clients and has no effect: the viewers hit the\nserver's own loopback by default." }, "viaProxy": { "type": "boolean", "description": "via_proxy is ignored: the viewers go through the public address whenever\none is configured and answers, the way real viewers come, and hit the\nserver's loopback otherwise. The report says which path was taken." }, "seed": { "type": "string", "format": "uint64", "description": "seed replays a previous run's title draw: the report carries the seed it\nused, and passing it back draws the same titles in the same order. Zero\n(the default) takes a fresh one from the clock." } } }, "v1StorageInfo": { "type": "object", "properties": { "path": { "type": "string", "description": "Representative path for this physical disk (the first library path that\nresolved to it). Kept for backwards compatibility with older clients." }, "totalBytes": { "type": "string", "format": "int64" }, "usedBytes": { "type": "string", "format": "int64" }, "freeBytes": { "type": "string", "format": "int64" }, "paths": { "type": "array", "items": { "type": "string" }, "description": "Every distinct library path that lives on this same physical disk (same\nfilesystem device id). Lets the UI group libraries per drive instead of\nshowing the same disk's capacity once per library." } } }, "v1SystemInfo": { "type": "object", "properties": { "version": { "type": "string" }, "os": { "type": "string" }, "arch": { "type": "string" }, "ffmpegVersion": { "type": "string" }, "hwDevices": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1HWDevice" } }, "uptimeSeconds": { "type": "string", "format": "int64" }, "goVersion": { "type": "string" }, "serverId": { "type": "string" }, "setupComplete": { "type": "boolean" }, "passwordRecoveryEnabled": { "type": "boolean" }, "smtpConfigured": { "type": "boolean" }, "videoSessions": { "$ref": "#/definitions/v1VideoSessionCapacity", "description": "VideoSessions surfaces the AUTO-derived cap on concurrent VIDEO transcode\n(encode, never copy/remux) sessions, the admin-overridden effective limit,\nand how many are live right now - so the admin panel can show \"why\" a\nnumber was chosen instead of a bare integer. Unset when no calibration\nservice is wired (e.g. a hand-built test server)." }, "commit": { "type": "string", "description": "commit is the git SHA the running binary was built from, build_date its\nRFC3339 build timestamp. `version` above is a branch or tag name and so\ncannot identify a deployment: two images months apart both report\n\"beta-0.0.1\". Both fields are the literal \"unknown\" - never blank -\nwhen the build could not be stamped, so a client can tell \"this server is\ntoo old to answer\" from \"this build genuinely does not know\"." }, "buildDate": { "type": "string" } } }, "v1UpdateServerConfigRequest": { "type": "object", "properties": { "values": { "type": "object", "additionalProperties": { "type": "string" } } } }, "v1VideoCapacityEvidence": { "type": "object", "properties": { "height": { "type": "integer", "format": "int32" }, "fps": { "type": "number", "format": "double" }, "requiredFps": { "type": "number", "format": "double" }, "ratio": { "type": "number", "format": "double" }, "cpuBudget": { "type": "integer", "format": "int32" }, "derived": { "type": "boolean", "description": "derived is false when no usable calibration evidence existed and\nauto_capacity fell back to the conservative default of 1." } }, "description": "VideoCapacityEvidence is the \"why\" behind auto_capacity: the tallest\nPASSING software bench rung the number was derived from." }, "v1VideoClassRungs": { "type": "object", "properties": { "ladderClass": { "type": "string", "description": "ladder_class is \"software\" | \"software-hdr\" | \"software-av1\" | \"hw\"." }, "rungFits": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1VideoRungFit" } } }, "description": "VideoClassRungs is one ladder class's calibrated rung costs, for the admin\npanel's per-pool breakdown. See apptranscoding.VideoCostModel.RungsFor." }, "v1VideoPool": { "type": "object", "properties": { "pool": { "type": "string", "description": "pool is \"cpu\" or \"gpu\"." }, "budgetUsed": { "type": "number", "format": "double" }, "budgetTotal": { "type": "number", "format": "double" }, "classes": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1VideoClassRungs" }, "description": "classes is every ladder class billed against this pool that has usable\ncalibration evidence - \"software\" (+ \"software-hdr\"/\"software-av1\" when\nbenched) for the cpu pool, \"hw\" for the gpu pool." } }, "description": "VideoPool is one resource pool's (cpu or gpu) admission budget and the\ncalibrated rung costs of the ladder class(es) billed against it. See\napptranscoding.ResourcePool / LadderClass.Pool." }, "v1VideoRungFit": { "type": "object", "properties": { "height": { "type": "integer", "format": "int32" }, "cost": { "type": "number", "format": "double" }, "maxStreams": { "type": "integer", "format": "int32" }, "bySource": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1VideoSourceFit" }, "description": "by_source prices this same rung for each source class the host measured.\ncost/max_streams above are the source-agnostic figures the bench produced;\nthey answer \"how many streams at this output height\" only for the source\nthe bench decoded, which is why the breakdown exists. Empty when the host\nhas no decode evidence." } }, "description": "VideoRungFit is one calibrated resolution rung's admission cost and how\nmany concurrent streams topping out at that height the host's budget\nfits. See apptranscoding.VideoCostModel.Rungs." }, "v1VideoSessionCapacity": { "type": "object", "properties": { "autoCapacity": { "type": "integer", "format": "int32" }, "effectiveLimit": { "type": "integer", "format": "int32" }, "active": { "type": "integer", "format": "int32" }, "evidence": { "$ref": "#/definitions/v1VideoCapacityEvidence" }, "budgetUsed": { "type": "number", "format": "double", "description": "budget_used / budget_total are the cost-model view of capacity: the\nfraction of \"one whole host\" currently reserved by live streams, and the\nbudget new streams may spend (default 1.0). Both stay 0 / 0 when no cost\nmodel is wired to the limiter - the panel then falls back to the\nauto_capacity/active counter view above." }, "budgetTotal": { "type": "number", "format": "double" }, "rungFits": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1VideoRungFit" }, "description": "rung_fits is the per-resolution cost breakdown the budget above is\nderived from - empty when no cost model is wired." }, "pools": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1VideoPool" }, "description": "pools is the per-resource-pool view of the SAME budget: CPU (every\nsoftware ladder class) and, only when the host has a hw bench table\n(see apptranscoding.VideoCostModel.Classes), a separate GPU pool. The\naggregate budget_used/budget_total above are the SUM across pools and\nare misleading once two independent pools exist (e.g. a GPU-heavy box\nshows \"0.7/2\" instead of \"0.5/1 cpu, 0.2/1 gpu\") - pools is the\nauthoritative breakdown; the fields above stay for older clients." }, "benchSource": { "$ref": "#/definitions/v1SourceClass", "description": "bench_source is the codec+height the encode rungs were DECODED from, and\ndecode_throughput the measured decode-only fps per codec. They are what\nmakes the rung costs interpretable: the same rung costs ~4x more fed by a\n4K HEVC source than by a 1080p H.264 one. Unset on a host calibrated\nbefore decode probing existed." }, "decodeThroughput": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v1DecodeThroughput" } } }, "description": "VideoSessionCapacity is the admin-facing view of the AUTO video-session cap\n(derived from the boot benchmark), the effective limit actually enforced\n(auto, possibly reduced by transcoding.max_video_sessions), and the live\ncount. See apptranscoding.AutoVideoSessionCapacity / ResolveVideoSessionLimit." }, "v1VideoSourceFit": { "type": "object", "properties": { "source": { "$ref": "#/definitions/v1SourceClass" }, "cost": { "type": "number", "format": "double" }, "maxStreams": { "type": "integer", "format": "int32" } }, "description": "VideoSourceFit is one rung's cost for one SOURCE class - the answer to \"how\nmany of these can I serve\" once the thing being decoded is named." } } }