{"id":29143382,"url":"https://github.com/rackerlabs/recap","last_synced_at":"2025-06-30T20:04:49.001Z","repository":{"id":49413105,"uuid":"6358863","full_name":"rackerlabs/recap","owner":"rackerlabs","description":"A system status reporting tool","archived":false,"fork":false,"pushed_at":"2024-02-27T22:52:18.000Z","size":453,"stargazers_count":90,"open_issues_count":18,"forks_count":57,"subscribers_count":128,"default_branch":"master","last_synced_at":"2025-04-13T00:29:16.292Z","etag":null,"topics":["bash","linux","logs","recap"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rackerlabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2012-10-23T19:50:59.000Z","updated_at":"2025-03-14T10:49:31.000Z","dependencies_parsed_at":"2025-04-13T00:29:19.191Z","dependency_job_id":"d80bf2b3-8d18-4416-a7df-449b9551c0b2","html_url":"https://github.com/rackerlabs/recap","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/rackerlabs/recap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rackerlabs%2Frecap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rackerlabs%2Frecap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rackerlabs%2Frecap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rackerlabs%2Frecap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rackerlabs","download_url":"https://codeload.github.com/rackerlabs/recap/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rackerlabs%2Frecap/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262842917,"owners_count":23373165,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","linux","logs","recap"],"created_at":"2025-06-30T20:04:46.545Z","updated_at":"2025-06-30T20:04:48.107Z","avatar_url":"https://github.com/rackerlabs.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Recap\n\n[![Build Master Status](https://img.shields.io/travis/rackerlabs/recap/master.svg?logo=travis\u0026label=master)](https://travis-ci.org/rackerlabs/recap)\n[![Build Development Status](https://img.shields.io/travis/rackerlabs/recap/development.svg?logo=travis\u0026label=development)](https://travis-ci.org/rackerlabs/recap)\n[![GitHub release](https://img.shields.io/github/release/rackerlabs/recap.svg)](https://github.com/rackerlabs/recap/releases/latest)\n[![GitHub license](https://img.shields.io/github/license/rackerlabs/recap.svg)](https://raw.githubusercontent.com/rackerlabs/recap/master/COPYING)\n[![GitHub stars](https://img.shields.io/github/stars/rackerlabs/recap.svg?style=social\u0026label=Star)](https://github.com/rackerlabs/recap)\n[![Twitter](https://img.shields.io/twitter/url/https/github.com/rackerlabs/recap.svg?style=social)](https://twitter.com/intent/tweet?text=Check%20this%20out:\u0026url=https%3A%2F%2Fgithub.com%2Frackerlabs%2Frecap)\n\n**recap** is a system status reporting tool. A reporting script that generates reports of various information about the server.\n\n## Contribution\n\nContribution guidelines can be found in [CONTRIBUTING.md](https://github.com/rackerlabs/recap/blob/master/CONTRIBUTING.md)\n\n## Dependencies\n- bash \u003e= 4\n- coreutils\n- gawk\n- grep\n- iotop\n- iproute/iproute2\n- elinks\n- procps\n- psmisc\n- sysstat \u003e= 9\n\n## Versioning\n\n`recap` is following the `x.y.z` versioning as defined below:\n\n - **x** *(major)* - Changes that prevent at least some rolling upgrades.\n - **y** *(minor)* - Changes that don't break any rolling upgrades but require closer user attention for example configuration defaults, function behavior, tools used to produce reports, among others.\n - **z** *(patch)* - Changes that are backward-compatible including features and/or bug fixes.\n\n## Installation\n\nIt is highly recommended to make use of a package to install `recap` is the easiest way to keep it updated whenever there is a new release.\n\n### Fedora\n\n`recap` is available from the main Fedora repository ([spec file](https://src.fedoraproject.org/rpms/recap/blob/master/f/recap.spec)).\n\n```\ndnf install recap\n```\n\n### RHEL/CentOS\n\n`recap` is available from the [EPEL](https://fedoraproject.org/wiki/EPEL) repository ([spec file](https://src.fedoraproject.org/rpms/recap/blob/master/f/recap.spec)).\n\n```\nyum install recap\n```\n\n### Debian\n\nCurrently only available in [testing](https://packages.debian.org/source/testing/recap) and [unstable](https://packages.debian.org/source/unstable/recap). For other releases see the options to build a deb package or install from source.\n\nThe official Debian files are available in this [repository](https://github.com/jkirk/recap)\n\n### Ubuntu\n\nAt the moment there is no public repository for Ubuntu, two options are available, build a deb package or install manually, see instructions down below.\n\n### Build a deb package\n\nThis [repository](https://github.com/jkirk/recap)  contains the official Debian files required to build a deb package.\n\nThese steps used to be used to build the deb package, use them as a guide:\n\n```bash\n# Install all the packages required for building the package\napt-get update\napt-get install debhelper devscripts git -y\n\n## For Ubuntu:\napt-get install equivs -y\n\n# Create the working dir:\nmkdir recap\ncd recap\n\n# Get the Debian configs\ngit init\ngit remote add origin https://github.com/jkirk/recap.git\ngit fetch --no-tags origin\ngit checkout -qf FETCH_HEAD\ngit submodule update --init --recursive\nexport LATEST=$( git log --format=\"%h\" --no-merges -1 )\n\n# Build dependencies\necho \"yes\" | mk-build-deps --install --remove debian/control\n\n# Get upstream recap code\ngit checkout --orphan upstream\ngit reset --hard\ngit remote add upstream https://github.com/rackerlabs/recap.git\ngit fetch -t upstream\nlatest_tag=$( git tag | tail -1 )\ngit archive ${latest_tag} -o ../recap_${latest_tag}.orig.tar.gz\ntar -zxf ../recap_${latest_tag}.orig.tar.gz\ngit fetch --no-tags origin\ngit checkout ${LATEST} -- debian\n\n# Build the package\ndebuild -us -uc --lintian-opts --profile debian\n\n# Package will be created in ../recap_${latest_tag}-\u003cRELEASE\u003e_all.deb\n# RELEASE comes from the changelog in the Debian repository.\n```\n\n### Manual\n\n1. Install the required dependencies.\n2. Clone this repository: `git clone https://github.com/rackerlabs/recap.git`\n3. Change into the new directory: `cd recap`\n4. Install the program: `sudo make install`\n\nThe information captured will be found in log files in the `/var/log/recap/` directory.\n\n#### About the locations of the scripts\n\n- The default location of the install is `\"/\"` it can be overridden with `DESTDIR`.\n- The scripts, man pages and docs are installed under \"`\"/usr/local\"` by default, this can be overridden with `PREFIX`. Main scripts are installed on in \"`./sbin`\" by default, this can be overriden with `BINDIR`.\n- The core scripts and the plugins are installed on top of `PREFIX` in \"`./recap/plugins-available`\" by default, this can be overridden with `LIBDIR`\n\nThe following example is a common location for most of the distributions, this will install `recap` under `/usr`:\n\n  ```\n$ sudo make PREFIX=\"/usr\" install\n```\n\nThis other example will install `recap` under your homedirectory but using the default locations for the script, i.e. under `\"~/usr/local\"`:\n\n  ```\n$ make DESTDIR=\"~\" install\n```\n\nThe `Makefile` scripts attempts to detect systemd if so, the `install` option will install the systemd unit files. The install will **not** enable the timers, but it will show the commands required to enable each of the timers.  When systemd is not detected the cronjobs will be installed.\n\nIs up to each package distribution to follow their own best practices regarding enabling/disabling the timers on install/remove of the package.\n\n### Ansible\n\nAn ansible playbook could be used to install `recap` from a git repository. The playbook is located in `tools` under `ansible_recap.yml` the playbook can be used to install it on Red Hat based and Debian based distros. Or to uninstall it defining the `uninstall` variable.\n\n#### Variables\n\n- `repo` - The location of the repository, default: `https://github.com/rackerlabs/recap.git`.\n- `ref` - The reference to use this could be a branch, a tag or commit, default: `master`.\n- `binpath` - The value of *BINPATH*, default: `/sbin`.\n- `destdir` - The value of *DESTDIR*, default: `\"\"`.\n- `prefix` - The value of *PREFIX*, default: `/usr`.\n- `tmp_install_dir` - The location where the cloned repo will be placed, default: `/tmp/recap`.\n- `uninstall` - Then this is defined it will remove `recap`, default: *undefined*.\n- `enable_plugins` - To enable the global plugin configuration default: `false`.\n- `plugin_list` - A list of plugins to enable, from the `plugin-available` directory, default: `all`.\n\n#### Install (default)\n\nInstall the stable version of `recap`:\n\n```\nansible-playbook tools/ansible_recap.yml\n```\n\nInstall the development version of `recap`:\n\n```\nansible-playbook tools/ansible_recap.yml -e ref=development\n```\n\nInstall branch `foo` from a different repository:\n\n```\nansible-playbook tools/ansible_recap.yml -e ref=foo -e repo=https://github.com/bar/recap.git\n```\n\nInstall recap with *BINPATH* in `/bin`:\n\n```\nansible-playbook tools/ansible_recap.yml -e binpath=/bin\n\n```\n\nInstall recap with all plugins enabled:\n\n```\nansible-playbook tools/ansible_recap.yml -e enable_plugins=true\n\n```\n\nInstall recap with a list of plugins to enable:\n\n```\nansible-playbook tools/ansible_recap.yml \\\n  -e enable_plugins=true \\\n  -e '{\"plugin_list\":[docker_top,redis]}'\n\n```\n\n#### Uninstall\n\nUninstall `recap` from the default path:\n\n```\nansible-playbook tools/ansible_recap.yml -e uninstall=yes\n```\n\nUninstall `recap` from a custom location:\n\n```\nansible-playbook tools/ansible_recap.yml -e uninstall=yes -e destdir=/tmp/test\n```\n\n## Cron/Timers and Configuration\n\n### Timers(systemd)\n\nMultiple unit files are available to make use of `timers`, here the default schedules for the recap scripts:\n- recap (default every 10min)\n- recap-onboot (runs at boot time)\n- recaplog (default: Once a day 1am)\n\n#### Enabling timers\n\nEach one of the timers can be enabled with:\n\n  ```bash\n  sudo systemctl enable recap.timer --now\"\n  sudo systemctl enable recaplog.timer --now\"\n  sudo systemctl enable recap-onboot.timer --now\"\n  ```\n\n#### Disabling timers\n\nEach one of the timers can be disabled with:\n\n  ```bash\n  sudo systemctl disable recap.timer --now\"\n  sudo systemctl disable recaplog.timer --now\"\n  sudo systemctl disable recap-onboot.timer --now\"\n  ```\n\n### Cron\n\nThe cron file (`/etc/cron.d/recap`) is used to determine the execution time of `recap` and `recaplog`.  By default the cron execution for `recap` is enabled to run every 10 min. and `recaplog` is expected to run every day at 1 am, but those can be adjusted as needed.\n\n### Configuration\n\nThe following variables are commented out with the defaults values in the configuration file `/etc/recap.conf` which can be overridden.\n\n#### Settings shared by recap scripts\n\n- **BASEDIR** - Directory where the logs are saved.\n\n  Default: `BASEDIR=\"/var/log/recap\"`\n\n- **LIBDIR** - Directory where the libraries/functions are located.\n\n  The default value depends on the `PREFIX` used when installing, the default `PREFIX` on the `Makefile` is `/usr/local`, then:\n\n    Default: `LIBDIR=\"/usr/local/lib/recap\"`\n\n  But packages use `/usr` as the `PREFIX`, then through a package it is expected to be:\n\n    Default: `LIBDIR=\"/usr/lib/recap\"`\n\n\n#### Settings used only by `recaplog`\n\n- **LOG_COMPRESS** - Enable or disable log compression.\n\n  Default: `LOG_COMPRESS=1`\n\n- **LOG_EXPIRY** - Log files will be deleted after LOG_EXPIRY days\n\n  Default: `LOG_EXPIRY=15`\n\n#### Settings used only by `recap`\n\n- **MAILTO** - Send a report to the email defined.\n\n  Default: `MAILTO=\"\"`\n\n- **MIN_FREE_SPACE** - Minimum free space (in MB) required in `${BASEDIR}` to run recap, a value of 0 deactivates this check.\n\n  Default: `MIN_FREE_SPACE=0`\n\n\n#### Reports\n\nThese are the type of reports generated and their dependencies.\n\n##### fdisk\n\n- **USEFDISK** - Generates logs from \"fdisk `${OPTS_FDISK}`\"\n\n  Default: `USEFDISK=\"no\"`\n\n##### mysql\n\n- **USEMYSQL** - Generates logs from \"mysqladmin status\"\n\n  Makes use of `DOTMYDOTCNF`.\n\n  Required by: `USEMYSQLPROCESSLIST`, `USEINNODB`\n\n  Default: `USEMYSQL=\"no\"`\n\n- **USEMYSQLPROCESSLIST** - Generates logs from \"mysqladmin processlist\"\n\n  Makes use of `DOTMYDOTCNF` and `MYSQL_PROCESS_LIST`\n\n  Requires: `USEMYSQL`\n\n  Default: `USEMYSQLPROCESSLIST=\"no\"`\n\n- **USEINNODB** - Generates logs from \"mysql show engine innodb status\"\n\n  Makes use of `DOTMYDOTCNF`\n\n  Requires: `USEMYSQL`\n\n  Default: `USEINNODB=\"no\"`\n\n\n##### netstat\n\n- **USENETSTAT** - Generates network stats from \"ss `${OPTS_NETSTAT}`\"\n\n  Required by: `USENETSTATSUM`\n\n  Default: `USENETSTAT=\"yes\"`\n\n\n- **USENETSTATSUM** - Generates logs from \"nstat `${OPTS_NETSTAT_SUM}`\".\n\n  Requires: `USENETSTAT`\n\n  Default: `USENETSTATSUM=\"no\"`\n\n##### ps\n\n- **USEPS** - Generates logs from \"ps\"\n\n  Options can be modified in `OTPS_PS`\n\n  Default: `USEPS=\"yes\"`\n\n##### pstree\n\n- **USEPSTREE** - Generates logs from pstree\n\n  Options can be modified in `OTPS_PSTREE`\n\n  Default: `USEPSTREE=\"no\"`\n\n##### resources\n\n- **USERESOURCES** - Generates \"resources\"(uptime, free, vmstat, iostat, iotop) log\n\n  Required by: `USEDF`, `USESLAB`, `USESAR`, `USESARQ`, `USESARR`\n\n  Default: `USERESOURCES=\"yes\"`\n\n\n- **USEDF** - Generates logs from df\n\n  Requires: `USERESOURCES`\n\n  Options can be modified in `OPTS_DF`\n\n  Default: `USEDF=\"yes\"`\n\n- **USESLAB** - Generates logs from the slab table.\n\n  Requires: `USERESOURCES`\n\n  Default: `USESLAB=\"no\"`\n\n\n- **USERSAR** - Generates logs from sar.\n\n  Requires: `USERESOURCES`\n\n  Default: `USESAR=\"yes\"`\n\n- **USESARQ** - Generates logs from \"sar -q\" (logs queue length, load data)\n\n  Requires: `USERESOURCES`\n\n  Default: `USESARQ=\"no\"`\n\n- **USESARR** - Generates logs from\"sar -r\" (logs memory data)\n\n  Requires: `USERESOURCES`\n\n  Default: `USESARR=\"no\"`\n\n\n#### Options\n\nOptions used by the tools generating the reports\n\n- **DOTMYDOTCNF** - Defines the path to the mysql client configuration file\n\n  Required by: `USEMYSQL`, `USEMYSQLPROCESSLIST`, `USEINNODB`\n\n  Default: `DOTMYDOTCNF=\"/root/.my.cnf\"`\n\n- **MYSQL_PROCESS_LIST** - Format  to  display MySQL process list, options are \"table\" or \"vertical\".\n\n  Required by: `USEMYSQLPROCESSLIST`\n\n  Default: `MYSQL_PROCESS_LIST=\"table\"`\n\n- **OPTS_DF** - df options\n\n  Required by: `USEDF`\n\n  Default: `OPTS_DF=\"-x nfs\"`\n\n- **OPTS_FDISK** - Option used by USEFDISK.\n\n  Required by: `USEFDISK`\n\n  Default: `OPTS_FDISK=\"-l\"`\n\n- **OPTS_FREE** - free options\n\n  Required by: `USEFREE`\n\n  Default: `OPTS_FREE=\"\"`\n\n- **OPTS_IOSTAT** - iostat options\n\n  Required by: `USERESOURCES`\n\n  Default: `OPTS_IOSTAT=\"-t -x 1 3\"`\n\n- **OPTS_IOTOP** - iotop options\n\n  Required by: `USERESOURCES`\n\n  Default: `OPTS_IOTOP=\"-b -o -t -n 3\"`\n\n- **OPTS_NETSTAT** - ss options\n\n  Required by: `USENETSTAT`\n\n  Default: `OPTS_NETSTAT=\"-atunp\"`\n\n- **OPTS_NETSTAT_SUM** - nstat options\n\n  Required by: `USENETSTATSUM`\n\n  Default: `OPTS_NETSTAT_SUM=\"-a\"`\n\n- **OPTS_PS** - ps options\n\n  Required by: `USEPS`\n\n  Default: `OPTS_PS=\"auxfww\"`\n\n- **OPTS_PSTREE** - pstree options\n\n  Required by: `USEPSTREE`\n\n  Default: `OPTS_PSTREE=\"-p\"`\n\n\n- **OPTS_VMSTAT** - vmstat options\n\n  Required by: `USERESOURCES`\n\n  Default: `OPTS_VMSTAT=\"-S M 1 3\"`\n\n## Plugins\n\n- **USEPLUGINS** - Enable/Disable plugins usage.\n\n  Default: `USEPLUGINS=no`\n\nPlugins are stored in the plugin directory, defined by **LIBDIR**/plugins-available\n\n  Default: /usr/lib/local/recap/plugin-available\n\n### Enabling plugins\n\nTo enable plugins, the following is required to:\n\n  - Setting `USEPLUGINS=\"yes\"` in `/etc/recap.conf`\n  - Symlinking `plugins-enabled/plugin_name` to `plugins-available/plugin_name`\n\n### Naming conventions:\n\n- Plugin scripts can be named in any way. It's desired that they describe the purpose of the plugin in one word. When multiple words are required use underscores (`_`). Don't use extensions or dates (e.g. `YYYYMMDD`) in the plugin name. Some examples:\n\n  - **Good** names for plugins\n    - redis\n    - memcache\n    - docker_images\n    - memcache_13\n  - **Bad** names for plugins\n    - johndoe_apache   (not very descriptive)\n    - myplugin         (non explicit)\n    - test.sh          (non explicit, using extension)\n    - recap-plugin     (non explicit, using hyphens)\n    - Sendmail         (CamelCase)\t\t\n    - redis.bak        (extension)\n    - ms sql           (space between words)\n    - reports_20202020 (use of a date)\n\n- Allowed naming convention for plugin **OPTIONS** in /etc/recap.conf: **PLUGIN_OPTS_\u003cPLUGIN\u003e_\u003cOPT_NAME\u003e**\n  Some examples:\n\n  - **Good** plugin option names:\n    - **PLUGIN_OPTS_MEMCACHE_PROTO**\n    - **PLUGIN_OPTS_AWS_KEY**\n    - **PLUGIN_OPTS_REDIS_PORT**\n    - **PLUGIN_OPTS_DOCKER_HUB_URL**\n  - **Bad** plugin option names:\n    - plugin_opts_my_plugin   (lower case)\n    - PLUGIN_OPTS_MY_VARIABLE (lacking plugin reference)\n    - PLUGIN_OPTS_DOCKER_port (CamelCase)\n    - PLUGIN-OPTS-NTP         (using hyphens instead of underscores, missing the option)\n\n- Inside the plugin file/script it is expected **only** functions. recap will **only** call **one** function: `print_\u003cplugin_name\u003e` where `plugin_name` must match the name of the file.\n\n- Optionally, other functions can be defined to create different entries in the\n  log. Those other functions could be controlled by plugin variables (**PLUGIN_OPTS_\u003cPLUGIN\u003e_\u003cOPT_NAME\u003e**). Those variables are set in `/etc/recap.conf` and conditionally called from the main plugin function `plugin_name`\n\n- Any plugin variable defined **must** have a default value.\n\n- The plugins are expected to follow some of the practices followed in `recap`. Please refer to [CONTRIBUTING.md](https://github.com/rackerlabs/recap/blob/master/CONTRIBUTING.md)\n\n- A template of a plugin is provided in `doc/plugin_template`\n\n## Changelog \u0026 Contributions\n\nInformation about changes and contributors is documented in the [CHANGELOG.md](https://github.com/rackerlabs/recap/blob/master/CHANGELOG.md)\n\n## License\n\n*recap* is licensed under the [GNU General Public License v2.0](https://raw.githubusercontent.com/rackerlabs/recap/master/COPYING)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frackerlabs%2Frecap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frackerlabs%2Frecap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frackerlabs%2Frecap/lists"}