Skip to main content

perforce_cli/cmd/
diagnostics.rs

1use std::path::{Path, PathBuf};
2use std::process::{Child, Command, Stdio};
3
4use super::{ExclusiveOption, SubCommand, Unselected};
5use crate::global::GlobalOpts;
6use crate::spawn::ParameterizedSpawn;
7
8// ---------------------------------------------------------------------------
9// Journal state (-J [-L limit])
10// ---------------------------------------------------------------------------
11
12/// The journal and log copy state of `p4 diagnostics`.
13///
14#[cfg_attr(
15    feature = "lt2025_2",
16    doc = "Carries the optional `-L limit` that caps the downloaded journal and log copy, which the basic form always includes."
17)]
18#[cfg_attr(
19    not(feature = "lt2025_2"),
20    doc = "Downloads a copy of the current journal file and log file (`-J`), optionally capped by `-L limit`."
21)]
22///
23/// Entered with [`Diagnostics::journal`].
24#[derive(Debug, Clone, Default)]
25pub struct Journal {
26    limit: Option<String>,
27}
28
29impl ExclusiveOption for Journal {
30    fn inject_args(&self, command: &mut Command) {
31        #[cfg(not(feature = "lt2025_2"))]
32        command.arg("-J");
33
34        if let Some(limit) = &self.limit {
35            command.arg("-L").arg(limit);
36        }
37    }
38}
39
40// ---------------------------------------------------------------------------
41// Strace state (-s [--strace-runtime secs])
42// ---------------------------------------------------------------------------
43
44/// The `strace` state of the advance form of `p4 diagnostics`.
45///
46#[cfg_attr(
47    feature = "lt2025_2",
48    doc = "Runs an `strace` command on the server processes for 20 seconds (`-s`)."
49)]
50#[cfg_attr(
51    not(feature = "lt2025_2"),
52    doc = "Runs an `strace` command on the server processes (`-s`), for 20 seconds by default or for the number of seconds given by `--strace-runtime secs`."
53)]
54///
55/// Entered with [`Diagnostics::run_strace`] or
56/// [`Diagnostics::run_strace_with`].
57#[derive(Debug, Clone, Default)]
58pub struct Strace {
59    #[cfg(not(feature = "lt2025_2"))]
60    runtime: Option<u64>,
61}
62
63impl ExclusiveOption for Strace {
64    fn inject_args(&self, command: &mut Command) {
65        command.arg("-s");
66
67        #[cfg(not(feature = "lt2025_2"))]
68        if let Some(runtime) = self.runtime {
69            command.arg("--strace-runtime").arg(runtime.to_string());
70        }
71    }
72}
73
74// ---------------------------------------------------------------------------
75// Basic form state (-j, -J [-L limit])
76// ---------------------------------------------------------------------------
77
78/// The basic form of `p4 diagnostics`.
79///
80#[cfg_attr(
81    feature = "lt2025_2",
82    doc = "Selected by `-L limit`; [`Diagnostics::basic`] enters this form explicitly."
83)]
84#[cfg_attr(
85    not(feature = "lt2025_2"),
86    doc = "Selected by `-j`, `-J`, or `-L limit`; [`Diagnostics::basic`] and [`Diagnostics::json_format`] enter this form."
87)]
88///
89/// The `J` type parameter tracks the [`Journal`] state, starting as
90/// [`Unselected`].
91#[derive(Debug, Clone, Default)]
92pub struct Basic<J = Unselected> {
93    #[cfg(not(feature = "lt2025_2"))]
94    json_format: bool,
95
96    journal: J,
97}
98
99impl<J: ExclusiveOption> ExclusiveOption for Basic<J> {
100    fn inject_args(&self, command: &mut Command) {
101        #[cfg(not(feature = "lt2025_2"))]
102        if self.json_format {
103            command.arg("-j");
104        }
105
106        self.journal.inject_args(command);
107    }
108}
109
110// ---------------------------------------------------------------------------
111// Basic-files state of the advance form (-a [-J [-L limit]])
112// ---------------------------------------------------------------------------
113
114/// The basic diagnostic files state of the advance form of `p4 diagnostics`.
115///
116/// Requests that the basic diagnostic files are produced alongside the
117/// advance-form data (`-a`). Entered with
118/// [`Diagnostics::advance_with_basic`] or [`Diagnostics::with_basic`];
119/// [`Diagnostics::journal`] then selects whether the journal and log copy is
120/// also downloaded.
121///
122/// The `J` type parameter tracks the [`Journal`] state, starting as
123/// [`Unselected`].
124#[derive(Debug, Clone, Default)]
125pub struct WithBasic<J = Unselected> {
126    journal: J,
127}
128
129impl<J: ExclusiveOption> ExclusiveOption for WithBasic<J> {
130    fn inject_args(&self, command: &mut Command) {
131        command.arg("-a");
132
133        self.journal.inject_args(command);
134    }
135}
136
137// ---------------------------------------------------------------------------
138// Advance form state (-l, -s, -p, -t, -a)
139// ---------------------------------------------------------------------------
140
141/// The advance form of `p4 diagnostics`.
142///
143#[cfg_attr(
144    feature = "lt2025_2",
145    doc = "Selected by `-l`, `-s`, or `-a`; [`Diagnostics::advance_with_basic`] enters this form explicitly."
146)]
147#[cfg_attr(
148    not(feature = "lt2025_2"),
149    doc = "Selected by `-l`, `-s`, `-p`, `-t`, or `-a`; [`Diagnostics::advance_with_basic`] enters this form explicitly."
150)]
151///
152/// The `S` type parameter tracks the [`Strace`] state and the `B` type
153/// parameter tracks the [`WithBasic`] state, each starting as
154/// [`Unselected`].
155#[derive(Debug, Clone, Default)]
156pub struct Advance<S = Unselected, B = Unselected> {
157    run_lsof: bool,
158
159    #[cfg(not(feature = "lt2025_2"))]
160    run_ps: bool,
161
162    #[cfg(not(feature = "lt2025_2"))]
163    run_top: bool,
164
165    strace: S,
166
167    basic: B,
168}
169
170impl<S: ExclusiveOption, B: ExclusiveOption> ExclusiveOption for Advance<S, B> {
171    fn inject_args(&self, command: &mut Command) {
172        if self.run_lsof {
173            command.arg("-l");
174        }
175
176        self.strace.inject_args(command);
177
178        #[cfg(not(feature = "lt2025_2"))]
179        if self.run_ps {
180            command.arg("-p");
181        }
182
183        #[cfg(not(feature = "lt2025_2"))]
184        if self.run_top {
185            command.arg("-t");
186        }
187
188        self.basic.inject_args(command);
189    }
190}
191
192// ---------------------------------------------------------------------------
193// Command
194// ---------------------------------------------------------------------------
195
196#[cfg_attr(
197    feature = "lt2025_2",
198    doc = "`p4 [g-opts] diagnostics [-L limit]`\n\n\
199           `p4 [g-opts] diagnostics [-l] [-s] [-a [-L limit]]`"
200)]
201#[cfg_attr(
202    not(feature = "lt2025_2"),
203    doc = "`p4 [g-opts] diagnostics [-D] [-j] [-J [-L limit]]`\n\n\
204           `p4 [g-opts] diagnostics [-D] [-l] [-s [--strace-runtime secs]] [-p] [-t] [-a [-J [-L limit]]]`"
205)]
206///
207/// Generate diagnostic data about the P4 Server.
208///
209#[cfg_attr(
210    feature = "lt2025_2",
211    doc = "This command is a Technology Preview feature. Features offered in Technology Preview are experimental and not guaranteed to always work as expected. If you have feedback and functionality suggestions, email techpreview@perforce.com.",
212    doc = "",
213    doc = "The output format is subject to change. This command is currently intended for use under guidance by Perforce Support."
214)]
215#[cfg_attr(
216    feature = "lt2025_2",
217    doc = "",
218    doc = "The first form of the command, `p4 [g-opts] diagnostics [-L limit]`, generates the basic diagnostic data and downloads it to a number of fixed named files in the current directory:",
219    doc = "",
220    doc = "- `diags` - basic configuration details, configuration, configuration history, server setting, and checkpoint history.",
221    doc = "- `monitor` - the monitor records, if monitoring is enabled.",
222    doc = "- `topology` - a textual description of the network that contains this server.",
223    doc = "- A copy of the current `journal` and `log` files, using the configured names of these files.",
224    doc = "",
225    doc = "The second form of the command, `p4 [g-opts] diagnostics [-l] [-s] [-a [-L limit]]`, provides information that might take more time and require more server resources."
226)]
227#[cfg_attr(
228    not(feature = "lt2025_2"),
229    doc = "",
230    doc = "The first form of the command generates the basic diagnostic data, and downloads a compressed tar file (`.tgz`) that contains these files:",
231    doc = "",
232    doc = "- `diags` - basic configuration details, configuration, configuration history, server setting.",
233    doc = "- `info` - tagged output from the `p4 info` and `p4 servers -J` commands, and a list of all non-default configurables.",
234    doc = "- `monitor` - the monitor records, if monitoring is enabled.",
235    doc = "- `topology` - a textual description of the network that contains this server. Servers that do not have a serverID are ignored.",
236    doc = "",
237    doc = "The second form of the command provides information that might take more time and require more server resources."
238)]
239///
240#[cfg_attr(
241    feature = "lt2025_2",
242    doc = "The `M` type parameter tracks the command form at compile time. The default [`Unselected`] state selects the basic form with no local options; `journal` and `basic` enter the [`Basic`] state, while `advance`, `advance_with_basic`, and the `run_*` transitions enter the [`Advance`] state."
243)]
244#[cfg_attr(
245    not(feature = "lt2025_2"),
246    doc = "The `M` type parameter tracks the command form at compile time. The default [`Unselected`] state selects the basic form with no local options; `journal`, `json_format`, and `basic` enter the [`Basic`] state, while `advance`, `advance_with_basic`, and the `run_*` transitions enter the [`Advance`] state."
247)]
248#[derive(Debug, Clone, Default)]
249pub struct Diagnostics<M = Unselected> {
250    bin: PathBuf,
251
252    global_opts: GlobalOpts,
253
254    #[cfg(not(feature = "lt2025_2"))]
255    uncompressed: bool,
256
257    mode: M,
258}
259
260impl Diagnostics<Unselected> {
261    /// Creates a new `p4 diagnostics` command.
262    ///
263    /// `bin` is the path to the Perforce command-line executable.
264    pub fn new(bin: impl Into<PathBuf>, global_opts: GlobalOpts) -> Self {
265        Self {
266            bin: bin.into(),
267            global_opts,
268            #[cfg(not(feature = "lt2025_2"))]
269            uncompressed: false,
270            mode: Unselected,
271        }
272    }
273
274    /// Enters the [`Basic`] form of the command with no local options
275    /// selected; equivalent to the default [`Unselected`] state.
276    pub fn basic(self) -> Diagnostics<Basic<Unselected>> {
277        Diagnostics {
278            bin: self.bin,
279            global_opts: self.global_opts,
280            #[cfg(not(feature = "lt2025_2"))]
281            uncompressed: self.uncompressed,
282            mode: Basic {
283                #[cfg(not(feature = "lt2025_2"))]
284                json_format: false,
285                journal: Unselected,
286            },
287        }
288    }
289
290    /// # Description
291    ///
292    /// -j
293    ///
294    /// Request that the `diags` and `monitor` files are encoded in JSON
295    /// format. These output files are named `diags.json` and `monitor.json`.
296    /// Any non-UFT8 sequences in a string are replaced by U+FFFD in the JSON
297    /// output.
298    ///
299    /// Enters the [`Basic`] form of the command.
300    #[cfg(not(feature = "lt2025_2"))]
301    pub fn json_format(self) -> Diagnostics<Basic<Unselected>> {
302        Diagnostics {
303            bin: self.bin,
304            global_opts: self.global_opts,
305            uncompressed: self.uncompressed,
306            mode: Basic {
307                json_format: true,
308                journal: Unselected,
309            },
310        }
311    }
312
313    /// # Description
314    ///
315    /// -J [-L limit]
316    ///
317    /// Downloads a copy of the current journal file and log file, using the
318    /// configured names of these files.
319    ///
320    /// Enters the [`Basic`] form of the command with the [`Journal`] state
321    /// selected.
322    #[cfg(not(feature = "lt2025_2"))]
323    pub fn journal(self) -> Diagnostics<Basic<Journal>> {
324        Diagnostics {
325            bin: self.bin,
326            global_opts: self.global_opts,
327            #[cfg(not(feature = "lt2025_2"))]
328            uncompressed: self.uncompressed,
329            mode: Basic {
330                #[cfg(not(feature = "lt2025_2"))]
331                json_format: false,
332                journal: Journal::default(),
333            },
334        }
335    }
336
337    /// # Description
338    ///
339    /// -L limit
340    ///
341    /// The basic form always includes a copy of the journal and log files;
342    /// this caps their download at the last `limit` bytes.
343    ///
344    /// Enters the [`Journal`] state with the journal and log copy limited to
345    /// `limit`.
346    #[cfg(feature = "lt2025_2")]
347    pub fn limit(self, limit: impl Into<String>) -> Diagnostics<Basic<Journal>> {
348        Diagnostics {
349            bin: self.bin,
350            global_opts: self.global_opts,
351            mode: Basic {
352                journal: Journal {
353                    limit: Some(limit.into()),
354                },
355            },
356        }
357    }
358
359    /// # Description
360    ///
361    /// -a
362    ///
363    #[cfg_attr(
364        feature = "lt2025_2",
365        doc = "Requests that the basic diagnostic files are produced. Without this option, those files are omitted with the `-l` and `-s` options."
366    )]
367    #[cfg_attr(
368        not(feature = "lt2025_2"),
369        doc = "Requests that the basic diagnostic files are produced. Without this option, those files are omitted with the `-l`, `-t`, `-p`, and `-s` options."
370    )]
371    ///
372    /// Enters the [`Advance`] form of the command with the [`WithBasic`]
373    /// state selected.
374    pub fn advance_with_basic(self) -> Diagnostics<Advance<Unselected, WithBasic<Unselected>>> {
375        Diagnostics {
376            bin: self.bin,
377            global_opts: self.global_opts,
378            #[cfg(not(feature = "lt2025_2"))]
379            uncompressed: self.uncompressed,
380            mode: Advance {
381                run_lsof: false,
382                #[cfg(not(feature = "lt2025_2"))]
383                run_ps: false,
384                #[cfg(not(feature = "lt2025_2"))]
385                run_top: false,
386                strace: Unselected,
387                basic: WithBasic::default(),
388            },
389        }
390    }
391
392    /// # Description
393    ///
394    /// -l
395    ///
396    /// Request that the `/usr/bin/lsof` be run to provide locking details of
397    /// all files in use by P4 Servers on this system.
398    #[cfg_attr(
399        feature = "lt2025_2",
400        doc = "The data from this operation is downloaded into a file named `manuallocks` in the current directory."
401    )]
402    #[cfg_attr(
403        not(feature = "lt2025_2"),
404        doc = "The data from this operation is downloaded into a file named `manuallocks`."
405    )]
406    /// *This option is not supported on Windows.*
407    ///
408    /// Enters the [`Advance`] form of the command.
409    pub fn run_lsof(self) -> Diagnostics<Advance<Unselected, Unselected>> {
410        Diagnostics {
411            bin: self.bin,
412            global_opts: self.global_opts,
413            #[cfg(not(feature = "lt2025_2"))]
414            uncompressed: self.uncompressed,
415            mode: Advance {
416                run_lsof: true,
417                #[cfg(not(feature = "lt2025_2"))]
418                run_ps: false,
419                #[cfg(not(feature = "lt2025_2"))]
420                run_top: false,
421                strace: Unselected,
422                basic: Unselected,
423            },
424        }
425    }
426
427    /// # Description
428    ///
429    /// -p
430    ///
431    /// Run the `ps` program and returns its output.
432    ///
433    /// Enters the [`Advance`] form of the command.
434    #[cfg(not(feature = "lt2025_2"))]
435    pub fn run_ps(self) -> Diagnostics<Advance<Unselected, Unselected>> {
436        Diagnostics {
437            bin: self.bin,
438            global_opts: self.global_opts,
439            uncompressed: self.uncompressed,
440            mode: Advance {
441                run_lsof: false,
442                run_ps: true,
443                run_top: false,
444                strace: Unselected,
445                basic: Unselected,
446            },
447        }
448    }
449
450    /// # Description
451    ///
452    /// -t
453    ///
454    /// Run the `top` program and returns its output.
455    ///
456    /// Enters the [`Advance`] form of the command.
457    #[cfg(not(feature = "lt2025_2"))]
458    pub fn run_top(self) -> Diagnostics<Advance<Unselected, Unselected>> {
459        Diagnostics {
460            bin: self.bin,
461            global_opts: self.global_opts,
462            uncompressed: self.uncompressed,
463            mode: Advance {
464                run_lsof: false,
465                run_ps: false,
466                run_top: true,
467                strace: Unselected,
468                basic: Unselected,
469            },
470        }
471    }
472
473    /// # Description
474    ///
475    /// -s
476    ///
477    #[cfg_attr(
478        feature = "lt2025_2",
479        doc = "Run an `strace` command on the server processes for 20 seconds and downloads the trace output to a file named `strace` in the current directory. *This option is not yet supported on any platform.*"
480    )]
481    #[cfg_attr(
482        not(feature = "lt2025_2"),
483        doc = "Run an `strace` command on the server processes for 20 seconds. The data from this operation is downloaded into a file named `strace`. *The `strace` Linux command is not supported on Windows.*"
484    )]
485    ///
486    /// Enters the [`Advance`] form of the command with the [`Strace`] state
487    /// selected.
488    pub fn run_strace(self) -> Diagnostics<Advance<Strace, Unselected>> {
489        Diagnostics {
490            bin: self.bin,
491            global_opts: self.global_opts,
492            #[cfg(not(feature = "lt2025_2"))]
493            uncompressed: self.uncompressed,
494            mode: Advance {
495                run_lsof: false,
496                #[cfg(not(feature = "lt2025_2"))]
497                run_ps: false,
498                #[cfg(not(feature = "lt2025_2"))]
499                run_top: false,
500                strace: Strace::default(),
501                basic: Unselected,
502            },
503        }
504    }
505
506    /// # Description
507    ///
508    /// `-s --strace-runtime secs`
509    ///
510    /// Run an `strace` command on the server processes for `secs` seconds
511    /// instead of the default 20. The data from this operation is
512    /// downloaded into a file named `strace`.
513    /// *The `strace` Linux command is not supported on Windows.*
514    ///
515    /// Enters the [`Advance`] form of the command with the [`Strace`] state
516    /// selected.
517    #[cfg(not(feature = "lt2025_2"))]
518    pub fn run_strace_with(self, runtime: u64) -> Diagnostics<Advance<Strace, Unselected>> {
519        Diagnostics {
520            bin: self.bin,
521            global_opts: self.global_opts,
522            uncompressed: self.uncompressed,
523            mode: Advance {
524                run_lsof: false,
525                run_ps: false,
526                run_top: false,
527                strace: Strace {
528                    runtime: Some(runtime),
529                },
530                basic: Unselected,
531            },
532        }
533    }
534}
535
536impl<J: ExclusiveOption> Diagnostics<Basic<J>> {
537    /// # Description
538    ///
539    /// -j
540    ///
541    /// Request that the `diags` and `monitor` files are encoded in JSON
542    /// format. These output files are named `diags.json` and `monitor.json`.
543    /// Any non-UFT8 sequences in a string are replaced by U+FFFD in the JSON
544    /// output.
545    #[cfg(not(feature = "lt2025_2"))]
546    pub fn get_json_format(&self) -> bool {
547        self.mode.json_format
548    }
549
550    /// # Description
551    ///
552    /// -j
553    ///
554    /// Request that the `diags` and `monitor` files are encoded in JSON
555    /// format. These output files are named `diags.json` and `monitor.json`.
556    /// Any non-UFT8 sequences in a string are replaced by U+FFFD in the JSON
557    /// output.
558    #[cfg(not(feature = "lt2025_2"))]
559    pub fn set_json_format(&mut self, v: bool) -> &mut Self {
560        self.mode.json_format = v;
561        self
562    }
563
564    /// # Description
565    ///
566    /// -j
567    ///
568    /// Request that the `diags` and `monitor` files are encoded in JSON
569    /// format. These output files are named `diags.json` and `monitor.json`.
570    /// Any non-UFT8 sequences in a string are replaced by U+FFFD in the JSON
571    /// output.
572    #[cfg(not(feature = "lt2025_2"))]
573    pub fn json_format(mut self, v: bool) -> Self {
574        self.mode.json_format = v;
575        self
576    }
577}
578
579impl Diagnostics<Basic<Unselected>> {
580    /// # Description
581    ///
582    /// -J [-L limit]
583    ///
584    /// Downloads a copy of the current journal file and log file, using the
585    /// configured names of these files.
586    ///
587    /// Enters the [`Basic`] form of the command with the [`Journal`] state
588    /// selected.
589    #[cfg(not(feature = "lt2025_2"))]
590    pub fn journal(self) -> Diagnostics<Basic<Journal>> {
591        Diagnostics {
592            bin: self.bin,
593            global_opts: self.global_opts,
594            #[cfg(not(feature = "lt2025_2"))]
595            uncompressed: self.uncompressed,
596            mode: Basic {
597                #[cfg(not(feature = "lt2025_2"))]
598                json_format: self.mode.json_format,
599                journal: Journal::default(),
600            },
601        }
602    }
603
604    /// # Description
605    ///
606    /// -J [-L limit]
607    ///
608    /// Downloads a copy of the current journal file and log file, using the
609    /// configured names of these files.
610    ///
611    /// Enters the [`Basic`] form of the command with the [`Journal`] state
612    /// selected and the download limited to `limit`.
613    #[cfg(not(feature = "lt2025_2"))]
614    pub fn journal_with(self, limit: impl Into<String>) -> Diagnostics<Basic<Journal>> {
615        self.journal().limit(limit)
616    }
617
618    /// # Description
619    ///
620    /// -L limit
621    ///
622    /// The basic form always includes a copy of the journal and log files;
623    /// this caps their download at the last `limit` bytes.
624    ///
625    /// Enters the [`Journal`] state with the journal and log copy limited to
626    /// `limit`.
627    #[cfg(feature = "lt2025_2")]
628    pub fn limit(self, limit: impl Into<String>) -> Diagnostics<Basic<Journal>> {
629        Diagnostics {
630            bin: self.bin,
631            global_opts: self.global_opts,
632            mode: Basic {
633                journal: Journal {
634                    limit: Some(limit.into()),
635                },
636            },
637        }
638    }
639}
640
641impl Diagnostics<Basic<Journal>> {
642    /// # Description
643    ///
644    /// -L limit
645    ///
646    /// Limit the download size of the journal and log files to the last
647    /// `limit` number of bytes of these files, subject to buffer rounding. The
648    /// `limit` is in bytes and can be suffixed with a single character to
649    /// designate a unit multiplier: `k` or `K` for kilobytes, `m` or `M` for
650    /// megabytes, `g` or `G` for gigabytes, and `t` or `T` for terabytes.
651    pub fn get_limit(&self) -> Option<&str> {
652        self.mode.journal.limit.as_deref()
653    }
654
655    /// # Description
656    ///
657    /// -L limit
658    ///
659    /// Limit the download size of the journal and log files to the last
660    /// `limit` number of bytes of these files, subject to buffer rounding. The
661    /// `limit` is in bytes and can be suffixed with a single character to
662    /// designate a unit multiplier: `k` or `K` for kilobytes, `m` or `M` for
663    /// megabytes, `g` or `G` for gigabytes, and `t` or `T` for terabytes.
664    pub fn set_limit(&mut self, v: impl Into<String>) -> &mut Self {
665        self.mode.journal.limit = Some(v.into());
666        self
667    }
668
669    /// # Description
670    ///
671    /// -L limit
672    ///
673    /// Limit the download size of the journal and log files to the last
674    /// `limit` number of bytes of these files, subject to buffer rounding. The
675    /// `limit` is in bytes and can be suffixed with a single character to
676    /// designate a unit multiplier: `k` or `K` for kilobytes, `m` or `M` for
677    /// megabytes, `g` or `G` for gigabytes, and `t` or `T` for terabytes.
678    pub fn limit(mut self, v: impl Into<String>) -> Self {
679        self.mode.journal.limit = Some(v.into());
680        self
681    }
682}
683
684impl<S: ExclusiveOption, B: ExclusiveOption> Diagnostics<Advance<S, B>> {
685    /// # Description
686    ///
687    /// -l
688    ///
689    /// Request that the `/usr/bin/lsof` be run to provide locking details of
690    /// all files in use by P4 Servers on this system.
691    #[cfg_attr(
692        feature = "lt2025_2",
693        doc = "The data from this operation is downloaded into a file named `manuallocks` in the current directory."
694    )]
695    #[cfg_attr(
696        not(feature = "lt2025_2"),
697        doc = "The data from this operation is downloaded into a file named `manuallocks`."
698    )]
699    /// *This option is not supported on Windows.*
700    pub fn get_run_lsof(&self) -> bool {
701        self.mode.run_lsof
702    }
703
704    /// # Description
705    ///
706    /// -l
707    ///
708    /// Request that the `/usr/bin/lsof` be run to provide locking details of
709    /// all files in use by P4 Servers on this system.
710    #[cfg_attr(
711        feature = "lt2025_2",
712        doc = "The data from this operation is downloaded into a file named `manuallocks` in the current directory."
713    )]
714    #[cfg_attr(
715        not(feature = "lt2025_2"),
716        doc = "The data from this operation is downloaded into a file named `manuallocks`."
717    )]
718    /// *This option is not supported on Windows.*
719    pub fn set_run_lsof(&mut self, v: bool) -> &mut Self {
720        self.mode.run_lsof = v;
721        self
722    }
723
724    /// # Description
725    ///
726    /// -l
727    ///
728    /// Request that the `/usr/bin/lsof` be run to provide locking details of
729    /// all files in use by P4 Servers on this system.
730    #[cfg_attr(
731        feature = "lt2025_2",
732        doc = "The data from this operation is downloaded into a file named `manuallocks` in the current directory."
733    )]
734    #[cfg_attr(
735        not(feature = "lt2025_2"),
736        doc = "The data from this operation is downloaded into a file named `manuallocks`."
737    )]
738    /// *This option is not supported on Windows.*
739    pub fn run_lsof(mut self, v: bool) -> Self {
740        self.mode.run_lsof = v;
741        self
742    }
743
744    /// # Description
745    ///
746    /// -p
747    ///
748    /// Run the `ps` program and returns its output.
749    #[cfg(not(feature = "lt2025_2"))]
750    pub fn get_run_ps(&self) -> bool {
751        self.mode.run_ps
752    }
753
754    /// # Description
755    ///
756    /// -p
757    ///
758    /// Run the `ps` program and returns its output.
759    #[cfg(not(feature = "lt2025_2"))]
760    pub fn set_run_ps(&mut self, v: bool) -> &mut Self {
761        self.mode.run_ps = v;
762        self
763    }
764
765    /// # Description
766    ///
767    /// -p
768    ///
769    /// Run the `ps` program and returns its output.
770    #[cfg(not(feature = "lt2025_2"))]
771    pub fn run_ps(mut self, v: bool) -> Self {
772        self.mode.run_ps = v;
773        self
774    }
775
776    /// # Description
777    ///
778    /// -t
779    ///
780    /// Run the `top` program and returns its output.
781    #[cfg(not(feature = "lt2025_2"))]
782    pub fn get_run_top(&self) -> bool {
783        self.mode.run_top
784    }
785
786    /// # Description
787    ///
788    /// -t
789    ///
790    /// Run the `top` program and returns its output.
791    #[cfg(not(feature = "lt2025_2"))]
792    pub fn set_run_top(&mut self, v: bool) -> &mut Self {
793        self.mode.run_top = v;
794        self
795    }
796
797    /// # Description
798    ///
799    /// -t
800    ///
801    /// Run the `top` program and returns its output.
802    #[cfg(not(feature = "lt2025_2"))]
803    pub fn run_top(mut self, v: bool) -> Self {
804        self.mode.run_top = v;
805        self
806    }
807
808    /// # Description
809    ///
810    /// -s
811    ///
812    #[cfg_attr(
813        feature = "lt2025_2",
814        doc = "Run an `strace` command on the server processes for 20 seconds and downloads the trace output to a file named `strace` in the current directory. *This option is not yet supported on any platform.*"
815    )]
816    #[cfg_attr(
817        not(feature = "lt2025_2"),
818        doc = "Run an `strace` command on the server processes for 20 seconds. The data from this operation is downloaded into a file named `strace`. *The `strace` Linux command is not supported on Windows.*"
819    )]
820    pub fn run_strace(self) -> Diagnostics<Advance<Strace, B>> {
821        Diagnostics {
822            bin: self.bin,
823            global_opts: self.global_opts,
824            #[cfg(not(feature = "lt2025_2"))]
825            uncompressed: self.uncompressed,
826            mode: Advance {
827                run_lsof: self.mode.run_lsof,
828                #[cfg(not(feature = "lt2025_2"))]
829                run_ps: self.mode.run_ps,
830                #[cfg(not(feature = "lt2025_2"))]
831                run_top: self.mode.run_top,
832                strace: Strace::default(),
833                basic: self.mode.basic,
834            },
835        }
836    }
837
838    /// # Description
839    ///
840    /// `-s --strace-runtime secs`
841    ///
842    /// Run an `strace` command on the server processes for `secs` seconds
843    /// instead of the default 20. The data from this operation is
844    /// downloaded into a file named `strace`.
845    /// *The `strace` Linux command is not supported on Windows.*
846    #[cfg(not(feature = "lt2025_2"))]
847    pub fn run_strace_with(self, runtime: u64) -> Diagnostics<Advance<Strace, B>> {
848        Diagnostics {
849            bin: self.bin,
850            global_opts: self.global_opts,
851            uncompressed: self.uncompressed,
852            mode: Advance {
853                run_lsof: self.mode.run_lsof,
854                run_ps: self.mode.run_ps,
855                run_top: self.mode.run_top,
856                strace: Strace {
857                    runtime: Some(runtime),
858                },
859                basic: self.mode.basic,
860            },
861        }
862    }
863}
864
865impl<S: ExclusiveOption> Diagnostics<Advance<S, Unselected>> {
866    /// # Description
867    ///
868    /// -a
869    ///
870    #[cfg_attr(
871        feature = "lt2025_2",
872        doc = "Requests that the basic diagnostic files are produced. Without this option, those files are omitted with the `-l` and `-s` options."
873    )]
874    #[cfg_attr(
875        not(feature = "lt2025_2"),
876        doc = "Requests that the basic diagnostic files are produced. Without this option, those files are omitted with the `-l`, `-t`, `-p`, and `-s` options."
877    )]
878    ///
879    /// Transitions this command to the [`WithBasic`] state.
880    pub fn with_basic(self) -> Diagnostics<Advance<S, WithBasic<Unselected>>> {
881        Diagnostics {
882            bin: self.bin,
883            global_opts: self.global_opts,
884            #[cfg(not(feature = "lt2025_2"))]
885            uncompressed: self.uncompressed,
886            mode: Advance {
887                run_lsof: self.mode.run_lsof,
888                #[cfg(not(feature = "lt2025_2"))]
889                run_ps: self.mode.run_ps,
890                #[cfg(not(feature = "lt2025_2"))]
891                run_top: self.mode.run_top,
892                strace: self.mode.strace,
893                basic: WithBasic::default(),
894            },
895        }
896    }
897}
898
899impl<S: ExclusiveOption> Diagnostics<Advance<S, WithBasic<Unselected>>> {
900    /// # Description
901    ///
902    /// -J [-L limit]
903    ///
904    /// Downloads a copy of the current journal file and log file, using the
905    /// configured names of these files.
906    ///
907    /// Transitions this command to the [`Journal`] state.
908    #[cfg(not(feature = "lt2025_2"))]
909    pub fn journal(self) -> Diagnostics<Advance<S, WithBasic<Journal>>> {
910        Diagnostics {
911            bin: self.bin,
912            global_opts: self.global_opts,
913            #[cfg(not(feature = "lt2025_2"))]
914            uncompressed: self.uncompressed,
915            mode: Advance {
916                run_lsof: self.mode.run_lsof,
917                #[cfg(not(feature = "lt2025_2"))]
918                run_ps: self.mode.run_ps,
919                #[cfg(not(feature = "lt2025_2"))]
920                run_top: self.mode.run_top,
921                strace: self.mode.strace,
922                basic: WithBasic {
923                    journal: Journal::default(),
924                },
925            },
926        }
927    }
928
929    /// # Description
930    ///
931    /// -J [-L limit]
932    ///
933    /// Downloads a copy of the current journal file and log file, using the
934    /// configured names of these files.
935    ///
936    /// Transitions this command to the [`Journal`] state with the download
937    /// limited to `limit`.
938    #[cfg(not(feature = "lt2025_2"))]
939    pub fn journal_with(
940        self,
941        limit: impl Into<String>,
942    ) -> Diagnostics<Advance<S, WithBasic<Journal>>> {
943        self.journal().limit(limit)
944    }
945
946    /// # Description
947    ///
948    /// -L limit
949    ///
950    /// The basic diagnostic files always include a copy of the journal and
951    /// log files; this caps their download at the last `limit` bytes.
952    ///
953    /// Transitions this command to the [`Journal`] state with the journal and
954    /// log copy limited to `limit`.
955    #[cfg(feature = "lt2025_2")]
956    pub fn limit(self, limit: impl Into<String>) -> Diagnostics<Advance<S, WithBasic<Journal>>> {
957        Diagnostics {
958            bin: self.bin,
959            global_opts: self.global_opts,
960            mode: Advance {
961                run_lsof: self.mode.run_lsof,
962                strace: self.mode.strace,
963                basic: WithBasic {
964                    journal: Journal {
965                        limit: Some(limit.into()),
966                    },
967                },
968            },
969        }
970    }
971}
972
973impl<S: ExclusiveOption> Diagnostics<Advance<S, WithBasic<Journal>>> {
974    /// # Description
975    ///
976    /// -L limit
977    ///
978    /// Limit the download size of the journal and log files to the last
979    /// `limit` number of bytes of these files, subject to buffer rounding. The
980    /// `limit` is in bytes and can be suffixed with a single character to
981    /// designate a unit multiplier: `k` or `K` for kilobytes, `m` or `M` for
982    /// megabytes, `g` or `G` for gigabytes, and `t` or `T` for terabytes.
983    pub fn get_limit(&self) -> Option<&str> {
984        self.mode.basic.journal.limit.as_deref()
985    }
986
987    /// # Description
988    ///
989    /// -L limit
990    ///
991    /// Limit the download size of the journal and log files to the last
992    /// `limit` number of bytes of these files, subject to buffer rounding. The
993    /// `limit` is in bytes and can be suffixed with a single character to
994    /// designate a unit multiplier: `k` or `K` for kilobytes, `m` or `M` for
995    /// megabytes, `g` or `G` for gigabytes, and `t` or `T` for terabytes.
996    pub fn set_limit(&mut self, v: impl Into<String>) -> &mut Self {
997        self.mode.basic.journal.limit = Some(v.into());
998        self
999    }
1000
1001    /// # Description
1002    ///
1003    /// -L limit
1004    ///
1005    /// Limit the download size of the journal and log files to the last
1006    /// `limit` number of bytes of these files, subject to buffer rounding. The
1007    /// `limit` is in bytes and can be suffixed with a single character to
1008    /// designate a unit multiplier: `k` or `K` for kilobytes, `m` or `M` for
1009    /// megabytes, `g` or `G` for gigabytes, and `t` or `T` for terabytes.
1010    pub fn limit(mut self, v: impl Into<String>) -> Self {
1011        self.mode.basic.journal.limit = Some(v.into());
1012        self
1013    }
1014}
1015
1016impl<B: ExclusiveOption> Diagnostics<Advance<Strace, B>> {
1017    /// # Description
1018    ///
1019    /// `--strace-runtime secs`
1020    ///
1021    /// Run the `strace` command for `secs` seconds instead of the default 20.
1022    #[cfg(not(feature = "lt2025_2"))]
1023    pub fn get_strace_runtime(&self) -> Option<u64> {
1024        self.mode.strace.runtime
1025    }
1026
1027    /// # Description
1028    ///
1029    /// `--strace-runtime secs`
1030    ///
1031    /// Run the `strace` command for `secs` seconds instead of the default 20.
1032    #[cfg(not(feature = "lt2025_2"))]
1033    pub fn set_strace_runtime(&mut self, v: u64) -> &mut Self {
1034        self.mode.strace.runtime = Some(v);
1035        self
1036    }
1037
1038    /// # Description
1039    ///
1040    /// `--strace-runtime secs`
1041    ///
1042    /// Run the `strace` command for `secs` seconds instead of the default 20.
1043    #[cfg(not(feature = "lt2025_2"))]
1044    pub fn strace_runtime(mut self, v: u64) -> Self {
1045        self.mode.strace.runtime = Some(v);
1046        self
1047    }
1048}
1049
1050impl<M: ExclusiveOption> Diagnostics<M> {
1051    /// Get the Perforce command path.
1052    pub fn get_bin(&self) -> &Path {
1053        &self.bin
1054    }
1055
1056    /// Set the Perforce command path.
1057    pub fn set_bin(&mut self, bin: impl Into<PathBuf>) -> &mut Self {
1058        self.bin = bin.into();
1059        self
1060    }
1061
1062    /// Set the Perforce command path.
1063    pub fn bin(mut self, bin: impl Into<PathBuf>) -> Self {
1064        self.set_bin(bin);
1065        self
1066    }
1067
1068    /// # Description
1069    ///
1070    /// -D
1071    ///
1072    /// Create a new directory and download the requested uncompressed
1073    /// individual files into this new directory. Without this option,
1074    /// download a single compressed tar file.
1075    #[cfg(not(feature = "lt2025_2"))]
1076    pub fn get_uncompressed(&self) -> bool {
1077        self.uncompressed
1078    }
1079
1080    /// # Description
1081    ///
1082    /// -D
1083    ///
1084    /// Create a new directory and download the requested uncompressed
1085    /// individual files into this new directory. Without this option,
1086    /// download a single compressed tar file.
1087    #[cfg(not(feature = "lt2025_2"))]
1088    pub fn set_uncompressed(&mut self, v: bool) -> &mut Self {
1089        self.uncompressed = v;
1090        self
1091    }
1092
1093    /// # Description
1094    ///
1095    /// -D
1096    ///
1097    /// Create a new directory and download the requested uncompressed
1098    /// individual files into this new directory. Without this option,
1099    /// download a single compressed tar file.
1100    #[cfg(not(feature = "lt2025_2"))]
1101    pub fn uncompressed(mut self, v: bool) -> Self {
1102        self.uncompressed = v;
1103        self
1104    }
1105
1106    /// # Description
1107    ///
1108    /// g-opts
1109    ///
1110    /// See [Global options](GlobalOpts).
1111    pub fn get_global_opts(&self) -> &GlobalOpts {
1112        &self.global_opts
1113    }
1114
1115    /// # Description
1116    ///
1117    /// g-opts
1118    ///
1119    /// See [Global options](GlobalOpts).
1120    pub fn set_global_opts(&mut self, v: GlobalOpts) -> &mut Self {
1121        self.global_opts = v;
1122        self
1123    }
1124
1125    /// # Description
1126    ///
1127    /// g-opts
1128    ///
1129    /// See [Global options](GlobalOpts).
1130    pub fn global_opts(mut self, v: GlobalOpts) -> Self {
1131        self.global_opts = v;
1132        self
1133    }
1134}
1135
1136impl<M: ExclusiveOption> SubCommand for Diagnostics<M> {
1137    fn name(&self) -> &str {
1138        "diagnostics"
1139    }
1140
1141    fn inject_local_args(&self, command: &mut Command) {
1142        #[cfg(not(feature = "lt2025_2"))]
1143        if self.uncompressed {
1144            command.arg("-D");
1145        }
1146
1147        self.mode.inject_args(command);
1148    }
1149
1150    fn global_opts(&self) -> Option<&GlobalOpts> {
1151        Some(&self.global_opts)
1152    }
1153}
1154
1155impl<M: ExclusiveOption> ParameterizedSpawn<()> for Diagnostics<M> {
1156    type Output = Child;
1157    type Error = std::io::Error;
1158
1159    /// Spawns `p4 diagnostics` as a child process with piped standard output
1160    /// and error streams; use the returned [`Child`] handle to wait for it or
1161    /// interact with it.
1162    fn spawn_with(&mut self, (): ()) -> Result<Self::Output, Self::Error> {
1163        self.setup_command(&self.bin)
1164            .stdout(Stdio::piped())
1165            .stderr(Stdio::piped())
1166            .spawn()
1167    }
1168}
1169
1170#[cfg(test)]
1171mod tests {
1172    use super::*;
1173    use crate::cmd::args_of;
1174
1175    fn args(cmd: &impl SubCommand) -> Vec<String> {
1176        args_of(&cmd.setup_command("p4"))
1177    }
1178
1179    #[test]
1180    fn plain_basic_form() {
1181        let cmd = Diagnostics::new("p4", GlobalOpts::new());
1182        assert_eq!(args(&cmd), ["diagnostics"]);
1183        assert_eq!(args(&cmd.basic()), ["diagnostics"]);
1184    }
1185
1186    #[test]
1187    fn journal_with_limit() {
1188        #[cfg(not(feature = "lt2025_2"))]
1189        let cmd = Diagnostics::new("p4", GlobalOpts::new())
1190            .basic()
1191            .journal_with("10m");
1192        #[cfg(feature = "lt2025_2")]
1193        let cmd = Diagnostics::new("p4", GlobalOpts::new()).limit("10m");
1194
1195        assert_eq!(cmd.get_limit(), Some("10m"));
1196
1197        #[cfg(not(feature = "lt2025_2"))]
1198        assert_eq!(args(&cmd), ["diagnostics", "-J", "-L", "10m"]);
1199
1200        #[cfg(feature = "lt2025_2")]
1201        assert_eq!(args(&cmd), ["diagnostics", "-L", "10m"]);
1202    }
1203
1204    #[cfg(not(feature = "lt2025_2"))]
1205    #[test]
1206    fn json_format_with_journal() {
1207        let cmd = Diagnostics::new("p4", GlobalOpts::new())
1208            .json_format()
1209            .journal()
1210            .limit("1g");
1211
1212        assert!(cmd.get_json_format());
1213        assert_eq!(args(&cmd), ["diagnostics", "-j", "-J", "-L", "1g"]);
1214    }
1215
1216    #[cfg(not(feature = "lt2025_2"))]
1217    #[test]
1218    fn uncompressed_after_subcommand() {
1219        let cmd = Diagnostics::new("p4", GlobalOpts::new()).uncompressed(true);
1220        assert_eq!(args(&cmd), ["diagnostics", "-D"]);
1221
1222        let cmd = cmd.journal();
1223        assert_eq!(args(&cmd), ["diagnostics", "-D", "-J"]);
1224    }
1225
1226    #[test]
1227    fn advance_lsof_and_strace() {
1228        let cmd = Diagnostics::new("p4", GlobalOpts::new())
1229            .run_lsof()
1230            .run_strace();
1231
1232        assert!(cmd.get_run_lsof());
1233        assert_eq!(args(&cmd), ["diagnostics", "-l", "-s"]);
1234    }
1235
1236    #[test]
1237    fn advance_with_basic_journal_limit() {
1238        #[cfg(not(feature = "lt2025_2"))]
1239        let cmd = Diagnostics::new("p4", GlobalOpts::new())
1240            .advance_with_basic()
1241            .journal()
1242            .limit("10m");
1243        #[cfg(feature = "lt2025_2")]
1244        let cmd = Diagnostics::new("p4", GlobalOpts::new())
1245            .advance_with_basic()
1246            .limit("10m");
1247
1248        assert_eq!(cmd.get_limit(), Some("10m"));
1249
1250        #[cfg(not(feature = "lt2025_2"))]
1251        assert_eq!(args(&cmd), ["diagnostics", "-a", "-J", "-L", "10m"]);
1252
1253        #[cfg(feature = "lt2025_2")]
1254        assert_eq!(args(&cmd), ["diagnostics", "-a", "-L", "10m"]);
1255    }
1256
1257    #[test]
1258    fn with_basic_after_strace() {
1259        let cmd = Diagnostics::new("p4", GlobalOpts::new())
1260            .run_strace()
1261            .with_basic();
1262
1263        assert_eq!(args(&cmd), ["diagnostics", "-s", "-a"]);
1264    }
1265
1266    #[cfg(not(feature = "lt2025_2"))]
1267    #[test]
1268    fn strace_runtime() {
1269        let cmd = Diagnostics::new("p4", GlobalOpts::new()).run_strace_with(30);
1270
1271        assert_eq!(cmd.get_strace_runtime(), Some(30));
1272        assert_eq!(args(&cmd), ["diagnostics", "-s", "--strace-runtime", "30"]);
1273    }
1274
1275    #[cfg(not(feature = "lt2025_2"))]
1276    #[test]
1277    fn all_advance_options_in_syntax_order() {
1278        let cmd = Diagnostics::new("p4", GlobalOpts::new())
1279            .uncompressed(true)
1280            .run_lsof()
1281            .run_ps(true)
1282            .run_top(true)
1283            .run_strace_with(15);
1284
1285        assert_eq!(
1286            args(&cmd),
1287            [
1288                "diagnostics",
1289                "-D",
1290                "-l",
1291                "-s",
1292                "--strace-runtime",
1293                "15",
1294                "-p",
1295                "-t"
1296            ]
1297        );
1298    }
1299
1300    #[test]
1301    fn global_opts_are_injected_once() {
1302        let cmd = Diagnostics::new(
1303            "p4",
1304            GlobalOpts::new().port("localhost:1666").quiet_mode(true),
1305        )
1306        .run_lsof();
1307
1308        assert_eq!(
1309            args(&cmd),
1310            ["-p", "localhost:1666", "-q", "diagnostics", "-l"]
1311        );
1312    }
1313}