{"id":16886846,"url":"https://github.com/jlevy/procdog","last_synced_at":"2025-09-21T06:32:37.980Z","repository":{"id":28708192,"uuid":"32228761","full_name":"jlevy/procdog","owner":"jlevy","description":"Lightweight command-line process control","archived":false,"fork":false,"pushed_at":"2018-09-14T10:06:41.000Z","size":292,"stargazers_count":78,"open_issues_count":3,"forks_count":7,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-08-24T11:50:06.120Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jlevy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-03-14T19:40:30.000Z","updated_at":"2025-07-24T09:26:17.000Z","dependencies_parsed_at":"2022-07-24T16:02:05.819Z","dependency_job_id":null,"html_url":"https://github.com/jlevy/procdog","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/jlevy/procdog","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlevy%2Fprocdog","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlevy%2Fprocdog/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlevy%2Fprocdog/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlevy%2Fprocdog/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jlevy","download_url":"https://codeload.github.com/jlevy/procdog/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlevy%2Fprocdog/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276204814,"owners_count":25602738,"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","status":"online","status_checked_at":"2025-09-21T02:00:07.055Z","response_time":72,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2024-10-13T16:41:40.557Z","updated_at":"2025-09-21T06:32:37.728Z","avatar_url":"https://github.com/jlevy.png","language":"Python","readme":"# procdog\n\n## Lightweight command-line process control\n\nProcdog (as in \"**proc**ess watch**dog**\"... get it?)\nis a simple command-line tool to start, stop, and check the health of\nprocesses. It works with any kind of process you can invoke from the command\nline (be it native, Java, Node, Python, or anything) on MacOS or Linux.\n\nWhy would you want another tool for this?\n\n- For basic interactive situations, you can just run a process in a terminal\n  or use job management in your shell (`jobs`, `kill`, etc.).\n- But you rapidly realize this won't work well once you have longer-lived processes\n  or are `ssh`ing to remote servers. Then you could use `nohup` and manually\n  checking with `ps`, or using [screen](http://en.wikipedia.org/wiki/GNU_Screen).\n  But these don't script easily.\n- You also might want to script starting and stopping.\n  With a little effort you might write a custom Bash script (writing a PID file,\n  using `pgrep` and `pkill`, etc.), but it's a hassle and gets messy quickly.\n- Of course, you can just \"do it right.\" Traditionally, in the Unix world, the way to\n  control services are\n  [System V service scripts](http://manpages.ubuntu.com/manpages/trusty/man8/service.8.html),\n  [start-stop-daemon](http://manpages.ubuntu.com/manpages/karmic/man8/start-stop-daemon.8.html),\n  [Upstart](http://upstart.ubuntu.com/), or\n  [systemd](http://www.freedesktop.org/wiki/Software/systemd/).\n  Using these is essential for production deployment, but they tend to be a bit arcane\n  and highly OS-dependent, so aren't as convenient for casual use, and you can't easily\n  develop and test on both MacOS and Linux (as many of us try to do).\n\nProcdog is an alternative for developers that attempts to be easy to install,\nsimple and obvious to use, and cross-platform. Processes are independent of the\nshell used to invoke them (i.e., detatched as with `nohup`) and you can also check\nstatus or kill them at any time (as with a Unix service).\n\nProbably the most simlar tool to Procdog is [Supervisor](https://github.com/Supervisor/supervisor).\nAlthough it has similar goals, Supervisor is a more complex, production-oriented tool with a\nlong-lived, centrailized XML-RPC server that monitors processes. Procdog is intended\nto be a single, simple, easy-to-use command that needn't be set up and managed itself\nor run as root. Each use of Procdog is independent and monitors just one process. It\ndoes not require a configuration file unless you want to save typing. You can even\ncheck the Procdog script into your own project so developers can immediately use it\nlocally, since it has no dependencies (besides Python 2.7).\n\nYou'll find it useful if you have servers, databases, or other processes you want\nto manage on your personal machine when developing, in build systems and test\nharnesses, test deployments, etc. Currently, it *doesn't* have restart\nlogic, log file rotation, or some other features you may want for a production\nenvironments; for this consider Supervisor, Upstart, systemd, \u0026 co. Procdog is\nalso *way* less mature than these alternatives.\n\n## Installation\n\nNo dependencies except Python 2.7+. It's easiest to install with pip:\n\n    sudo pip install procdog\n\nOr, since it's just one file, you can copy the single\n[`procdog`](https://github.com/jlevy/procdog/blob/master/procdog)\nscript somewhere (perhaps within your own project) and make it executable.\n\n## Quick start\n\nNow you can start and monitor any process (here let's pick \"sleep\" -- not all that\nuseful, but you already have it):\n\n```\n$ procdog start myprocess --command \"sleep 100\"\nrunning, pid=14969\n$ procdog status myprocess\nrunning, pid=14969\n$ procdog stop myprocess\nstopped\n$\n```\n\nNote you have to give your process an arbitrary name (`myprocess` here), like a Unix\nservice name, so you can refer to it. Once the process is done, the monitor daemon\nalso exits.\n\n## Usage\n\nRun `procdog -h` for help on all options.\n\n## A better example\n\nNow, with a real server we'd like to know if it's actually up and doing something,\nlike listening on a port. Procdog supports an arbitrary command to test health\n(e.g. running `curl` to see if it returns a result) and can wait until a server\nis running and tell you.\n\n```\n$ procdog start backend --command=\"java -classpath my-backend.jar com.example.BackendServer server config.yml\" \\\n  --health-command=\"curl http://localhost:8080/ping\" \\\n  --health-count=10 --health-delay=2 \\\n  --dir=$HOME/backend \\\n  --stdout=backend.log --stderr=backend.log --append \\\n  --ensure-healthy --strict\nrunning, health=0, pid=15240\n$ procdog status backend\nrunning, health=0, pid=15240\n$ procdog stop backend --strict\nstopped\n$ procdog stop backend --strict\nprocdog: error: process 'backend' is not running\n$\n```\n\nSome notes on this:\n\n- We can specify where to write stdout and stderr. They can be the same or different.\n  Existing log files are appended to if you use `--append`.\n- The health command simply calls a shell command to see if the server is healthy.\n  The return code of the health check command must be `0` for the server to be considered\n  healthy. In this case, we're callin `curl` on a known health-check URL, which will have\n  return code 0 on an HTTP 200\n- The `--ensure-healthy` option means the command will block until the process is healthy,\n  or until the daemon gives up and kills the process (if necessary). In this example,\n  it will try 10 times, sleeping 2 seconds each time, before giving up.\n- The `--dir` option means process will run from that directory.\n- We ask the client to be `--strict`, so that it returns non-zero status code when we try to\n  start a process that's already running or or stop one that is already stopped.\n\n## Configuration files\n\nIt's possible to avoid typing by putting most options in a configuration file:\n\n```\n# Procdog config file. Each section is a process name.\n[backend]\ncommand=java -classpath my-backend.jar com.example.BackendServer server config.yml\nhealth_command=curl http://localhost:8080/ping\nhealth_count=10\nhealth_delay=2.\ndir=$HOME/backend\nstdout=backend.log\nstderr=backend.log\nappend=False\nensure_healthy=True\nstrict=True\n```\n\nYou have any number of sections, one section per process. Procdog reads options\nfrom `~/.procdog.cfg` or `procdog.cfg` (in the same directory the `procdog`\nscript resides). Any options given on the command line override those in the\nconfiguration file. Note that environment variables (like `$HOME`) are\nallowed and expanded. Once you have the above section in your config file,\nyou can run:\n\n```\n$ procdog start backend\nrunning, health=0, pid=15396\n$ procdog stop backend\nstopped\n$\n```\n\n## How it works\n\nProcdog starts a small daemon that `popen()`s and monitors the process.\nThe daemon listens and accepts commands on a local\n[Unix domain socket](http://en.wikipedia.org/wiki/Unix_domain_socket),\nmaking it possible to check the process is running or terminate it, and to do simple\nhealth checks. You can see these sockets at `/var/tmp/procdog.*.sock` (where the * is the\nid of the process). For simplicity, there is a single Procdog daemon for each monitored\nprocess, so each process is handled compeltely separately.\n\nWe use Unix domain sockets so that we don't have the headaches of pid files or\nchoosing and binding to TCP ports. They're also available on most platforms.\n\nDaemon logs are sent to `/var/tmp/procdog.*.log`. Usually you'll want to redirect your\nprocess stdout and stderr using the `--stdout` and `--stderr` options.\n\nProcdog is quite new so probably not stable. Bug reports and contributions are welcome!\n\n## Tests\n\nAll basic features are covered with a simple Bash-based regression test.\n\nTo run it, clone this repo, invoke `tests/run.sh` then follow the directions to diff\nthe output using `git`.\n\n## License\n\n[Apache 2](https://github.com/jlevy/procdog/blob/master/LICENSE).\n","funding_links":[],"categories":["System Utilities"],"sub_categories":["Directory Navigation"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjlevy%2Fprocdog","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjlevy%2Fprocdog","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjlevy%2Fprocdog/lists"}