runnerd_core/api/
jobs.rs

1//! Job history as clients read it: one record per GitHub job a runner of this daemon ran, its timeline, steps,
2//! metrics and log size; the queries that list them; sample series for graphs; per-repository aggregates; cache
3//! sizes. Times are seconds since the Unix epoch, sizes are bytes, CPU is in millicores (1000 = one core busy).
4
5use serde::{Deserialize, Serialize};
6
7/// Where a job is in its life, as this daemon saw it.
8#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
9#[serde(rename_all = "kebab-case")]
10pub enum JobState {
11    /// Waiting for a runner.
12    Queued,
13    /// A runner of this daemon took it.
14    Running,
15    /// GitHub reports it completed; `conclusion` says how.
16    Completed,
17    /// Its runner's container is gone and GitHub did not report the job completed in time.
18    Lost,
19    /// A runner of another machine took it, or it was cancelled before any runner did.
20    Elsewhere,
21}
22
23impl JobState {
24    /// Whether the job can still change.
25    pub fn is_final(self) -> bool {
26        matches!(
27            self,
28            JobState::Completed | JobState::Lost | JobState::Elsewhere
29        )
30    }
31}
32
33/// A job without its steps: what lists and events carry.
34#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
35pub struct JobSummary {
36    /// GitHub's job ID, also its check run ID.
37    pub id: u64,
38    /// `owner/name` on GitHub.
39    pub repository: String,
40    /// The workflow run it belongs to.
41    pub run_id: u64,
42    /// 1 for the first attempt of the run, higher for re-runs.
43    pub run_attempt: u32,
44    /// The workflow's name.
45    pub workflow: Option<String>,
46    /// The job's name in the workflow.
47    pub name: String,
48    /// The branch the run is for.
49    pub branch: Option<String>,
50    /// The job's page on GitHub.
51    pub url: Option<String>,
52    /// The workflow's `runs-on` labels.
53    pub labels: Vec<String>,
54    /// Where the job is.
55    pub state: JobState,
56    /// GitHub's conclusion once completed: `success`, `failure`, `cancelled`, `skipped`, `timed_out`, ….
57    pub conclusion: Option<String>,
58    /// The runner that ran it.
59    pub runner: Option<JobRunner>,
60    /// When each phase started.
61    pub timeline: Timeline,
62    /// CPU, memory and network use while it ran.
63    pub metrics: JobMetrics,
64    /// How much of its log is stored.
65    pub log: LogSummary,
66}
67
68/// `GET /v1/jobs/{id}`: a job with its steps.
69#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
70pub struct Job {
71    /// Everything but the steps.
72    #[serde(flatten)]
73    pub summary: JobSummary,
74    /// The steps as GitHub numbers them, including `Set up job` and `Complete job`.
75    pub steps: Vec<Step>,
76}
77
78/// The runner a job ran on.
79#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
80pub struct JobRunner {
81    /// The runner's name, also its container's.
82    pub name: String,
83    /// The profile it ran in.
84    pub profile: String,
85    /// The slot it ran in, 1-based.
86    pub slot: usize,
87    /// Its container's memory cap in bytes, which a reload since may have changed in the profile. `None` in records
88    /// from before runnerd kept it.
89    pub memory_cap: Option<u64>,
90    /// Its container's CPU limit in millicores, the unit of the CPU use in `Sample` and `JobMetrics`. `None` in
91    /// records from before runnerd kept it, or when Docker reports no limit.
92    pub cpu_cap: Option<u64>,
93}
94
95/// A job's phases, in the order they happen. A runner's container starts before GitHub gives it a job.
96#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
97pub struct Timeline {
98    /// GitHub queued the job.
99    pub queued_at: u64,
100    /// The container of the runner that took it started.
101    pub container_started_at: Option<u64>,
102    /// The runner started the job.
103    pub started_at: Option<u64>,
104    /// The job finished, by GitHub's clock; or when its container was found gone.
105    pub finished_at: Option<u64>,
106    /// The container and the runner's registration were removed.
107    pub cleaned_at: Option<u64>,
108}
109
110/// What a job used, over the samples taken while it ran (every few seconds). `None` until a sample exists.
111#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
112pub struct JobMetrics {
113    /// CPU time, in milliseconds.
114    pub cpu_time: Option<u64>,
115    /// The highest CPU use of a sample interval, in millicores.
116    pub cpu_peak: Option<u64>,
117    /// CPU time over wall time, in millicores.
118    pub cpu_average: Option<u64>,
119    /// The highest memory use without page cache.
120    pub memory_peak: Option<u64>,
121    /// The average memory use without page cache.
122    pub memory_average: Option<u64>,
123    /// Bytes the container received.
124    pub network_received: Option<u64>,
125    /// Bytes the container sent.
126    pub network_sent: Option<u64>,
127    /// Of the bytes received, those the Docker Hub mirror served.
128    pub mirror_bytes: u64,
129}
130
131/// A job's stored log.
132#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
133pub struct LogSummary {
134    /// Lines stored.
135    pub lines: u64,
136    /// Bytes stored.
137    pub bytes: u64,
138    /// Set once the log reached `history.log_max` and later lines were dropped.
139    pub truncated: bool,
140}
141
142/// One step of a job, as GitHub reports it.
143#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
144pub struct Step {
145    /// GitHub's step number; numbers may skip.
146    pub number: u32,
147    /// The name GitHub shows, such as `Set up job` or `Run docker run --rm hello-world`.
148    pub name: String,
149    /// `pending`, `queued`, `in_progress` or `completed`.
150    pub status: String,
151    /// Once completed: `success`, `failure`, `skipped`, `cancelled`, ….
152    pub conclusion: Option<String>,
153    /// When it started.
154    pub started_at: Option<u64>,
155    /// When it completed.
156    pub completed_at: Option<u64>,
157}
158
159/// `GET /v1/jobs` query parameters. Jobs come newest first (by ID, which grows with time).
160#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
161pub struct JobQuery {
162    /// Only this `owner/name`.
163    pub repository: Option<String>,
164    /// Only jobs in this state.
165    pub state: Option<JobState>,
166    /// Only jobs with this conclusion, such as `failure`.
167    pub conclusion: Option<String>,
168    /// Only jobs queued at or after this time.
169    pub since: Option<u64>,
170    /// Only jobs queued before this time.
171    pub until: Option<u64>,
172    /// Only jobs with a smaller ID: the `next` of the previous page.
173    pub before: Option<u64>,
174    /// At most this many jobs; default 50, at most 500.
175    pub limit: Option<u32>,
176}
177
178/// `GET /v1/jobs`: one page of jobs.
179#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
180pub struct JobPage {
181    /// Newest first.
182    pub jobs: Vec<JobSummary>,
183    /// Pass as `before` for the next page; `None` on the last page.
184    pub next: Option<u64>,
185}
186
187/// `GET /v1/jobs/{id}/logs` query parameters. The response is `text/plain`, one log line per line.
188#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
189pub struct LogQuery {
190    /// Start at this line, 0-based.
191    pub from: Option<u64>,
192    /// Keep the response open and send lines as they are stored, until the job finishes.
193    #[serde(default)]
194    pub follow: bool,
195}
196
197/// One sample of a container's use.
198#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
199pub struct Sample {
200    /// When it was taken.
201    pub at: u64,
202    /// CPU use since the previous sample, in millicores.
203    pub cpu: u64,
204    /// Memory use without page cache.
205    pub memory: u64,
206    /// Bytes received since the container started.
207    pub network_received: u64,
208    /// Bytes sent since the container started.
209    pub network_sent: u64,
210}
211
212/// `GET /v1/jobs/{id}/samples`: what the job's container used over time, from its start to its removal. Samples
213/// older than `history.samples` are deleted; the job's metrics stay.
214#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
215pub struct SampleSeries {
216    /// The job.
217    pub job: u64,
218    /// Seconds between samples.
219    pub interval: u64,
220    /// Oldest first.
221    pub samples: Vec<Sample>,
222}
223
224/// One sample of the whole slice runners run in.
225#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
226pub struct HostSample {
227    /// When it was taken.
228    pub at: u64,
229    /// CPU use of the slice since the previous sample, in millicores.
230    pub cpu: u64,
231    /// Memory use of the slice without page cache.
232    pub memory: u64,
233}
234
235/// `GET /v1/host/samples` query parameters.
236#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
237pub struct HostSampleQuery {
238    /// Only samples taken at or after this time; default the last hour, at most the last 24 hours.
239    pub since: Option<u64>,
240}
241
242/// `GET /v1/host/samples`: the slice's use over time, oldest first.
243#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
244pub struct HostSamples {
245    /// Seconds between samples.
246    pub interval: u64,
247    /// Oldest first.
248    pub samples: Vec<HostSample>,
249}
250
251/// How `GET /v1/stats` groups jobs in time.
252#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
253#[serde(rename_all = "kebab-case")]
254pub enum Bucket {
255    /// By UTC hour.
256    Hour,
257    /// By UTC day.
258    #[default]
259    Day,
260}
261
262/// `GET /v1/stats` query parameters.
263#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
264pub struct StatsQuery {
265    /// Only this `owner/name`.
266    pub repository: Option<String>,
267    /// Only jobs queued at or after this time; default 30 days ago. At most 744 buckets before `until` (or now)
268    /// are counted: 31 days of hours, two years of days.
269    pub since: Option<u64>,
270    /// Only jobs queued before this time.
271    pub until: Option<u64>,
272    /// The bucket size; default a day.
273    #[serde(default)]
274    pub bucket: Bucket,
275}
276
277/// `GET /v1/stats`: finished jobs per repository and time bucket, for trends. Sums, so clients can average.
278#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
279pub struct Stats {
280    /// The bucket size.
281    pub bucket: Bucket,
282    /// By bucket start, then repository.
283    pub rows: Vec<StatsRow>,
284}
285
286/// The finished jobs of one repository in one bucket.
287#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
288pub struct StatsRow {
289    /// The bucket's start.
290    pub start: u64,
291    /// `owner/name`.
292    pub repository: String,
293    /// Jobs completed or lost.
294    pub jobs: u64,
295    /// Of those, concluded `success`.
296    pub succeeded: u64,
297    /// Of those, concluded `failure` or `timed_out`, or lost.
298    pub failed: u64,
299    /// Of those, concluded `cancelled`.
300    pub cancelled: u64,
301    /// Seconds from queued to started, summed.
302    pub queue_seconds: u64,
303    /// Seconds from started to finished, summed.
304    pub run_seconds: u64,
305    /// CPU time, in milliseconds, summed.
306    pub cpu_time: u64,
307    /// The highest memory peak of a job.
308    pub memory_peak: u64,
309    /// Bytes received, summed.
310    pub network_received: u64,
311    /// Bytes from the mirror, summed.
312    pub mirror_bytes: u64,
313}
314
315/// What a cache volume holds.
316#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
317#[serde(rename_all = "kebab-case", tag = "kind")]
318pub enum CacheKind {
319    /// A profile's read-only snapshot.
320    Snapshot {
321        /// The profile.
322        profile: String,
323    },
324    /// A slot's layer changes and Docker Engine data.
325    Slot {
326        /// The profile.
327        profile: String,
328        /// 1-based.
329        slot: usize,
330    },
331    /// The pnpm store all slots share.
332    Pnpm,
333    /// The Maven repository all slots share.
334    Maven,
335    /// The Docker Hub mirror's storage.
336    Mirror,
337}
338
339/// One cache volume and its size.
340#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
341pub struct CacheVolume {
342    /// The Docker volume.
343    pub name: String,
344    /// What it holds.
345    #[serde(flatten)]
346    pub kind: CacheKind,
347    /// Its size at `measured_at`.
348    pub bytes: u64,
349    /// The size above which runnerd empties it, if it has one.
350    pub limit: Option<u64>,
351}
352
353/// `GET /v1/caches`: every cache volume of the configured profiles, as last measured. Docker measures volumes
354/// slowly, so runnerd measures them at start and whenever no runner runs after jobs ended.
355#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
356pub struct Caches {
357    /// When the sizes were measured; `None` before the first measurement.
358    pub measured_at: Option<u64>,
359    /// By name.
360    pub volumes: Vec<CacheVolume>,
361}
362
363/// `GET /v1/caches/history` query parameters.
364#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
365pub struct CacheHistoryQuery {
366    /// Only measurements at or after this time; default 30 days ago.
367    pub since: Option<u64>,
368}
369
370/// One volume's size at one measurement.
371#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
372pub struct CacheSize {
373    /// When it was measured.
374    pub at: u64,
375    /// The Docker volume.
376    pub name: String,
377    /// Its size.
378    pub bytes: u64,
379}
380
381/// `GET /v1/caches/history`: every measurement, oldest first.
382#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
383pub struct CacheHistory {
384    /// Oldest first.
385    pub sizes: Vec<CacheSize>,
386}
runnerd_core/api/jobs.rs

runnerd_core/api/
jobs.rs
