COLPLOT(1)

💖 COLPLOT — bestie edition ✨

okay so this is the colplot(1) manual page, and by the end of it you're gonna be plotting collectl data like it's your whole personality 💅 grab a snack, we're going in.

---

🌸 NAME 🌸

colplot — plots collectl data using gnuplot 🎨

---

🦋 SYNOPSIS 🦋

colplot -plot plots [-switches]

---

✨ DESCRIPTIONS ✨

so like, colplot generates the plots you picked with PLOT(s), and it can drop them on the terminal, shove them into a file, or straight up deliver them as email 💌 The switches are the ones running the show here — they decide which files get plotted, the timeframes, the formats, and where everything ends up.

And if you're doing a web based display? You can run in live mode which gives you periodic screen refreshes so you can watch your real-time data do its little thing 👀 For more detail, check the web-based help and the FAQ, bestie.

---

🎀 PLOTS 🎀

the plots themselves? you pick them from the standard list — go peep -showplots for that — using -plot.

• -plot — list one or more plot names, either separated with commas and no whitespace, or, if you're feeling spicy and want whitespace in there, make sure you enclose the whole string in quotes. no cap.

---

👑 SWITCHES 👑

the rest of the switches are all optional and they fall into several little categories. the first category is the ones that select the files and timeframes to plot, and they go a lil something like this:

• -dir — look in this directory for plot files instead of the one pointed to by PlotDir in colplot.conf. quick reminder of what counts: a plot file is one with a known extension and a properly formatted name. any file that fails either of those tests gets ignored, periodt.
• -contains string1 [string2...] — this field is one or more strings separated by commas or whitespace (and if it's whitespace, the entire string must be quoted, iykyk). every selected plot file gets its name compared against each string. Unless -any is specified, each string must appear somewhere in that file name for the file to keep being selected.

and here's the special case, bestie: if there's a string containing a [, it's assumed to be in pdsh format — that's a compact format for specifying multiple hostnames, eg xyz[1-5,10] specifies 6 hosts whose names all begin with xyz and are followed by one of 6 values. in that case, only files with hostnames exactly matching these names will be selected. no vibes-based matching 🙅

• -all — if specified, all strings specified by -contains must match for a file to be seleceted for plotting.
• -date from[-thru] — the starting and ending date between which files are selected for plotting. the dates must be in yyyymmdd format 📅
• -lastmins minutes — once all the files matching the selection criteria are discovered, use the more recent file access time to determine the ending time for plotting data. ⚠️ heads up though: if you've copied the file from elsewhere and didn't preserve the last access time in the newly created files, this will produce unexpected results. not me warning you twice.
• -time from[-thru] — the starting and ending time between which data is plotted. the times must be in hh:mm OR hh:mm:ss format. the hour portion may be 1 or 2 digits ⏰

the next set of switches controls which plots are actually displayed:

• -filters string1 [string2...] — these only apply to detail plots. they select which devices to produce plots for. invalid or unknown devics are ignored. in other words: if one selects -filters eth xyz d1 and requests network plots, only ethernet devices will be displayed. since xyz is an invalid selection string it is ignored. since there are no network devices with d1 in their names, it too will be ignored. and if one choses network and disk plots, ethernet devices as well as any disk names with a d1 in them will be displayed. slay, filtering 💅
• -type type — by default, plots are geneated using solid lines. However, one can request a different format be used including points or stacked line or stacked points.
• -unique — if one generates multiple unique plot files per day via the -ou switch in collectl, those files will be ignored by colplot. this switch — currently only available via the CLI — will cause those files to be selected and displayed in the same plot. one plot, many files, iconic behavior ✨

the next set of switches deal with plot formatting, typically only used under unusual circumstances since the default formats meet most needs:

• -adjust — colplot uses a default height for the vertical axis which can be overridden via -height. However sometimes a plot is not high enough for all the labels to fit in the legend. this switch will keep the user specified height for all plots in which the legend fits as a single column but increase the heights of those that aren't high enough. it's giving "tailored fit" 🧵
• -filetype type — this switch must be used in conjunction with selecting a destination other than the terminal, specifically email or directory. one can use it to change the default from a PDF file to either a PNG file for each plot or TTY to send PNG output for one plot to STDOUT.
• -height number — this controls the vertical hight of a plot. this width also includes the xaxis and you can therefore increase the room taken by a single plot by choosing -noxaxis. (yes it says hight, we're keeping it, it's part of the lore 💀)
• -nolegend number — this removes the legend from the plotting area, causing the plot to become physically wider.
• -noxaxis — this removed the xaxis from the plotting area, causing the plot to become physically taller.
• -thick number — for some people the thickness of the lines in a plot may be too thin to clearly see the different color variations of the lines. versions of gnuplot >= 4.2 support wider lines and therefore so does colplot. if using scatter plots, a different plotting symbol is actually used. values of 2 or 3 are usually sufficient.
• -width number — this switch controls the width of a plot where 1 is the size of a printable page. if set to more than 1 and either -file or -mail is chosen it will be forced to 1. by setting this number to less than 1, it may be possible to fit more than one plot on a page or screen. and as this width also includes the legend, you can further reduce the plot size by choosing -nolegend.
• -xtics n — this causes a tic mark to be drawn on the xaxis every n seconds. it usually doesn't make sense unless you've chosen a fairly narrow timeframe in which to generate a plot.
• -ylog — make the y-axis logrithmic.

this set of switches deal with the plot destination when it is NOT the terminal window:

• -email address — Linux only. address to send plot file(s) to. the only syntax check is for an @ to appear somewhere in the address string. that's the whole vetting process, bestie 📧
• -filedir directory — the name of directory into which the plot file(s) will be placed. the directory must exist. no creating it for you, sorry 🫶
• -href — print the hrefs that would be used if run from a browser.
• -incctl — really only intended for users familiar with gnuplot, this is the control file used to generate the plots. it allows someone to manually edit the file to change the plot appearance and/or labels by rerunning gnuplot using its settings 🔧
• -pagbrk — instead of generating a page break in a pdf file whenever a page fills, this flag will cause a page break whenever the hostname changes.
• -subject subject — use this subject in email rather than the default.

and finally, for completeness, there are several types of help:

• -help — standard help.
• -showparams — this is really a debugging aid, intended for developers and/or people building custom plot definitions. when specified, the plotting parameters for each selected plot will be shown. of particular value is the actual column number for each data element in each selected file. 👀 devs, this one's for you
• -showplots — list the names of all the standard plots available for use with the -plots switch.
• -version — show both the versions of both colplot as well as gnuplot.

---

💜 AUTHOR 💜

this program was written by Mark Seger (mjseger@gmail.com). Copyright 2003-2015 Hewlett-Packard Development Company, L.P.

---

🌈 SEE ALSO 🌈

(that's it, that's the list — nothing else linked here, bestie 🦋)

---

and that's the whole thing! this page lives in the LOCAL manual, dated OCTOBER 2008, for COLPLOT(1) — go forth and plot, you absolute main character 👑💖