{"id":19874421,"url":"https://github.com/strongloop/strong-supervisor","last_synced_at":"2025-05-02T10:31:08.464Z","repository":{"id":12752864,"uuid":"15426083","full_name":"strongloop/strong-supervisor","owner":"strongloop","description":"Application supervisor that automatically adds cluster control and performance monitoring with StrongOps","archived":false,"fork":false,"pushed_at":"2022-07-22T15:38:50.000Z","size":891,"stargazers_count":66,"open_issues_count":7,"forks_count":20,"subscribers_count":45,"default_branch":"master","last_synced_at":"2025-04-20T22:03:07.584Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/strongloop.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-12-24T22:28:42.000Z","updated_at":"2023-11-03T17:10:46.000Z","dependencies_parsed_at":"2022-09-10T17:00:54.137Z","dependency_job_id":null,"html_url":"https://github.com/strongloop/strong-supervisor","commit_stats":null,"previous_names":[],"tags_count":57,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strongloop%2Fstrong-supervisor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strongloop%2Fstrong-supervisor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strongloop%2Fstrong-supervisor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strongloop%2Fstrong-supervisor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/strongloop","download_url":"https://codeload.github.com/strongloop/strong-supervisor/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252023229,"owners_count":21682146,"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":[],"created_at":"2024-11-12T16:23:18.043Z","updated_at":"2025-05-02T10:31:08.204Z","avatar_url":"https://github.com/strongloop.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# strong-supervisor\n\nSupervise a node application package, seperating deployment concerns (logging,\nmonitoring, run-time control) from the application source.\n\n*NOTE:* strong-supervisor@5 has dropped support for some legacy features that\nare no longer relevant to its main use-cases.\n\n- running detached: this mode existed to provide a kindof light weight daemon,\n  but didn't include the generation of the init.d/systemd/upstart scripts required\n  for production usage, and those system startup tools already take care of\n  daemonization, so the feature is being removed. Use\n  start-stop-daemon or https://www.npmjs.com/package/strong-service-install with\n  the strong-supervisor.\n- running unclustered: this mode disabled most features of strong-supervisor\n  but still started the agent, originally intended to report to the StrongOps\n  service even when running apps on dev laptops, the service no longer exists,\n  so the feature is no longer supported and needs no replacement.\n\n\n## Installation\n\n`sl-run` and `sl-runctl` can be installed with:\n\n    npm install -g strong-supervisor\n\n\n## Features\n\n### Appmetrics Monitoring\n\nSupervisor and its workers are monitored using\n[appmetrics](https://github.com/RuntimeTools/appmetrics), which is open source\nand free for use under the Apache 2.0 license.\n\n*Note:* applications wanting to use appmetrics programatically must use\nsupervisor's builtin appmetrics, like so:\n\n    var appmetrics = global.APPMETRICS || require('appmetrics');\n\n*Note:* strong-supervisor 4.x and below use strong-agent, which required a\nStrongLoop license. With 5.x we use appmetrics and this restriction is removed.\n\nAppmetrics can be explicitly disabled using the `--no-profile` option.\n\n### Appmetrics Dashboard\n\nThe [appmetrics dashboard](https://github.com/RuntimeTools/appmetrics-dash) can\nbe enabled by setting the `STRONGLOOP_DASHBOARD` environment variable to `'on'`.\n\nSee the dashboard documentation for more information.\n\n### Metrics\n\nMetrics can be published to a thirdparty collector, in addition to\n[Strongloop Arc](https://github.com/strongloop/strong-arc). For information on\nsupported collectors and URL formats, see\n[strong-statsd](https://github.com/strongloop/strong-statsd).\n\n### Profiling control\n\nExpensive profiling (such as object tracking or call tracing) can by dynamically\nstarted and stopped using the CLI (by worker ID or by process ID). The object\ncount and size information is reported as a metric.\n\n### Heap snapshot\n\nA heap snapshot can be generated for the master or any worker from the CLI (by\nworker ID or by process ID). It is written to a file that can be opened in the\nChrome Dev Tools.\n\n### CPU profiling\n\nCPU profiling can be initiated on the master or any workers from the CLI (by\nworker ID or by process ID), and the CPU profile when stopped is written into a\nfile that can be opened in the Chrome Dev Tools.\n\n### Clustering\n\nSupervisor will run the application clustered, by default, maintaining a worker\nper CPU. It does this using\n[strong-cluster-control](https://github.com/strongloop/strong-cluster-control).\n\nClustering can be disabled using the `--cluster=off` option, or the size can be\nexplicitly set to any numeric value (including `0`), or to `--cluster=cpus` to\nrun a worker per CPU.\n\nNote that a number of features are unavailable when clustering is disabled.\n\n### Environment\n\nSupervisor will load environment variable settings from a `.env` file in the\napplications root directory, if it exists (see\n[dotenv](https://www.npmjs.org/package/dotenv) for more information).\n\n### Daemonization\n\n`sl-run can be useful when launching from a shell, but is not recommended for\nproduction use. For production use it is best to run the supervisor from an init\nscript and let the init system handle daemonization.\n\n### Logging\n\nSupervisor collects the stdout and stderr of itself and its workers, and writes\nit to stdout, by default. It is possible to specify a log file with the `--log`\noption.\n\nLogging is most effective in cluster mode as it allows for complete capture of\nthe application's stdout and stderr. If the application is not \"cluster safe\"\nbut logging is still desired we recommend using `--cluster 1` to gain all of the\nlogging and process supervision benefits without the potential problems of\nrunning multiple instances of your application code.\n\n#### Filename Expansions\n\nIt is possible to specify per-process log files by using `%p` (process ID) and\n`%w` (worker ID) expansions in the file name. It is also possible to specify a\ncommand to pipe log messages to by prefixing the log name with a `|`.\n\nFor example, the following will create a cluster and direct each process's logs\nto a separate instance of `logger`:\n\n```sh\nslr --cluster 4 --log '| logger -t \"myApp worker:%w pid:%p\"' myApp\n```\n\n#### Timestamps\n\nEach log line captured from a worker's stdout/stderr is prefixed with a\ntimestamp, the process ID, and the worker ID. If the application's logs are\nalready prefixed with timestamps, the timestamping can be disabled with the\n`--no-timestamp-workers`.\n\nThe supervisor log messages are prefixed with a timestamp, the supervisor's\nprocess ID, and a worker ID of `supervisor`. If the supervisor is logging to\nstdout and is being captured by a logger that adds its own timestamps, these\nsupervisor log timestamps can be disabled with the `--no-timestamp-supervisor`\noption.\n\n#### Syslog\n\nOn platforms where syslog is supported, and when the optional strong-fork-syslog\ndependency has been successfully compiled, a `--syslog` option is available.\nWhen enabled, each log line from worker stdout/stderr and the supervisor is\nlogged via a `syslog(3)` system call. In this mode, the supervisor does **NOT**\ntimestamp the log entries, but **DOES** prepend process ID and worker ID since\nthe system call is performed by the supervisor, preventing the standard syslog\nPID stamping from being accurate.\n\n#### Log Rotation\n\nThe log file can be rotated with `SIGUSR2`, see Signal Handling below.\n\n### PID file\n\nSupervisor can optionally write a PID file with the master's PID. This could be\nuseful to send signals to a detached process from within system startup scripts\nas used by `init` or `upstart`.\n\n### Signal Handling\n\nThe supervisor will attempt a clean shutdown of the cluster before exiting if it\nis signalled with SIGINT or SIGTERM, see\n[control.stop()](http://apidocs.strongloop.com/strong-cluster-control/#controlstopcallback).\n\nIf the supervisor is logging to file, it will reopen those files when\nsignalled with SIGUSR2. This is useful in conjunction with tools like\n[logrotate](http://manpages.ubuntu.com/manpages/jaunty/man8/logrotate.8.html).\n\nIf the supervisor is clustered, it will attempt a restart of the cluster if it is\nsignalled with SIGHUP, see\n[control.restart()](http://apidocs.strongloop.com/strong-cluster-control/#controlrestart).\n\n\n## Usage\n\n### sl-run\n\n``` text\nusage: sl-run [options] [app [app-options...]]\n\nRun an app, allowing it to be profiled (using StrongOps) and supervised.\n\n`app` can be a node file to run or a package directory. The default value is\n\".\", the current working directory. Packages will be run by requiring the first\nthat is found of:\n  1. javascript file mentioned in `scripts.start` of package.json\n    *** NOTE: the script is not run and arguments are not preserved, only the\n        path of the script is used, eg:\n          `node --nodearg script.js --scriptarg` =\u003e 'script.js'\n          `node bin/www` =\u003e `bin/www`\n        The parser is simple, so options that accept arguments `--flag value`\n        will cause problems.\n  2. server.js\n  3. app.js\n  4. result of require(app)\n    1. `main` property of app package.json\n    2. `app`.js\n    3. `app`/index.js\n\n\nOptions:\n  -h,--help          Print this message and exit.\n  -v,--version       Print runner version and exit.\n  -l,--log FILE      Write supervisor and worker output to FILE\n                       (defaults to \"-\", meaning log to stdout).\n  --no-timestamp-workers\n                     Disable timestamping of worker log lines by supervisor.\n  --no-timestamp-supervisor\n                     Disable timestamping of supervisor log messages.\n  --no-log-decoration\n                     Disable decorating supervisor/worker log messages with\n                       cluster id/pid\n  --syslog           Send supervisor and collected worker logs to syslog,\n                       unsupported on Windows.\n  --metrics BACKEND  Report metrics to custom backend. Implies `--profile`.\n  -p,--pid FILE      Write supervisor's pid to FILE, failing if FILE already\n                       has a valid pid in it (default is no pid file).\n  --cluster N        Set the cluster size (default is 'cpu', but see below).\n  --profile          Inject node instrumentation, the default.\n  --no-profile       Do not inject node instrumentation.\n  -C,--control CTL   Listen for control messages on CTL (default `runctl`).\n  --no-control       Do not listen for control messages.\n\nLog FILE is a path relative to the app's working directory if it is not\nabsolute. To create a log file per process, FILE supports simple substitutions\nof %p for process ID and %w for worker ID.\n\nSupported metrics backends are:\n\n- `statsd://[\u003chost\u003e][:\u003cport\u003e]`\n- `graphite://[\u003chost\u003e][:\u003cport\u003e]`\n- `syslog:[?[application=\u003capplication\u003e][\u0026priority=\u003cpriority\u003e]` (syslog is the\n  Unix logging framework, it doesn't exist on Windows)\n- `splunk://[\u003chost\u003e]:\u003cport\u003e`\n- `log:[\u003cfile\u003e]`\n- `debug:[?pretty[=\u003ctrue|false\u003e]]`\n\nIt is possible to use multiple backends simultaneously.\n\nCluster size N is one of:\n\n- A number of workers to run\n- A string containing \"cpu\" to run a worker per CPU\n```\n\n### sl-runctl\n\n```\nusage: sl-runctl [options] [command]\n\nOptions:\n\n  -h,--help           Print this message and exit.\n  -v,--version        Print version and exit.\n  -C,--control \u003cCTL\u003e  Control endpoint for process runner (default `runctl`).\n\nCommands:\n\n  status                     Report status of cluster workers, the default.\n  set-size \u003cN\u003e               Set cluster size to N workers.\n  stop                       Stop, shutdown all workers and stop controller.\n  restart                    Restart, restart all workers.\n  ls [DEPTH]                 List application dependencies.\n  objects-start \u003cID\u003e         Start tracking objects on ID.\n  objects-stop \u003cID\u003e          Stop tracking objects on ID.\n      Object metrics are published, see the `--metrics` option to `sl-run`.\n\n  cpu-start \u003cID\u003e [TIMEOUT]   Start CPU profiling on ID.\n      TIMEOUT is the optional watchdog timeout, in milliseconds.  In watchdog\n      mode, the profiler is suspended until an event loop stall is detected;\n      i.e. when a script is running for too long.  Only supported on Linux.\n\n  cpu-stop \u003cID\u003e [NAME]       Stop CPU profiling on ID, save as \"NAME.cpuprofile\".\n      CPU profiles must be loaded into Chrome Dev Tools. The NAME is optional,\n      profiles default to being named `node.\u003cPID\u003e.cpuprofile`.\n\n  heap-snapshot \u003cID\u003e [NAME]  Snapshot heap objects for ID, save as\n                             \"NAME.heapsnapshot\".\n      Heap snapshots must be loaded into Chrome Dev Tools. The NAME is\n      optional, snapshots default to being named `node.\u003cPID\u003e.heapshapshot`.\n\n  patch \u003cID\u003e \u003cFILE\u003e          Apply patch FILE to ID.\n\n  env-get [ID]               Get the complete environment of the specified\n                             process. If no target is specified the default is 0,\n                             the cluster master process.\n\n  env-set \u003cK1=V1...\u003e         Set environment variables in master and worker.\n                             Changes are live without process restart.\n\n  env-unset \u003cKEYS...\u003e        Unset environment variables in master and workers.\n                             Changes are live without process restart.\n\nCommands specific to a worker ID accept either a process ID or cluster worker\nID, and use an ID of `0` to mean the cluster master.\n```\n\n\n## License\n\nstrong-supervisor uses a dual license model.\n\nYou may use this library under the terms of the [Artistic 2.0 license][].\n\n[Artistic 2.0 license]: http://opensource.org/licenses/Artistic-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstrongloop%2Fstrong-supervisor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstrongloop%2Fstrong-supervisor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstrongloop%2Fstrong-supervisor/lists"}