guprecords - Global uptime records

guprecords is a Raku-based command-line program that generates uptime reports for hosts based on the input record files from uptimed. It allows you to create reports for different categories and metrics, and supports multiple output formats.

Features

• Supports multiple categories: Host, Kernel, KernelMajor, and KernelName
• Supports multiple metrics: Boots, Uptime, Score, Downtime, and Lifespan
• Output formats available: Plaintext, Markdown, and Gemtext
• Provides top entries based on the specified limit

Whereas:

• Boots: Total count of system boots.
• Uptime: Total hosts uptimes.
• Score: A meta score, calculated combining all other metrics.
• Downtime: Total hosts downtimes.
• Lifespan: Downtimes plus uptimes.

Usage

The program can be invoked with various command-line options to customize the generated reports. The following are the command-line options available:

• --stats-dir: The path to the directory containing the uptimed raw record input files (required)
• --category: The category to generate the report for, one of Host, Kernel, KernelMajor, KernelName (default: Host)
• --metric: The metric to use for the report, one of Boots, Uptime, Score, Downtime, Lifespan (default: Uptime)
• --limit: Limit the output to the specified number of entries (default: 20)
• --output-format: The output format for the report, one of Plaintext, Markdown, Gemtext (default: Plaintext)
• --all: Generate all possible reports except Kernel (optional)
• --include-kernel: Include the Kernel category when generating all reports (optional)

Example Usage

./guprecords.raku --stats-dir="./records" --category=Host --metric=Uptime --limit=10 --output-format=Markdown

This command generates a Markdown-formatted report for the top 10 hosts with the highest uptime.

Classes

• Epoch: A class representing the epoch value.
• Aggregate: A class representing the aggregate data for a specific category.
• HostAggregate: A subclass of Aggregate for handling host-related data.
• Aggregator: A class responsible for aggregating data from the record files.
• OutputHelper: A role providing helper methods for report output formatting.
• Reporter: A class generating reports based on specified category, metric, limit, and output format.
• HostReporter: A subclass of Reporter for handling host-related data.

Test

The program includes test functionality. To run the tests, invoke the program with the test argument:

./guprecords.raku test

This will run the tests and report the results.

End-to-end usage

Use uptimed to produce uptime statistics

First, you need to generate uptime statistics from all hosts by installing and running uptimed. There's a package available for most common Linux and *BSD distributions nowadays. It's also available for macOS (Darwin) via Homebrew. For example, under Fedora, run sudo dnf install uptimed. https://github.com/rpodgorny/uptimed

Collect all uptime records to a central location

Second, you must collect the records files produced by uptimed. Which are the raw uptime statistic files continuously updated by uptimed. Depending on the operating system used, the location of the records file can vary. It is advisable to store all the record files in a central git repository.

An example records file looks like this:

11175544:1658053426:OpenBSD 7.1
10033984:1669229566:OpenBSD 7.2
7701011:1642849465:OpenBSD 7.0
3900089:1650550947:OpenBSD 7.1
3573912:1654452258:OpenBSD 7.1
2132201:1640713822:OpenBSD 7.0
88762:1640625045:OpenBSD 7.0
18452:1640603646:OpenBSD 7.0
3408:1642846040:OpenBSD 7.0
2315:1640622113:OpenBSD 7.0
1190:1654451052:OpenBSD 7.1
334:1650550601:OpenBSD 7.1
310:1669229245:OpenBSD 7.2
310:1640624443:OpenBSD 7.0
261:1640624769:OpenBSD 7.0
144:1669229090:OpenBSD 7.2

... whereas the first number is the total uptime since boot, and the second is the boot time. The last column identifies the operating system and kernel version.

guprecords does not provide any out-of-the-box solution for the collection part. I use a quick-and-dirty Makefile in a uptimes.git repository, where I can run make push to manually collect and push the uptime statistics of the current host to the git repository. I log in to all my machines anyway, sooner or later, and I also automatically run a shell script (via my login RC file) to re-collect the stats when they weren't collected for a week or so. So this solution is "just good enough" for me for now:

manual:
    records_path=/var/spool/uptimed/records; \
    test -f /usr/local/var/uptimed/records && records_path=/usr/local/var/uptimed/records; \
    test -f /var/db/uptimed/records && records_path=/var/db/uptimed/records; \
    cp $$records_path ./stats/$$(hostname | cut -d. -f1).records
    uprecords -a -m 100 > ./stats/$$(hostname | cut -d. -f1).txt
    uprecords -a | grep '^->' > ./stats/$$(hostname | cut -d. -f1).cur.txt
    git add ./stats/*
    git commit -a -m 'new uptime
push: manual
    git add ./stats/$(hostname)*
    git commit -a -m 'new stats'
    git pull origin master
    git push origin master

Generate global uptime stats

Third, now you can finally run:

raku guprecords.raku --stats=dir=$HOME/git/uprecords/stats --all

... to generate something like the following:

Top 20 Boots's by Host

Boots is the total number of host boots over the entire lifespan.

+-----+-----------------+-------+
| Pos |            Host | Boots |
+-----+-----------------+-------+
|  1. |   alphacentauri |   671 |
|  2. |            mars |   207 |
|  3. |        callisto |   153 |
|  4. |          uranus |   150 |
|  5. |        dionysus |   136 |
|  6. |       tauceti-e |   120 |
|  7. |          *earth |   108 |
|  8. |           pluto |    51 |
|  9. | *ultramega15289 |    50 |
| 10. |        makemake |    50 |
| 11. |   ultramega8477 |    40 |
| 12. |          phobos |    40 |
| 13. |             sun |    33 |
| 14. |           *t450 |    25 |
| 15. |         *vulcan |    19 |
| 16. |         tauceti |    16 |
| 17. |       *blowfish |    16 |
| 18. |     sagittarius |    15 |
| 19. |       deltavega |    12 |
| 20. |         twofish |    10 |
+-----+-----------------+-------+

Top 20 Uptime's by Host

Uptime is the total uptime of a host over the entire lifespan.

+-----+-----------------+-----------------------------+
| Pos |            Host |                      Uptime |
+-----+-----------------+-----------------------------+
|  1. |         *vulcan |   4 years, 4 months, 7 days |
|  2. |          uranus | 3 years, 11 months, 21 days |
|  3. |             sun |  3 years, 9 months, 26 days |
|  4. |           uugrn |   3 years, 5 months, 5 days |
|  5. |       deltavega |  3 years, 1 months, 21 days |
|  6. |           pluto | 2 years, 10 months, 29 days |
|  7. |         tauceti |  2 years, 3 months, 19 days |
|  8. |       tauceti-f |  1 years, 9 months, 18 days |
|  9. | *ultramega15289 |  1 years, 7 months, 29 days |
| 10. |          *earth |  1 years, 4 months, 24 days |
| 11. |   ultramega8477 |  1 years, 3 months, 25 days |
| 12. |       *blowfish |  1 years, 3 months, 24 days |
| 13. |           host0 |   1 years, 3 months, 9 days |
| 14. |       tauceti-e |  1 years, 2 months, 20 days |
| 15. |        makemake |   1 years, 1 months, 6 days |
| 16. |        callisto | 0 years, 10 months, 31 days |
| 17. |   alphacentauri | 0 years, 10 months, 28 days |
| 18. |          london |  0 years, 9 months, 16 days |
| 19. |         twofish |  0 years, 8 months, 31 days |
| 20. |        fishbone |  0 years, 8 months, 12 days |
+-----+-----------------+-----------------------------+

Top 20 Score's by Host

Score is calculated by combining all other metrics.

+-----+-----------------+-------+
| Pos |            Host | Score |
+-----+-----------------+-------+
|  1. |          uranus |   360 |
|  2. |   alphacentauri |   294 |
|  3. |        dionysus |   285 |
|  4. |         *vulcan |   273 |
|  5. |             sun |   238 |
|  6. |           uugrn |   211 |
|  7. |       deltavega |   193 |
|  8. |           pluto |   182 |
|  9. |         tauceti |   141 |
| 10. | *ultramega15289 |   122 |
| 11. |       tauceti-e |   111 |
| 12. |       tauceti-f |   108 |
| 13. |        callisto |   108 |
| 14. |          *earth |   105 |
| 15. |        makemake |    96 |
| 16. |            mars |    85 |
| 17. |       *blowfish |    81 |
| 18. |   ultramega8477 |    80 |
| 19. |           host0 |    77 |
| 20. |          sirius |    52 |
+-----+-----------------+-------+

Top 20 Downtime's by Host

Downtime is the total downtime of a host over the entire lifespan.

+-----+-----------------+-----------------------------+
| Pos |            Host |                    Downtime |
+-----+-----------------+-----------------------------+
|  1. |        dionysus |  8 years, 3 months, 16 days |
|  2. |   alphacentauri | 5 years, 11 months, 18 days |
|  3. |          uranus |  3 years, 3 months, 28 days |
|  4. |        callisto |  1 years, 5 months, 15 days |
|  5. |            mars |  1 years, 2 months, 10 days |
|  6. |       tauceti-e |  0 years, 12 months, 9 days |
|  7. |        makemake | 0 years, 11 months, 22 days |
|  8. |          sirius |  0 years, 8 months, 20 days |
|  9. | *ultramega15289 |   0 years, 7 months, 8 days |
| 10. |          deimos |  0 years, 5 months, 15 days |
| 11. |          *earth |  0 years, 5 months, 10 days |
| 12. |           *t450 |  0 years, 2 months, 23 days |
| 13. |         joghurt |   0 years, 2 months, 9 days |
| 14. |           host0 |   0 years, 2 months, 1 days |
| 15. |       fibonacci |  0 years, 1 months, 11 days |
| 16. |           cobol |   0 years, 1 months, 8 days |
| 17. |   ultramega8477 |   0 years, 1 months, 8 days |
| 18. |             sun |   0 years, 1 months, 7 days |
| 19. |          sentax |   0 years, 1 months, 6 days |
| 20. |     sagittarius |   0 years, 1 months, 6 days |
+-----+-----------------+-----------------------------+

Top 20 Lifespan's by Host

Lifespan is the total uptime + the total downtime of a host.

+-----+-----------------+-----------------------------+
| Pos |            Host |                    Lifespan |
+-----+-----------------+-----------------------------+
|  1. |        dionysus |  8 years, 6 months, 17 days |
|  2. |          uranus |  7 years, 2 months, 16 days |
|  3. |   alphacentauri |  6 years, 9 months, 13 days |
|  4. |         *vulcan |   4 years, 4 months, 7 days |
|  5. |             sun |  3 years, 10 months, 2 days |
|  6. |           uugrn |   3 years, 5 months, 5 days |
|  7. |       deltavega |  3 years, 1 months, 21 days |
|  8. |           pluto | 2 years, 10 months, 30 days |
|  9. |         tauceti |  2 years, 3 months, 22 days |
| 10. |        callisto |  2 years, 3 months, 13 days |
| 11. | *ultramega15289 |   2 years, 2 months, 3 days |
| 12. |       tauceti-e |  2 years, 1 months, 29 days |
| 13. |        makemake | 1 years, 11 months, 28 days |
| 14. |       tauceti-f |  1 years, 9 months, 20 days |
| 15. |          *earth |  1 years, 8 months, 31 days |
| 16. |            mars |  1 years, 8 months, 19 days |
| 17. |           host0 |  1 years, 4 months, 10 days |
| 18. |   ultramega8477 |   1 years, 4 months, 1 days |
| 19. |       *blowfish |  1 years, 3 months, 24 days |
| 20. |          sirius |  1 years, 2 months, 24 days |
+-----+-----------------+-----------------------------+

Top 20 Boots's by Kernel

Boots is the total number of host boots over the entire lifespan.

+-----+------------------------------+-------+
| Pos |                       Kernel | Boots |
+-----+------------------------------+-------+
|  1. |          Linux 3.2.0-4-amd64 |   452 |
|  2. |  Linux 4.0.4-303.fc22.x86_64 |   103 |
|  3. |         FreeBSD 10.1-RELEASE |    76 |
|  4. |         FreeBSD 10.0-RELEASE |    52 |
|  5. |     FreeBSD 10.1-RELEASE-p19 |    48 |
|  6. |     FreeBSD 11.1-RELEASE-p10 |    46 |
|  7. |                Darwin 13.4.0 |    40 |
|  8. |     FreeBSD 10.3-RELEASE-p11 |    39 |
|  9. |     FreeBSD 10.3-RELEASE-p20 |    39 |
| 10. |     FreeBSD 10.1-RELEASE-p10 |    38 |
| 11. |      FreeBSD 10.0-RELEASE-p7 |    38 |
| 12. |     FreeBSD 10.1-RELEASE-p35 |    34 |
| 13. |      FreeBSD 13.0-RELEASE-p4 |    29 |
| 14. |      FreeBSD 10.0-RELEASE-p9 |    29 |
| 15. |     FreeBSD 10.3-RELEASE-p24 |    28 |
| 16. |         FreeBSD 13.0-RELEASE |    26 |
| 17. |     *FreeBSD 13.1-RELEASE-p3 |    25 |
| 18. |     FreeBSD 10.1-RELEASE-p31 |    24 |
| 19. |      FreeBSD 11.4-RELEASE-p5 |    23 |
| 20. |     FreeBSD 10.1-RELEASE-p41 |    20 |
+-----+------------------------------+-------+

Top 20 Uptime's by Kernel

Uptime is the total uptime of a host over the entire lifespan.

+-----+------------------------------------+-----------------------------+
| Pos |                             Kernel |                      Uptime |
+-----+------------------------------------+-----------------------------+
|  1. |                Linux 3.2.0-4-amd64 |  6 years, 4 months, 20 days |
|  2. | *Linux 3.10.0-1160.15.2.el7.x86_64 | 1 years, 12 months, 15 days |
|  3. |                Linux 3.2.0-3-amd64 |  1 years, 9 months, 18 days |
|  4. |   Linux 3.10.0-957.21.3.el7.x86_64 |  1 years, 7 months, 13 days |
|  5. |           FreeBSD 10.1-RELEASE-p16 |  1 years, 5 months, 23 days |
|  6. |                      Darwin 13.4.0 |  1 years, 3 months, 25 days |
|  7. |               Linux 2.6.32-5-amd64 |  1 years, 3 months, 18 days |
|  8. |               FreeBSD 10.2-RELEASE |  1 years, 3 months, 11 days |
|  9. |                        OpenBSD 7.1 |  1 years, 2 months, 28 days |
| 10. |  Linux 3.10.0-1160.11.1.el7.x86_64 | 0 years, 12 months, 21 days |
| 11. |            FreeBSD 11.0-RELEASE-p1 |  0 years, 10 months, 9 days |
| 12. |        Linux 4.0.4-303.fc22.x86_64 |  0 years, 9 months, 17 days |
| 13. |                FreeBSD 6.2-RELEASE |  0 years, 9 months, 14 days |
| 14. |  Linux 3.10.0-1127.13.1.el7.x86_64 |   0 years, 9 months, 9 days |
| 15. |                       *OpenBSD 7.2 |   0 years, 9 months, 3 days |
| 16. |            FreeBSD 11.1-RELEASE-p4 |  0 years, 8 months, 18 days |
| 17. |                        OpenBSD 4.1 |  0 years, 8 months, 12 days |
| 18. |    Linux 3.10.0-957.1.3.el7.x86_64 |  0 years, 8 months, 12 days |
| 19. |                        OpenBSD 7.0 |  0 years, 8 months, 10 days |
| 20. |                      Darwin 18.7.0 |  0 years, 7 months, 30 days |
+-----+------------------------------------+-----------------------------+

Top 20 Score's by Kernel

Score is calculated by combining all other metrics.

+-----+------------------------------------+-------+
| Pos |                             Kernel | Score |
+-----+------------------------------------+-------+
|  1. |                Linux 3.2.0-4-amd64 |   436 |
|  2. | *Linux 3.10.0-1160.15.2.el7.x86_64 |   126 |
|  3. |                Linux 3.2.0-3-amd64 |   108 |
|  4. |   Linux 3.10.0-957.21.3.el7.x86_64 |    96 |
|  5. |           FreeBSD 10.1-RELEASE-p16 |    88 |
|  6. |                      Darwin 13.4.0 |    80 |
|  7. |               Linux 2.6.32-5-amd64 |    77 |
|  8. |               FreeBSD 10.2-RELEASE |    75 |
|  9. |                        OpenBSD 7.1 |    73 |
| 10. |  Linux 3.10.0-1160.11.1.el7.x86_64 |    61 |
| 11. |        Linux 4.0.4-303.fc22.x86_64 |    53 |
| 12. |            FreeBSD 11.0-RELEASE-p1 |    48 |
| 13. |                       *OpenBSD 7.2 |    45 |
| 14. |                FreeBSD 6.2-RELEASE |    44 |
| 15. |  Linux 3.10.0-1127.13.1.el7.x86_64 |    43 |
| 16. |            FreeBSD 11.1-RELEASE-p4 |    39 |
| 17. |                        OpenBSD 7.0 |    39 |
| 18. |                        OpenBSD 4.1 |    39 |
| 19. |    Linux 3.10.0-957.1.3.el7.x86_64 |    38 |
| 20. |                      Darwin 18.7.0 |    37 |
+-----+------------------------------------+-------+

Top 20 Boots's by KernelMajor

Boots is the total number of host boots over the entire lifespan.

+-----+----------------+-------+
| Pos |    KernelMajor | Boots |
+-----+----------------+-------+
|  1. |  FreeBSD 10... |   551 |
|  2. |    *Linux 3... |   550 |
|  3. |     Linux 5... |   249 |
|  4. |     Linux 4... |   164 |
|  5. |  FreeBSD 11... |   153 |
|  6. | *FreeBSD 13... |   123 |
|  7. |   Darwin 13... |    40 |
|  8. |  *OpenBSD 7... |    34 |
|  9. |    *Linux 6... |    29 |
| 10. |   FreeBSD 5... |    25 |
| 11. |     Linux 2... |    22 |
| 12. |  *Darwin 21... |    20 |
| 13. |   Darwin 15... |    15 |
| 14. |   Darwin 18... |    15 |
| 15. |   Darwin 20... |    12 |
| 16. |   FreeBSD 7... |    10 |
| 17. |   FreeBSD 6... |    10 |
| 18. |   OpenBSD 4... |    10 |
| 19. |  *Darwin 22... |     2 |
| 20. |   Darwin 19... |     1 |
+-----+----------------+-------+

Top 20 Uptime's by KernelMajor

Uptime is the total uptime of a host over the entire lifespan.

+-----+----------------+-----------------------------+
| Pos |    KernelMajor |                      Uptime |
+-----+----------------+-----------------------------+
|  1. |    *Linux 3... | 15 years, 9 months, 26 days |
|  2. |  FreeBSD 10... |   5 years, 9 months, 9 days |
|  3. |     Linux 5... |  3 years, 12 months, 2 days |
|  4. |     Linux 4... |   2 years, 8 months, 9 days |
|  5. |  *OpenBSD 7... |   2 years, 6 months, 9 days |
|  6. |  FreeBSD 11... |  2 years, 4 months, 28 days |
|  7. |     Linux 2... | 1 years, 11 months, 21 days |
|  8. |   Darwin 13... |  1 years, 3 months, 25 days |
|  9. |   FreeBSD 6... |   1 years, 3 months, 9 days |
| 10. |  *Darwin 21... |  0 years, 8 months, 20 days |
| 11. |   OpenBSD 4... |  0 years, 8 months, 12 days |
| 12. |   Darwin 18... |  0 years, 7 months, 30 days |
| 13. |   Darwin 15... |  0 years, 6 months, 15 days |
| 14. |   FreeBSD 5... |  0 years, 5 months, 18 days |
| 15. |    *Linux 6... |  0 years, 5 months, 17 days |
| 16. |   Darwin 20... |  0 years, 4 months, 22 days |
| 17. | *FreeBSD 13... |  0 years, 3 months, 29 days |
| 18. |   FreeBSD 7... |   0 years, 2 months, 5 days |
| 19. |  *Darwin 22... |  0 years, 1 months, 14 days |
| 20. |   Darwin 19... |   0 years, 1 months, 9 days |
+-----+----------------+-----------------------------+

Top 20 Score's by KernelMajor

Score is calculated by combining all other metrics.

+-----+----------------+-------+
| Pos |    KernelMajor | Score |
+-----+----------------+-------+
|  1. |    *Linux 3... |  1043 |
|  2. |  FreeBSD 10... |   406 |
|  3. |     Linux 5... |   268 |
|  4. |     Linux 4... |   178 |
|  5. |  *OpenBSD 7... |   159 |
|  6. |  FreeBSD 11... |   159 |
|  7. |     Linux 2... |   121 |
|  8. |   Darwin 13... |    80 |
|  9. |   FreeBSD 6... |    75 |
| 10. |  *Darwin 21... |    44 |
| 11. |   OpenBSD 4... |    39 |
| 12. |   Darwin 18... |    37 |
| 13. |   Darwin 15... |    29 |
| 14. | *FreeBSD 13... |    28 |
| 15. |    *Linux 6... |    28 |
| 16. |   FreeBSD 5... |    25 |
| 17. |   Darwin 20... |    20 |
| 18. |   FreeBSD 7... |     7 |
| 19. |  *Darwin 22... |     5 |
| 20. |   Darwin 19... |     1 |
+-----+----------------+-------+

Top 20 Boots's by KernelName

Boots is the total number of host boots over the entire lifespan.

+-----+------------+-------+
| Pos | KernelName | Boots |
+-----+------------+-------+
|  1. |     *Linux |  1014 |
|  2. |   *FreeBSD |   872 |
|  3. |    *Darwin |   105 |
|  4. |   *OpenBSD |    44 |
+-----+------------+-------+

Top 20 Uptime's by KernelName

Uptime is the total uptime of a host over the entire lifespan.

+-----+------------+-----------------------------+
| Pos | KernelName |                      Uptime |
+-----+------------+-----------------------------+
|  1. |     *Linux | 24 years, 7 months, 10 days |
|  2. |   *FreeBSD | 9 years, 11 months, 29 days |
|  3. |    *Darwin |   3 years, 4 months, 3 days |
|  4. |   *OpenBSD |  3 years, 1 months, 18 days |
+-----+------------+-----------------------------+

Top 20 Score's by KernelName

Score is calculated by combining all other metrics.

+-----+------------+-------+
| Pos | KernelName | Score |
+-----+------------+-------+
|  1. |     *Linux |  1637 |
|  2. |   *FreeBSD |   703 |
|  3. |    *Darwin |   217 |
|  4. |   *OpenBSD |   198 |
+-----+------------+-------+