Merge pull request #24 from appsignal/add-name-argument

Add name argument

.changesets/add-required-name-argument.md

@@ -0,0 +1,32 @@
+---
+bump: minor
+type: change
+---
+
+Add a required positional argument for the name. This name is used as the identifier for cron and heartbeat check-ins, the group for logs, and the action name for errors.
+
+This avoids repetition of command-line parameters that represent the name:
+
+```sh
+# Before:
+appsignal-wrap \ 
+  --cron backup \ 
+  --error backup \ 
+  --log backup \ 
+  -- ./backup.sh
+
+# After:
+appsignal-wrap backup \ 
+  --cron \ 
+  -- ./backup.sh
+```
+
+It is still possible to override the name for a specific purpose by using the `--log GROUP` and `--error ACTION` arguments, or by passing an identifier to either `--cron` or `--heartbeat`:
+
+```sh
+appsignal-wrap mysql \ 
+  --heartbeat db
+  -- mysqld
+```
+
+Additionally, error sending is now enabled by default (use `--no-error` to disable it) and using both cron and heartbeat check-ins in the same invocation is no longer allowed.

README.md

@@ -22,19 +22,69 @@ Not a fan of `curl | sh` one-liners? Download the binary for your operating syst
 
 ## Usage
 
+See `appsignal-wrap --help` for detailed information on all configuration options.
+
 ```
-appsignal-wrap [OPTIONS] -- COMMAND
+appsignal-wrap NAME [OPTIONS] -- COMMAND
 ```
 
 To use `appsignal-wrap`, you must provide an app-level API key. You can find the app-level API key in the [push and deploy settings](https://appsignal.com/redirect-to/app?to=api_keys) for your application.
 
 To provide the app-level API key, set it as the value for the `APPSIGNAL_APP_PUSH_API_KEY` environment variable, or pass it as the value for the `--api-key` command-line option.
 
-You must also provide a command to execute, as the last argument, preceded by `--`. This is the command whose output and lifecycle will be monitored with AppSignal.
+You must also provide a name as the first argument, which will be used as the identifier for cron and heartbeat check-ins, as the group for logs, and as the action to group errors in AppSignal.
 
-## Examples
+Finally, you must provide a command to execute as the last argument, preceded by `--`. This is the command whose output and lifecycle will be monitored with AppSignal.
 
-See `appsignal-wrap --help` for detailed information on all configuration options.
+### Send standard output and error as logs to AppSignal
+
+By default, `appsignal-wrap` will send the standard output and standard error of the command it executes as logs to AppSignal:
+
+```sh
+appsignal-wrap sync_customers -- python ./sync_customers.py
+```
+
+The above command will execute `python ./sync_customers.py` with the AppSignal wrapper, sending its standard output and error as logs to AppSignal.
+
+You can disable sending logs entirely by using the `--no-log` command-line option, and you can use `--no-stdout` and `--no-stderr` to control whether standard output and error are used to send logs to AppSignal.
+
+### Report failure exit codes as errors to AppSignal
+
+By default, `appsignal-wrap` will report an error to AppSignal if the command it executes exits with a failure exit code, or if the command fails to be executed:
+
+```sh
+appsignal-wrap sync_customers -- python ./sync_customers.py
+```
+
+The above command will attempt to execute `python ./sync_customers.py` with the AppSignal wrapper, and it will report an error to AppSignal if it fails to execute the command, or if the command ends with a failure exit code.
+
+You can disable sending errors entirely by using the `--no-error` command-line option.
+
+### Send heartbeat check-ins to AppSignal while your process is running
+
+Use the `--heartbeat` flag to send heartbeat check-ins continuously to AppSignal, for as long as the process is running. This allows you to track that certain processes are always up:
+
+```sh
+appsignal-wrap worker --heartbeat -- bundle exec ./worker.rb
+```
+
+The above command will execute `bundle exec ./worker.rb`, and send heartbeat check-ins to AppSignal with the `worker` check-in identifier continuously, for as long as the process is running.
+
+It will also send logs and report errors, as described in previous sections. To only send heartbeat check-ins, use `--no-log` and `--no-error`.
+
+### Send cron check-ins to AppSignal when your process starts and finishes
+
+Use the `--cron` flag to send a start cron check-in to AppSignal when the process starts, and a finish cron check-in to AppSignal if it finishes successfully. This allows you to track that certain processes are executed on schedule:
+
+```sh
+appsignal-wrap sync_customers --cron -- python ./sync_customers.py
+```
+
+The above command will execute `bundle exec ./worker.rb`, send a start cron check-in to AppSignal with the `sync_customers` check-in identifier if it starts successfully, and send a finish cron check-in to AppSignal if it finishes with a success exit code.
+
+It will also send logs and report errors, as described in previous sections. To only send cron check-ins, use `--no-log` and `--no-error`.
+
+## Examples
 
 ### Monitor your database's uptime with AppSignal
 
@@ -43,7 +93,7 @@ You can use the `--heartbeat` command-line option to send heartbeat check-ins (n
 In this example, we'll start `mysqld`, the MySQL server process, using `appsignal-wrap`:
 
 ```sh
-appsignal-wrap --heartbeat database -- mysqld
+appsignal-wrap database --heartbeat -- mysqld
 ```
 
 This invocation can then be added to the `mysql.service` service definition:
@@ -53,12 +103,17 @@ This invocation can then be added to the `mysql.service` service definition:
 
 [Service]
 # Modify the existing ExecStart line to add `appsignal-wrap`
-ExecStart=/usr/local/bin/appsignal-wrap --heartbeat database -- /usr/sbin/mysqld
+ExecStart=/usr/local/bin/appsignal-wrap database --heartbeat -- /usr/sbin/mysqld
 # Add an environment variable containing the AppSignal app-level push API key
 Environment=APPSIGNAL_APP_PUSH_API_KEY=...
 ```
 
-In addition to the specified heartbeat check-ins, by default `appsignal-wrap` will also send your database process' standard output and standard error as logs to AppSignal. Use the `--no-log` configuration option to disable this behaviour.
+In addition to sending heartbeat check-ins, by default `appsignal-wrap` will also: 
+
+- Send your database process' standard output and standard error as logs to AppSignal, under the `database` group
+- Report failure exit codes as errors to AppSignal, grouped under the `database` action
+
+You can use the `--no-log` and `--no-error` command-line option to disable this behaviour.
 
 ### Monitor your cron jobs with AppSignal
 
@@ -67,7 +122,7 @@ You can use the `--cron` command-line option to send cron check-ins (named `back
 In this example, we'll run `/usr/local/bin/backup.sh`, our custom backup shell script, using `appsignal-wrap`:
 
 ```sh
-appsignal-wrap --cron backup -- bash /usr/local/bin/backup.sh
+appsignal-wrap backup --cron -- bash /usr/local/bin/backup.sh
 ```
 
 This invocation can then be added to the `/etc/crontab` file:
@@ -77,7 +132,12 @@ This invocation can then be added to the `/etc/crontab` file:
 
 APPSIGNAL_APP_PUSH_API_KEY=...
 
-0 2 * * * appsignal-wrap --cron backup -- bash /usr/local/bin/backup.sh
+0 2 * * * appsignal-wrap backup --cron -- bash /usr/local/bin/backup.sh
 ```
 
-In addition to the specified cron check-ins, by default `appsignal-wrap` will also send your database process' standard output and standard error as logs to AppSignal. Use the `--no-log` configuration option to disable this behaviour.
+In addition to sending cron check-ins, by default `appsignal-wrap` will also: 
+
+- Send your database process' standard output and standard error as logs to AppSignal, under the `backup` group
+- Report failure exit codes as errors to AppSignal, grouped under the `backup` action
+
+You can use the `--no-log` and `--no-error` command-line option to disable this behaviour.