1use core::fmt::{self, Write as _};
26use std::path::Path;
27
28use crate::{
29 Bytes,
30 disk::{Disk, DiskKind},
31};
32
33#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
35#[non_exhaustive]
36pub enum Profile {
37 General,
39 Database,
41 WebServer,
43 Benchmark,
45}
46
47impl Profile {
48 #[must_use]
50 pub const fn name(self) -> &'static str {
51 match self {
52 Self::General => "general",
53 Self::Database => "database",
54 Self::WebServer => "webserver",
55 Self::Benchmark => "benchmark",
56 }
57 }
58}
59
60#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
62#[non_exhaustive]
63pub enum Status {
64 Pass,
66 Warn,
68 Fail,
70 Unknown,
72}
73
74impl Status {
75 #[must_use]
77 pub const fn name(self) -> &'static str {
78 match self {
79 Self::Pass => "PASS",
80 Self::Warn => "WARN",
81 Self::Fail => "FAIL",
82 Self::Unknown => "UNKNOWN",
83 }
84 }
85}
86
87#[derive(Clone, Debug, PartialEq, Eq)]
89#[non_exhaustive]
90pub struct Check {
91 pub id: &'static str,
93 pub title: &'static str,
95 pub status: Status,
97 pub found: String,
99 pub recommended: &'static str,
101 pub why: &'static str,
103 pub fix: &'static str,
105}
106
107#[derive(Clone, Debug, PartialEq, Eq)]
109#[non_exhaustive]
110pub struct Report {
111 pub profile: Profile,
113 pub checks: Vec<Check>,
115}
116
117impl Report {
118 #[must_use]
120 pub fn passed(&self) -> bool {
121 !self.checks.iter().any(|c| c.status == Status::Fail)
122 }
123
124 pub fn warnings(&self) -> impl Iterator<Item = &Check> {
126 self.checks.iter().filter(|c| c.status == Status::Warn)
127 }
128
129 pub fn failures(&self) -> impl Iterator<Item = &Check> {
131 self.checks.iter().filter(|c| c.status == Status::Fail)
132 }
133
134 pub fn write_kv(&self, out: &mut impl fmt::Write) -> fmt::Result {
140 for (i, c) in self.checks.iter().enumerate() {
141 if i > 0 {
142 out.write_char('\n')?;
143 }
144 crate::fmt::kv(out, "check", c.id)?;
145 out.write_char(' ')?;
146 crate::fmt::kv(out, "status", c.status.name())?;
147 out.write_char(' ')?;
148 crate::fmt::kv(out, "found", &c.found)?;
149 out.write_char(' ')?;
150 crate::fmt::kv(out, "recommended", c.recommended)?;
151 }
152 Ok(())
153 }
154
155 pub fn write_json(&self, out: &mut impl fmt::Write) -> fmt::Result {
162 use crate::fmt::json_str;
163 out.write_str("{\"profile\":")?;
164 json_str(out, self.profile.name())?;
165 write!(out, ",\"passed\":{},\"checks\":[", self.passed())?;
166 for (i, c) in self.checks.iter().enumerate() {
167 if i > 0 {
168 out.write_char(',')?;
169 }
170 out.write_str("{\"id\":")?;
171 json_str(out, c.id)?;
172 out.write_str(",\"title\":")?;
173 json_str(out, c.title)?;
174 out.write_str(",\"status\":")?;
175 json_str(out, c.status.name())?;
176 out.write_str(",\"found\":")?;
177 json_str(out, &c.found)?;
178 out.write_str(",\"recommended\":")?;
179 json_str(out, c.recommended)?;
180 out.write_str(",\"why\":")?;
181 json_str(out, c.why)?;
182 out.write_str(",\"fix\":")?;
183 json_str(out, c.fix)?;
184 out.write_char('}')?;
185 }
186 out.write_str("]}")
187 }
188}
189
190impl fmt::Display for Report {
193 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
194 let width = |col: fn(&Check) -> usize, cap: usize| {
198 self.checks.iter().map(col).max().unwrap_or(0).min(cap)
199 };
200 let id = width(|c| c.id.len(), 32);
201 let title = width(|c| c.title.chars().count(), 40);
202 let found = width(|c| c.found.chars().count(), 32);
203 for (i, c) in self.checks.iter().enumerate() {
204 if i > 0 {
205 f.write_char('\n')?;
206 }
207 write!(
208 f,
209 "{:<7} {:<id$} {:<title$} {:<found$} {}",
210 c.status.name(),
211 c.id,
212 c.title,
213 printable(&c.found),
214 c.recommended
215 )?;
216 if c.status != Status::Pass && !c.fix.is_empty() {
217 write!(f, "\n {}", c.fix)?;
218 }
219 }
220 Ok(())
221 }
222}
223
224fn printable(text: &str) -> std::borrow::Cow<'_, str> {
228 if text.chars().any(char::is_control) {
229 text.chars()
230 .map(|c| if c.is_control() { '?' } else { c })
231 .collect::<String>()
232 .into()
233 } else {
234 text.into()
235 }
236}
237
238#[must_use]
241pub fn report(profile: Profile) -> Report {
242 evaluate(profile, &gather(None))
243}
244
245#[must_use]
249pub fn report_for(profile: Profile, data_dir: impl AsRef<Path>) -> Report {
250 evaluate(profile, &gather(Some(data_dir.as_ref())))
251}
252
253#[derive(Clone, Debug, Default, PartialEq, Eq)]
259pub(crate) enum Fact<T> {
260 #[default]
262 Skip,
263 Value(T),
265 Unknown(String),
267}
268
269impl<T> Fact<T> {
270 pub(crate) fn of(r: crate::Result<T>) -> Fact<T> {
272 match r {
273 Ok(v) => Fact::Value(v),
274 Err(e) => Fact::Unknown(e.to_string()),
275 }
276 }
277
278 pub(crate) fn map<U>(self, f: impl FnOnce(T) -> U) -> Fact<U> {
279 match self {
280 Fact::Skip => Fact::Skip,
281 Fact::Value(v) => Fact::Value(f(v)),
282 Fact::Unknown(why) => Fact::Unknown(why),
283 }
284 }
285}
286
287#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
289pub(crate) struct Dirty {
290 pub(crate) ratio: u64,
291 pub(crate) background_ratio: u64,
292 pub(crate) bytes: u64,
293 pub(crate) background_bytes: u64,
294}
295
296#[derive(Clone, Debug, Default, PartialEq, Eq)]
299pub(crate) struct Governor {
300 pub(crate) name: String,
302 pub(crate) performance: bool,
304}
305
306#[allow(dead_code)] #[derive(Clone, Copy, Debug, PartialEq, Eq)]
309pub(crate) enum MemLock {
310 Limit { soft: Option<u64> },
312 Privilege(bool),
314}
315
316#[derive(Clone, Debug, Default, PartialEq, Eq)]
319pub(crate) struct Tuning {
320 pub(crate) thp: Fact<(String, String)>,
322 pub(crate) swappiness: Fact<u64>,
323 pub(crate) overcommit: Fact<(u64, u64)>,
325 pub(crate) max_map_count: Fact<u64>,
326 pub(crate) dirty: Fact<Dirty>,
327 pub(crate) numa: Fact<(u64, u64)>,
329 pub(crate) handles_unlimited: bool,
331 pub(crate) files_system: Fact<u64>,
333 pub(crate) files_process: Fact<u64>,
335 pub(crate) memlock: Fact<MemLock>,
336 pub(crate) backlog: Fact<(u64, Option<u64>)>,
338 pub(crate) ports: Fact<(u32, u32)>,
340 pub(crate) governor: Fact<Governor>,
341 pub(crate) clock_source: Fact<String>,
342}
343
344#[derive(Clone, Debug, Default, PartialEq, Eq)]
346pub(crate) struct DataDirTuning {
347 pub(crate) atime: Fact<String>,
349 pub(crate) scheduler: Fact<String>,
351}
352
353#[derive(Clone, Debug, Default)]
356pub(crate) struct Inputs {
357 pub(crate) tuning: Tuning,
358 pub(crate) open_files_soft: Fact<Option<u64>>,
359 pub(crate) clock_synchronized: Fact<bool>,
360 pub(crate) swap_total: Fact<Bytes>,
361 pub(crate) numa_nodes: usize,
362 pub(crate) container_limits: Option<String>,
363 pub(crate) data_dir: Option<DataDir>,
364 pub(crate) bench: Option<crate::bench::Environment>,
365}
366
367#[derive(Clone, Debug)]
369pub(crate) struct DataDir {
370 pub(crate) disk: Fact<Disk>,
371 pub(crate) tuning: DataDirTuning,
372}
373
374fn gather(data_dir: Option<&Path>) -> Inputs {
375 let tuning = crate::sys::tuning();
376 let open_files_soft = Fact::of(crate::process::limits()).map(|l| l.open_files.soft);
377 let clock_synchronized = match crate::host::clock_sync() {
378 Ok(Some(c)) => Fact::Value(c.synchronized),
379 Ok(None) => Fact::Unknown("the OS does not say".to_owned()),
380 Err(e) => Fact::Unknown(e.to_string()),
381 };
382 let swap_total = Fact::of(crate::mem::swap()).map(|s| s.total);
383 let mut limits = Vec::new();
384 if let Ok(Some(l)) = crate::mem::limit() {
385 limits.push(format!("memory {}", l.hard));
386 }
387 if let Ok(Some(q)) = crate::cpu::quota() {
388 limits.push(format!("cpu {:.2}", q.cpus));
389 }
390 let container_limits = (!limits.is_empty()).then(|| limits.join(", "));
391 let data_dir = data_dir.map(|path| {
392 let disk = Fact::of(crate::disk::of(path));
393 let tuning = match &disk {
394 Fact::Value(d) => crate::sys::data_dir_tuning(path, d),
395 _ => DataDirTuning::default(),
396 };
397 DataDir { disk, tuning }
398 });
399 Inputs {
400 tuning,
401 open_files_soft,
402 clock_synchronized,
403 swap_total,
404 numa_nodes: crate::cpu::numa_nodes().len(),
405 container_limits,
406 data_dir,
407 bench: None,
408 }
409}
410
411pub const SWAPPINESS_MIN: u64 = 1;
417pub const SWAPPINESS_MAX: u64 = 10;
419pub const MAX_MAP_COUNT_MIN: u64 = 262_144;
421pub const DIRTY_BACKGROUND_MAX: u64 = 5;
423pub const DIRTY_MAX: u64 = 15;
425pub const OPEN_FILES_SERVER: u64 = 65_536;
427pub const OPEN_FILES_GENERAL: u64 = 4_096;
429pub const OPEN_FILES_FLOOR: u64 = 1_024;
431pub const BACKLOG_MIN: u64 = 4_096;
433pub const PORTS_MIN: u32 = 28_000;
435pub const FREE_WARN: f32 = 15.0;
437pub const FREE_FAIL: f32 = 5.0;
439
440#[cfg(target_os = "macos")]
441mod fixes {
442 pub(super) const NOFILE: &str =
443 "launchctl limit maxfiles 65536 200000, or SoftResourceLimits in the launchd plist";
444 pub(super) const MEMLOCK: &str = "launchctl limit memlock unlimited unlimited";
445 pub(super) const BACKLOG: &str = "sysctl -w kern.ipc.somaxconn=4096";
446 pub(super) const PORTS: &str =
447 "sysctl -w net.inet.ip.portrange.first=10000 net.inet.ip.portrange.last=65535";
448 pub(super) const GOVERNOR: &str = "";
449 pub(super) const CLOCK: &str = "enable Set time automatically in System Settings";
450 pub(super) const CLOCK_SOURCE: &str = "";
451 pub(super) const TURBO: &str = "";
452 pub(super) const SWAP: &str = "macOS manages swap itself";
453}
454
455#[cfg(windows)]
456mod fixes {
457 pub(super) const NOFILE: &str = "";
458 pub(super) const MEMLOCK: &str =
459 "grant Lock pages in memory (SeLockMemoryPrivilege) to the service account in secpol.msc";
460 pub(super) const BACKLOG: &str = "";
461 pub(super) const PORTS: &str = "netsh int ipv4 set dynamicport tcp start=10000 num=55535";
462 pub(super) const GOVERNOR: &str = "powercfg /setactive SCHEME_MIN";
463 pub(super) const CLOCK: &str = "w32tm /resync, and check the Windows Time service";
464 pub(super) const CLOCK_SOURCE: &str = "";
465 pub(super) const TURBO: &str = "powercfg /setacvalueindex SCHEME_CURRENT SUB_PROCESSOR PERFBOOSTMODE 0, then powercfg /setactive SCHEME_CURRENT";
466 pub(super) const SWAP: &str = "System Properties > Advanced > Performance > Virtual memory";
467}
468
469#[cfg(target_os = "freebsd")]
470mod fixes {
471 pub(super) const NOFILE: &str =
472 "openfiles in /etc/login.conf (then cap_mkdb /etc/login.conf), within kern.maxfilesperproc";
473 pub(super) const MEMLOCK: &str =
474 "memorylocked=unlimited in /etc/login.conf (then cap_mkdb /etc/login.conf)";
475 pub(super) const BACKLOG: &str = "sysctl kern.ipc.soacceptqueue=4096, and in /etc/sysctl.conf";
476 pub(super) const PORTS: &str =
477 "sysctl net.inet.ip.portrange.first=10000 net.inet.ip.portrange.last=65535";
478 pub(super) const GOVERNOR: &str = "";
479 pub(super) const CLOCK: &str =
480 "sysrc ntpd_enable=YES ntpd_sync_on_start=YES, then service ntpd start";
481 pub(super) const CLOCK_SOURCE: &str = "sysctl kern.timecounter.hardware=TSC-low";
482 pub(super) const TURBO: &str = "";
483 pub(super) const SWAP: &str = "add a swap partition or file: swapon(8) and /etc/fstab";
484}
485
486#[cfg(not(any(target_os = "macos", target_os = "freebsd", windows)))]
487mod fixes {
488 pub(super) const NOFILE: &str =
489 "LimitNOFILE=65536 in the systemd unit, or nofile in /etc/security/limits.conf";
490 pub(super) const MEMLOCK: &str =
491 "LimitMEMLOCK=infinity in the systemd unit, or memlock in /etc/security/limits.conf";
492 pub(super) const BACKLOG: &str =
493 "sysctl -w net.core.somaxconn=4096 net.ipv4.tcp_max_syn_backlog=4096";
494 pub(super) const PORTS: &str = "sysctl -w net.ipv4.ip_local_port_range=\"10000 65535\"";
495 pub(super) const GOVERNOR: &str = "cpupower frequency-set -g performance";
496 pub(super) const CLOCK: &str = "enable chrony or systemd-timesyncd: timedatectl set-ntp true";
497 pub(super) const CLOCK_SOURCE: &str =
498 "echo tsc > /sys/devices/system/clocksource/clocksource0/current_clocksource";
499 pub(super) const TURBO: &str = "echo 1 > /sys/devices/system/cpu/intel_pstate/no_turbo, or echo 0 > /sys/devices/system/cpu/cpufreq/boost";
500 pub(super) const SWAP: &str = "add a small swap file or zram: swapon, or zram-generator";
501}
502
503fn check(
504 id: &'static str,
505 title: &'static str,
506 status: Status,
507 found: impl Into<String>,
508 recommended: &'static str,
509 why: &'static str,
510 fix: &'static str,
511) -> Check {
512 Check {
513 id,
514 title,
515 status,
516 found: found.into(),
517 recommended,
518 why,
519 fix,
520 }
521}
522
523fn push<T>(
526 out: &mut Vec<Check>,
527 fact: &Fact<T>,
528 meta: (
529 &'static str,
530 &'static str,
531 &'static str,
532 &'static str,
533 &'static str,
534 ),
535 judge: impl FnOnce(&T) -> (Status, String),
536) {
537 let (id, title, recommended, why, fix) = meta;
538 match fact {
539 Fact::Skip => {}
540 Fact::Unknown(reason) => {
541 out.push(check(
542 id,
543 title,
544 Status::Unknown,
545 reason.clone(),
546 recommended,
547 why,
548 fix,
549 ));
550 }
551 Fact::Value(v) => {
552 let (status, found) = judge(v);
553 out.push(check(id, title, status, found, recommended, why, fix));
554 }
555 }
556}
557
558const fn pass_if(ok: bool) -> Status {
559 if ok { Status::Pass } else { Status::Warn }
560}
561
562fn has(profiles: &[Profile], profile: Profile) -> bool {
563 profiles.contains(&profile)
564}
565
566#[allow(clippy::too_many_lines)] pub(crate) fn evaluate(profile: Profile, inputs: &Inputs) -> Report {
568 use Profile::{Benchmark, Database, WebServer};
569
570 let t = &inputs.tuning;
571 let mut out = Vec::new();
572 let db = profile == Database;
573 let server = matches!(profile, Database | WebServer);
574
575 if db {
576 push(
577 &mut out,
578 &t.thp,
579 (
580 "linux.thp",
581 "Transparent huge pages",
582 "madvise or never",
583 "With always, the kernel stalls allocations to compact memory and bloats sparse heaps, which shows as latency spikes.",
584 "echo madvise > /sys/kernel/mm/transparent_hugepage/enabled",
585 ),
586 |(enabled, defrag)| {
587 let ok = enabled != "always" && defrag != "always";
588 (pass_if(ok), format!("{enabled}, defrag {defrag}"))
589 },
590 );
591 push(
592 &mut out,
593 &t.swappiness,
594 (
595 "linux.swappiness",
596 "Swap tendency (vm.swappiness)",
597 "1 to 10",
598 "A high value swaps out the buffer pool to keep page cache, which a database already manages itself.",
599 "sysctl -w vm.swappiness=1",
600 ),
601 |&v| {
602 (
603 pass_if((SWAPPINESS_MIN..=SWAPPINESS_MAX).contains(&v)),
604 v.to_string(),
605 )
606 },
607 );
608 push(
609 &mut out,
610 &t.overcommit,
611 (
612 "linux.overcommit",
613 "Memory overcommit",
614 "0 or 2",
615 "With 1 the kernel grants any allocation and the OOM killer ends the database when memory runs out.",
616 "sysctl -w vm.overcommit_memory=0",
617 ),
618 |&(mode, ratio)| {
619 let found = if mode == 2 {
620 format!("{mode}, ratio {ratio}")
621 } else {
622 mode.to_string()
623 };
624 (
625 if mode == 1 {
626 Status::Fail
627 } else {
628 Status::Pass
629 },
630 found,
631 )
632 },
633 );
634 push(
635 &mut out,
636 &t.max_map_count,
637 (
638 "linux.max_map_count",
639 "Memory map count",
640 "at least 262144",
641 "Memory-mapped storage engines need a map per file region and fail allocations past the limit.",
642 "sysctl -w vm.max_map_count=262144",
643 ),
644 |&v| (pass_if(v >= MAX_MAP_COUNT_MIN), v.to_string()),
645 );
646 push(
647 &mut out,
648 &t.dirty,
649 (
650 "linux.dirty",
651 "Dirty page write-back",
652 "background at most 5%, foreground at most 15%",
653 "Large dirty thresholds let gigabytes of writes pile up and then stall every writer while they flush.",
654 "sysctl -w vm.dirty_background_ratio=5 vm.dirty_ratio=15",
655 ),
656 |d| {
657 if d.bytes != 0 || d.background_bytes != 0 {
658 return (
660 Status::Pass,
661 format!(
662 "background {} bytes, foreground {} bytes",
663 d.background_bytes, d.bytes
664 ),
665 );
666 }
667 (
668 pass_if(d.background_ratio <= DIRTY_BACKGROUND_MAX && d.ratio <= DIRTY_MAX),
669 format!(
670 "background {}%, foreground {}%",
671 d.background_ratio, d.ratio
672 ),
673 )
674 },
675 );
676 if inputs.numa_nodes > 1 {
677 push(
678 &mut out,
679 &t.numa,
680 (
681 "linux.numa",
682 "NUMA balancing and zone reclaim",
683 "both 0",
684 "Automatic balancing migrates the buffer pool between nodes, and zone reclaim drops cache instead of using remote memory.",
685 "sysctl -w kernel.numa_balancing=0 vm.zone_reclaim_mode=0",
686 ),
687 |&(balancing, reclaim)| {
688 (
689 pass_if(balancing == 0 && reclaim == 0),
690 format!("balancing {balancing}, zone reclaim {reclaim}"),
691 )
692 },
693 );
694 }
695 }
696
697 let (want, recommended) = if server {
699 (OPEN_FILES_SERVER, "at least 65536")
700 } else {
701 (OPEN_FILES_GENERAL, "at least 4096")
702 };
703 const NOFILE_WHY: &str = "Every connection and every open table or segment file takes a descriptor; at the limit, accepts and opens fail.";
704 if t.handles_unlimited {
705 out.push(check(
706 "limits.nofile",
707 "Open-file limit",
708 Status::Pass,
709 "unlimited (handles)",
710 recommended,
711 NOFILE_WHY,
712 fixes::NOFILE,
713 ));
714 } else {
715 push(
716 &mut out,
717 &inputs.open_files_soft,
718 (
719 "limits.nofile",
720 "Open-file limit",
721 recommended,
722 NOFILE_WHY,
723 fixes::NOFILE,
724 ),
725 |&soft| match soft {
726 None => (Status::Pass, "unlimited".to_owned()),
727 Some(n) => {
728 let mut found = n.to_string();
729 if let Fact::Value(max) = t.files_system {
730 if max >= 1 << 62 {
732 found.push_str(", system unlimited");
733 } else {
734 found.push_str(&format!(", system {max}"));
735 }
736 }
737 let status = if n >= want {
738 Status::Pass
739 } else if server && n < OPEN_FILES_FLOOR {
740 Status::Fail
741 } else {
742 Status::Warn
743 };
744 (status, found)
745 }
746 },
747 );
748 }
749
750 if db {
751 push(
752 &mut out,
753 &t.memlock,
754 (
755 "limits.memlock",
756 "Locked-memory limit",
757 "unlimited, when the buffer pool is locked",
758 "A database that locks its buffer pool in memory, to keep it out of swap, can lock no more than this.",
759 fixes::MEMLOCK,
760 ),
761 |m| match *m {
762 MemLock::Limit { soft: None } => (Status::Pass, "unlimited".to_owned()),
763 MemLock::Limit { soft: Some(n) } => (Status::Warn, Bytes::new(n).to_string()),
764 MemLock::Privilege(true) => (Status::Pass, "granted".to_owned()),
765 MemLock::Privilege(false) => (Status::Warn, "not granted".to_owned()),
766 },
767 );
768 }
769
770 if server {
771 push(
772 &mut out,
773 &t.backlog,
774 (
775 "net.backlog",
776 "Listen backlog",
777 "at least 4096",
778 "Connections beyond the backlog are dropped during bursts, and clients see timeouts.",
779 fixes::BACKLOG,
780 ),
781 |&(somaxconn, syn)| {
782 let least = syn.map_or(somaxconn, |s| s.min(somaxconn));
783 let found = match syn {
784 Some(s) => format!("{somaxconn}, SYN {s}"),
785 None => somaxconn.to_string(),
786 };
787 (pass_if(least >= BACKLOG_MIN), found)
788 },
789 );
790 push(
791 &mut out,
792 &t.ports,
793 (
794 "net.ports",
795 "Ephemeral ports",
796 "at least 28000 ports",
797 "Each outgoing connection holds a port through TIME_WAIT; a narrow range runs out under load.",
798 fixes::PORTS,
799 ),
800 |&(first, last)| {
801 let count = last.saturating_sub(first).saturating_add(1);
802 (
803 pass_if(count >= PORTS_MIN),
804 format!("{first} to {last} ({count})"),
805 )
806 },
807 );
808 }
809
810 if has(&[Database, WebServer, Benchmark], profile) {
811 push(
812 &mut out,
813 &t.governor,
814 (
815 "cpu.governor",
816 "CPU frequency policy",
817 "performance",
818 "Power-saving policies add wake-up latency and make throughput depend on load history.",
819 fixes::GOVERNOR,
820 ),
821 |g| (pass_if(g.performance), g.name.clone()),
822 );
823 }
824
825 if has(&[Database, Benchmark], profile) {
826 push(
827 &mut out,
828 &t.clock_source,
829 (
830 "clock.source",
831 "Kernel clock source",
832 "tsc",
833 "Reading hpet or acpi_pm costs microseconds, which every timestamp and timeout pays.",
834 fixes::CLOCK_SOURCE,
835 ),
836 |s| (pass_if(!crate::bench::slow_clock(s)), s.clone()),
837 );
838 }
839
840 if profile != Benchmark {
841 push(
842 &mut out,
843 &inputs.clock_synchronized,
844 (
845 "clock.sync",
846 "Clock synchronized",
847 "synchronized",
848 "Leases, distributed locks, certificates, and log ordering assume clocks agree.",
849 fixes::CLOCK,
850 ),
851 |&ok| {
852 (
853 pass_if(ok),
854 if ok {
855 "synchronized"
856 } else {
857 "not synchronized"
858 }
859 .to_owned(),
860 )
861 },
862 );
863 }
864
865 if db {
866 push(
867 &mut out,
868 &inputs.swap_total,
869 (
870 "mem.swap",
871 "Swap present",
872 "some swap or zram, small",
873 "Without any swap, a brief memory spike goes straight to the OOM killer instead of slowing down.",
874 fixes::SWAP,
875 ),
876 |&total| {
877 let status = if total.raw() == 0 {
878 Status::Warn
879 } else {
880 Status::Pass
881 };
882 (status, total.to_string())
883 },
884 );
885 }
886
887 if let Some(dir) = &inputs.data_dir {
888 data_dir_checks(&mut out, profile, dir);
889 }
890
891 if let Some(limits) = &inputs.container_limits {
892 out.push(check(
893 "container.limits",
894 "Container limits",
895 Status::Pass,
896 limits.clone(),
897 "reported",
898 "Size thread pools and caches from these limits, not from the host.",
899 "",
900 ));
901 }
902
903 if profile == Benchmark {
904 let env = inputs
905 .bench
906 .clone()
907 .unwrap_or_else(crate::bench::environment);
908 bench_checks(&mut out, &env);
909 }
910
911 Report {
912 profile,
913 checks: out,
914 }
915}
916
917fn data_dir_checks(out: &mut Vec<Check>, profile: Profile, dir: &DataDir) {
918 let db = profile == Profile::Database;
919 const FS_WHY: &str = "Network filesystems break locking and fsync guarantees, and some local ones are slow under database write patterns.";
920 let disk = match &dir.disk {
921 Fact::Skip => return,
922 Fact::Unknown(reason) => {
923 out.push(check(
924 "fs.type",
925 "Data directory filesystem",
926 Status::Unknown,
927 reason.clone(),
928 RECOMMENDED_FS,
929 FS_WHY,
930 "",
931 ));
932 return;
933 }
934 Fact::Value(d) => d,
935 };
936 let fs = disk.filesystem.to_ascii_lowercase();
937 let network = disk.kind == DiskKind::Network;
938 let status = if network {
939 if db { Status::Fail } else { Status::Warn }
940 } else if db {
941 pass_if(RECOMMENDED_FS_NAMES.contains(&fs.as_str()))
942 } else {
943 Status::Pass
944 };
945 out.push(check(
946 "fs.type",
947 "Data directory filesystem",
948 status,
949 disk.filesystem.clone(),
952 RECOMMENDED_FS,
953 FS_WHY,
954 "move the data directory to a local disk with a recommended filesystem",
955 ));
956
957 push(
958 out,
959 &dir.tuning.atime,
960 (
961 "fs.atime",
962 "Data directory access times",
963 "noatime or relatime",
964 "Updating the access time on every read turns reads into writes.",
965 "mount with noatime: add it to the options in /etc/fstab and remount",
966 ),
967 |a| (pass_if(a != "strictatime"), a.clone()),
968 );
969
970 if let Some(space) = disk.space {
971 let free = space.available.percent_of(space.total).value();
972 let status = if free < FREE_FAIL {
973 Status::Fail
974 } else if free < FREE_WARN {
975 Status::Warn
976 } else {
977 Status::Pass
978 };
979 out.push(check(
980 "disk.space",
981 "Data directory free space",
982 status,
983 format!("{free:.0}% free ({} of {})", space.available, space.total),
984 "at least 15% free",
985 "A full disk stops writes and can corrupt files that are half written; copy-on-write filesystems need headroom.",
986 "free space or grow the volume",
987 ));
988 }
989
990 if db {
991 let (status, found) = match disk.kind {
992 DiskKind::Ssd => (Status::Pass, "ssd"),
993 DiskKind::Hdd => (Status::Warn, "hdd"),
994 DiskKind::Ram => (Status::Warn, "memory (lost on reboot)"),
995 DiskKind::Network => (Status::Warn, "network"),
996 DiskKind::Removable => (Status::Warn, "removable"),
997 DiskKind::Optical => (Status::Warn, "optical"),
998 DiskKind::Virtual => (Status::Pass, "virtual"),
999 _ => (Status::Unknown, "unknown"),
1000 };
1001 out.push(check(
1002 "disk.kind",
1003 "Data directory storage",
1004 status,
1005 found,
1006 "ssd or nvme",
1007 "Random reads and fsync latency on rotating disks are a hundred times slower.",
1008 "move the data directory to solid-state storage",
1009 ));
1010 if disk.kind == DiskKind::Ssd {
1011 push(
1012 out,
1013 &dir.tuning.scheduler,
1014 (
1015 "disk.scheduler",
1016 "Data disk I/O scheduler",
1017 "none or mq-deadline",
1018 "Fair-queueing schedulers add latency that solid-state drives do not need.",
1019 "echo none > /sys/block/<disk>/queue/scheduler, or a udev rule",
1020 ),
1021 |s| (pass_if(s == "none" || s == "mq-deadline"), s.clone()),
1022 );
1023 }
1024 }
1025}
1026
1027#[cfg(target_os = "macos")]
1028const RECOMMENDED_FS: &str = "local APFS";
1029#[cfg(windows)]
1030const RECOMMENDED_FS: &str = "local NTFS or ReFS";
1031#[cfg(target_os = "freebsd")]
1032const RECOMMENDED_FS: &str = "local ZFS or UFS";
1033#[cfg(not(any(target_os = "macos", target_os = "freebsd", windows)))]
1034const RECOMMENDED_FS: &str = "local ext4 or xfs";
1035
1036const RECOMMENDED_FS_NAMES: &[&str] = &["ext4", "xfs", "apfs", "ntfs", "refs", "zfs", "ufs"];
1038
1039fn bench_checks(out: &mut Vec<Check>, env: &crate::bench::Environment) {
1040 use crate::bench::Warning;
1041 let warned = |w| env.warnings.contains(&w);
1042 if let Some(turbo) = env.turbo {
1043 out.push(check(
1044 "cpu.turbo",
1045 "Turbo boost",
1046 pass_if(!turbo),
1047 if turbo { "enabled" } else { "disabled" },
1048 "disabled",
1049 "Turbo frequency depends on temperature and on what other cores do, so runs differ.",
1050 fixes::TURBO,
1051 ));
1052 }
1053 if let Some(throttled) = env.throttled {
1054 out.push(check(
1055 "cpu.throttled",
1056 "Thermal throttling",
1057 pass_if(!throttled),
1058 if throttled { "throttled" } else { "not throttled" },
1059 "not throttled",
1060 "A throttled CPU runs slower than its rated frequency for reasons the benchmark does not control.",
1061 "improve cooling, or let the machine cool down",
1062 ));
1063 }
1064 if let Some(ac) = env.on_ac {
1065 out.push(check(
1066 "power.ac",
1067 "Mains power",
1068 pass_if(ac),
1069 if ac { "on mains" } else { "on battery" },
1070 "on mains",
1071 "On battery the OS lowers frequencies and parks cores.",
1072 "connect the charger",
1073 ));
1074 }
1075 out.push(check(
1076 "cpu.idle",
1077 "Machine idle",
1078 pass_if(!warned(Warning::Busy)),
1079 if warned(Warning::Busy) {
1080 "busy"
1081 } else {
1082 "idle"
1083 },
1084 "idle",
1085 "Other work competes for cores, caches, and memory bandwidth.",
1086 "stop other workloads before measuring",
1087 ));
1088 out.push(check(
1089 "virt.vm",
1090 "Bare metal",
1091 pass_if(!env.virtualized),
1092 if env.virtualized {
1093 "virtual machine"
1094 } else {
1095 "bare metal"
1096 },
1097 "bare metal",
1098 "Other guests share the hardware, and the hypervisor adds exits and steal time.",
1099 "measure on bare metal, or pin the VM to dedicated cores",
1100 ));
1101}
1102
1103#[cfg(test)]
1104mod tests {
1105 use super::*;
1106 use crate::disk::Space;
1107
1108 fn tuned() -> Tuning {
1109 Tuning {
1110 thp: Fact::Value(("madvise".into(), "madvise".into())),
1111 swappiness: Fact::Value(1),
1112 overcommit: Fact::Value((0, 50)),
1113 max_map_count: Fact::Value(262_144),
1114 dirty: Fact::Value(Dirty {
1115 ratio: 10,
1116 background_ratio: 5,
1117 ..Dirty::default()
1118 }),
1119 numa: Fact::Value((0, 0)),
1120 handles_unlimited: false,
1121 files_system: Fact::Value(1 << 20),
1122 files_process: Fact::Value(1 << 20),
1123 memlock: Fact::Value(MemLock::Limit { soft: None }),
1124 backlog: Fact::Value((4096, Some(4096))),
1125 ports: Fact::Value((10_000, 65_535)),
1126 governor: Fact::Value(Governor {
1127 name: "performance".into(),
1128 performance: true,
1129 }),
1130 clock_source: Fact::Value("tsc".into()),
1131 }
1132 }
1133
1134 fn inputs(tuning: Tuning) -> Inputs {
1135 Inputs {
1136 tuning,
1137 open_files_soft: Fact::Value(Some(1 << 20)),
1138 clock_synchronized: Fact::Value(true),
1139 swap_total: Fact::Value(Bytes::new(1 << 30)),
1140 numa_nodes: 2,
1141 container_limits: None,
1142 data_dir: None,
1143 bench: None,
1144 }
1145 }
1146
1147 fn status(r: &Report, id: &str) -> Option<Status> {
1148 r.checks.iter().find(|c| c.id == id).map(|c| c.status)
1149 }
1150
1151 #[test]
1152 fn test_readiness_tuned_database_passes_everything() {
1153 let r = evaluate(Profile::Database, &inputs(tuned()));
1154 assert!(r.passed());
1155 assert!(r.checks.iter().all(|c| c.status == Status::Pass), "{r}");
1156 assert_eq!(status(&r, "linux.numa"), Some(Status::Pass));
1157 }
1158
1159 #[test]
1160 fn test_readiness_untuned_database_warns_and_fails() {
1161 let mut t = tuned();
1162 t.thp = Fact::Value(("always".into(), "madvise".into()));
1163 t.swappiness = Fact::Value(60);
1164 t.overcommit = Fact::Value((1, 50));
1165 t.max_map_count = Fact::Value(65_530);
1166 t.dirty = Fact::Value(Dirty {
1167 ratio: 20,
1168 background_ratio: 10,
1169 ..Dirty::default()
1170 });
1171 t.backlog = Fact::Value((4096, Some(512)));
1172 t.ports = Fact::Value((40_000, 60_999));
1173 t.clock_source = Fact::Value("hpet".into());
1174 t.memlock = Fact::Value(MemLock::Limit {
1175 soft: Some(8 << 20),
1176 });
1177 let mut i = inputs(t);
1178 i.open_files_soft = Fact::Value(Some(1024));
1179 i.swap_total = Fact::Value(Bytes::new(0));
1180 let r = evaluate(Profile::Database, &i);
1181 assert!(!r.passed());
1182 assert_eq!(status(&r, "linux.overcommit"), Some(Status::Fail));
1183 for id in [
1184 "linux.thp",
1185 "linux.swappiness",
1186 "linux.max_map_count",
1187 "linux.dirty",
1188 "net.backlog",
1189 "net.ports",
1190 "clock.source",
1191 "limits.memlock",
1192 "limits.nofile",
1193 "mem.swap",
1194 ] {
1195 assert_eq!(status(&r, id), Some(Status::Warn), "{id}");
1196 }
1197 assert_eq!(r.failures().count(), 1);
1198 let mut t = tuned();
1200 t.ports = Fact::Value((32_768, 60_999));
1201 assert_eq!(
1202 status(&evaluate(Profile::WebServer, &inputs(t)), "net.ports"),
1203 Some(Status::Pass)
1204 );
1205 }
1206
1207 #[test]
1208 fn test_readiness_open_files_floor_fails_servers_only() {
1209 let mut i = inputs(tuned());
1210 i.open_files_soft = Fact::Value(Some(256));
1211 assert_eq!(
1212 status(&evaluate(Profile::WebServer, &i), "limits.nofile"),
1213 Some(Status::Fail)
1214 );
1215 assert_eq!(
1216 status(&evaluate(Profile::General, &i), "limits.nofile"),
1217 Some(Status::Warn)
1218 );
1219 let mut t = tuned();
1220 t.handles_unlimited = true;
1221 let mut i = inputs(t);
1222 i.open_files_soft = Fact::Skip;
1223 assert_eq!(
1224 status(&evaluate(Profile::Database, &i), "limits.nofile"),
1225 Some(Status::Pass)
1226 );
1227 }
1228
1229 #[test]
1230 fn test_readiness_skip_is_left_out_and_unknown_reported() {
1231 let t = Tuning {
1232 swappiness: Fact::Unknown("permission denied".into()),
1233 ..Tuning::default()
1234 };
1235 let mut i = inputs(t);
1236 i.numa_nodes = 1;
1237 let r = evaluate(Profile::Database, &i);
1238 assert_eq!(status(&r, "linux.thp"), None);
1239 assert_eq!(status(&r, "linux.numa"), None);
1240 let c = r
1241 .checks
1242 .iter()
1243 .find(|c| c.id == "linux.swappiness")
1244 .unwrap();
1245 assert_eq!(c.status, Status::Unknown);
1246 assert_eq!(c.found, "permission denied");
1247 assert!(r.passed());
1248 }
1249
1250 #[test]
1251 fn test_readiness_profiles_choose_their_checks() {
1252 let general = evaluate(Profile::General, &inputs(tuned()));
1253 assert_eq!(status(&general, "linux.thp"), None);
1254 assert_eq!(status(&general, "net.backlog"), None);
1255 assert_eq!(status(&general, "cpu.governor"), None);
1256 assert_eq!(status(&general, "clock.sync"), Some(Status::Pass));
1257 let web = evaluate(Profile::WebServer, &inputs(tuned()));
1258 assert_eq!(status(&web, "net.backlog"), Some(Status::Pass));
1259 assert_eq!(status(&web, "linux.swappiness"), None);
1260 }
1261
1262 fn disk(fs: &str, kind: DiskKind, free: u64) -> Disk {
1263 Disk {
1264 mount_point: "/var/lib".into(),
1265 device: "/dev/nvme0n1p2".into(),
1266 label: None,
1267 filesystem: fs.into(),
1268 kind,
1269 space: Some(Space {
1270 total: Bytes::new(100),
1271 free: Bytes::new(free),
1272 available: Bytes::new(free),
1273 }),
1274 read_only: false,
1275 removable: false,
1276 }
1277 }
1278
1279 #[test]
1280 fn test_readiness_display_cannot_be_forged_and_names_no_source() {
1281 let mut i = inputs(tuned());
1283 let mut d = disk("ext4", DiskKind::Ssd, 50);
1284 d.device = "user@server:/x\nFAIL fake.check Injected".into();
1285 d.filesystem = "ext4\nFAIL forged".into();
1286 i.data_dir = Some(DataDir {
1287 disk: Fact::Value(d),
1288 tuning: DataDirTuning::default(),
1289 });
1290 let r = evaluate(Profile::Database, &i);
1291 let text = r.to_string();
1292 assert!(!text.contains("server"), "{text}");
1293 assert!(
1294 !text.lines().any(|l| l.starts_with("FAIL forged")),
1295 "{text}"
1296 );
1297 assert_eq!(text.lines().filter(|l| l.contains("forged")).count(), 1);
1298 }
1299
1300 #[test]
1301 fn test_readiness_data_directory() {
1302 let mut i = inputs(tuned());
1303 i.data_dir = Some(DataDir {
1304 disk: Fact::Value(disk("ext4", DiskKind::Ssd, 50)),
1305 tuning: DataDirTuning {
1306 atime: Fact::Value("relatime".into()),
1307 scheduler: Fact::Value("none".into()),
1308 },
1309 });
1310 let r = evaluate(Profile::Database, &i);
1311 for id in [
1312 "fs.type",
1313 "fs.atime",
1314 "disk.space",
1315 "disk.kind",
1316 "disk.scheduler",
1317 ] {
1318 assert_eq!(status(&r, id), Some(Status::Pass), "{id}");
1319 }
1320 i.data_dir = Some(DataDir {
1321 disk: Fact::Value(disk("nfs4", DiskKind::Network, 3)),
1322 tuning: DataDirTuning {
1323 atime: Fact::Value("strictatime".into()),
1324 scheduler: Fact::Skip,
1325 },
1326 });
1327 let r = evaluate(Profile::Database, &i);
1328 assert_eq!(status(&r, "fs.type"), Some(Status::Fail));
1329 assert_eq!(status(&r, "disk.space"), Some(Status::Fail));
1330 assert_eq!(status(&r, "fs.atime"), Some(Status::Warn));
1331 assert_eq!(status(&r, "disk.scheduler"), None);
1332 assert_eq!(
1333 status(&evaluate(Profile::General, &i), "fs.type"),
1334 Some(Status::Warn)
1335 );
1336 i.data_dir = Some(DataDir {
1337 disk: Fact::Value(disk("btrfs", DiskKind::Hdd, 10)),
1338 tuning: DataDirTuning::default(),
1339 });
1340 let r = evaluate(Profile::Database, &i);
1341 assert_eq!(status(&r, "fs.type"), Some(Status::Warn));
1342 assert_eq!(status(&r, "disk.space"), Some(Status::Warn));
1343 assert_eq!(status(&r, "disk.kind"), Some(Status::Warn));
1344 }
1345
1346 #[test]
1347 fn test_readiness_benchmark_profile() {
1348 let mut i = inputs(tuned());
1349 i.bench = Some(crate::bench::environment());
1350 let r = evaluate(Profile::Benchmark, &i);
1351 assert!(status(&r, "cpu.idle").is_some() && status(&r, "virt.vm").is_some());
1352 assert_eq!(status(&r, "clock.sync"), None);
1353 assert_eq!(status(&r, "cpu.governor"), Some(Status::Pass));
1354 }
1355
1356 #[test]
1357 fn test_readiness_outputs() {
1358 let mut t = tuned();
1359 t.swappiness = Fact::Value(60);
1360 let r = evaluate(Profile::Database, &inputs(t));
1361 let text = r.to_string();
1362 assert!(text.contains("WARN linux.swappiness "), "{text}");
1363 assert!(text.contains("\n sysctl -w vm.swappiness=1"));
1364 let mut kv = String::new();
1365 r.write_kv(&mut kv).unwrap();
1366 assert!(kv.contains("check=linux.swappiness status=WARN found=60 recommended=\"1 to 10\""));
1367 let mut j = String::new();
1368 r.write_json(&mut j).unwrap();
1369 assert!(j.starts_with("{\"profile\":\"database\",\"passed\":true,\"checks\":[{\"id\":"));
1370 assert!(j.ends_with("}]}"));
1371 }
1372
1373 #[test]
1374 fn test_readiness_live_never_fails() {
1375 for p in [
1376 Profile::General,
1377 Profile::Database,
1378 Profile::WebServer,
1379 Profile::Benchmark,
1380 ] {
1381 let r = report_for(p, std::env::temp_dir());
1382 assert_eq!(r.profile, p);
1383 assert!(r.checks.iter().any(|c| c.id == "limits.nofile"), "{r}");
1384 for c in &r.checks {
1385 assert!(!c.title.is_empty() && !c.why.is_empty(), "{c:?}");
1386 }
1387 }
1388 }
1389}