Menu

AppSignal Wrap for process monitoring

AppSignal provides appsignal-wrap, a tool to monitor any processes running in your server, such as your cron jobs, your database server, or any other processes pertaining to your application.

The appsignal-wrap tool seamlessly integrates with AppSignal's cron and heartbeat check-ins, logging, and error reporting. It can be used to monitor any process running on your servers, regardless of the language or framework it's written in.

AppSignal Wrap helps answer questions like:

Is my database process up and running?
Is my cron job running on time?
What went wrong with my backup script?
Did my application server fail to start?

Core appsignal-wrap features

After installing appsignal-wrap, you can use the tool to start processes you want to monitor. The appsignal-wrap tool will then:

Report the standard output and standard error of the process, as logs that you can filter and query on AppSignal Logging.

Send cron check-ins to report that the process has started and finished successfully, or heartbeat check-ins to keep track of its uptime.

Report failure exit statuses as errors to AppSignal.

Installation

The easiest way to install appsignal-wrap is to run the following command:

Shell
curl -sSL https://github.com/appsignal/appsignal-wrap/releases/latest/download/install.sh | sudo sh

The command will automatically download the latest release of appsignal-wrap for your OS (operating system) and architecture, and install it to your server's $PATH.

Both Linux and macOS are supported, in the x86 64-bit (Intel) and ARM 64-bit (Apple Silicon) architectures. Alpine Linux is also supported through our musl-enabled builds for both architectures.

Alternatively, you can download the latest release from the GitHub releases page for your operating system and architecture, and install it manually to your server's $PATH.

Usage

To monitor a process with appsignal-wrap, you pass the command that you want to monitor as the last argument to appsignal-wrap. For example:

Shell
export APPSIGNAL_APP_LEVEL_API_KEY=[APP_LEVEL_API_KEY]
appsignal-wrap [NAME] -- [COMMAND]

In the above example, [NAME] is the name that you want to use to identify the process in AppSignal, and [COMMAND] is the command that you want to monitor. Both the name and the command are required. For example:

Shell
appsignal-wrap backup-script -- bash /var/app/backup.sh

You'll need an AppSignal app-level API key, which you can find in the "Push & Deploy" settings of your AppSignal app.

You can provide it to appsignal-wrap as the argument to the --api-key command-line option, or as the APPSIGNAL_APP_LEVEL_API_KEY environment variable.

By default, appsignal-wrap will report the standard output and standard error of the process as logs to AppSignal, and report any failure exit statuses to AppSignal as errors.

Check-ins

Read our Check-ins documentation for more information on how AppSignal Check-ins work.

By default, appsignal-wrap will not send any check-in events. You can use the --cron or --heartbeat command-line options to enable cron or heartbeat check-ins respectively.

The appsignal-wrap tool will use the name provided as the first argument as the check-in identifier. For example, to report cron check-in events with backup-script as the check-in identifier:

Shell
appsignal-wrap backup-script --cron -- bash /var/app/backup.sh

Cron check-ins

When using --cron to send cron check-ins, appsignal-wrap will send a start cron check-in event when the process starts, and a finish cron check-in event if the process finishes successfully.

If the process exits with a failure exit status, appsignal-wrap will not send a finish cron check-in event.

Heartbeat check-ins

When using --heartbeat to send heartbeat check-ins, appsignal-wrap will send heartbeat check-in events continuously during the lifetime of the process.

Custom identifier

To send check-in events to AppSignal with an identifier different from the name provided as the first argument, you can pass a different identifier as an argument to the --cron or --heartbeat command-line options. For example:

Shell
appsignal-wrap backup --cron daily-backup -- bash /var/app/backup.sh

In the above example, appsignal-wrap will send cron check-in events with daily-backup as the check-in identifier, but will still use backup as the name to identify the process when reporting logs and errors.

Logging

By default, appsignal-wrap will send both the standard output and standard error of the process it monitors as logs to AppSignal. The logs will appear under the "application" source, and the name provided as the first argument will be used as the log group.

Disable logging

To disable sending either the standard output or standard error as logs, you can use the --no-stdout or --no-stderr command-line options respectively.

To disable sending logs altogether, you can use the --no-log command-line option.

Custom log group

To send logs as a different log group, you can pass it as an argument to the --log command-line option. For example:

Shell
appsignal-wrap mysql --log db -- mysqld

In the above example, appsignal-wrap will use db as the log group when sending logs to AppSignal, but will still use mysql as the name to identify the process when reporting check-ins and errors.

Custom log source

To send logs to a different log source, you can pass the log source's API key, which you obtain when creating a log source, as an argument to the --log-source command-line option, or as the APPSIGNAL_LOG_SOURCE_API_KEY environment variable. For example:

Shell
export APPSIGNAL_LOG_SOURCE_API_KEY=[LOG_SOURCE_API_KEY]
appsignal-wrap mysql -- mysqld

Error reporting

By default, appsignal-wrap will report any failure exit statuses of the process it monitors as errors to AppSignal. The errors will be grouped by the name provided as the first argument.

Disable error reporting

To disable reporting errors entirely, you can use the --no-error command-line option.

Output in error messages

When reporting errors to AppSignal, appsignal-wrap will include the last few lines of the standard output and standard error of the process as the error message.

Using the --no-stdout or --no-stderr command-line options will prevent the standard output or standard error from being included in the error message.

Using both options will prevent any logs from being included in the error message.

Custom error grouping

To group errors differently, you can pass a different name as an argument to the --error command-line option. For example:

Shell
appsignal-wrap backup --error user-backup -- bash /var/app/backup.sh --only-users

In the above example, appsignal-wrap will report errors with user-backup as the error group, but will still use backup as the name to identify the process when reporting logs and check-ins.

Process behavior

The appsignal-wrap tool aims to be transparent -- that is, running some command using appsignal-wrap should have the same behavior as running that same command by itself.

After the monitored process finishes, appsignal-wrap will wait for a short period of time (usually one second or less) before exiting, in order to ensure that all logs and check-ins are sent to AppSignal.

If invoking appsignal-wrap in a loop, the delay caused by this wait may cause the loop to run slower than expected.

Environment variables

The process automatically inherits the environment variables of the appsignal-wrap parent process.

Exit status

If the process it monitors exits with an exit code, appsignal-wrap will exit with the same failure exit code.

If the process it monitors is terminated by a signal, appsignal-wrap will exit with a failure exit code of 128 + signal, where signal is the number representing the signal that caused the process to terminate. The signal that this number represents is operating system-specific.

Input and output

The process automatically inherits its standard input descriptor from the appsignal-wrap parent process.

In addition to reporting them to AppSignal, the standard output and standard error of the process are piped to the standard output and standard error of the appsignal-wrap parent process.

When using --no-stdout or --no-stderr, the process automatically inherits the standard output or standard error descriptor, respectively, of the appsignal-wrap parent process.

This means that you can use appsignal-wrap in a pipeline, or redirect its output to a file, for example:

Shell
# Without monitoring
grep "active" customers.csv \
    | python /var/app/import.py \
    > /var/log/import.log
 
# With monitoring
grep "active" customers.csv \
    | appsignal-wrap import-customers -- python /var/app/import.py \
    > /var/log/import.log

Signals

When the appsignal-wrap process receives a signal that can be handled, it will forward it to the process it monitors.

For example, sending a SIGTERM signal to the appsignal-wrap parent process will cause the process it monitors to receive a SIGTERM signal.

When the appsignal-wrap parent process receives a signal that cannot be handled, such as SIGKILL and SIGSTOP, or if it unexpectedly crashes, a SIGTERM signal will be sent to the process it monitors.

On macOS, signals that cannot be handled, such as SIGKILL and SIGSTOP, will not cause the process it monitors to receive any signal.