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 process monitors, 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 process monitors to report that the process has started and finished successfully, or heartbeat process monitors 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:

Bash

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_PUSH_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_PUSH_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.

Process Monitoring

Read our Process Monitoring documentation for more information on how AppSignal Process Monitoring works.

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

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

Shell

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

Cron process monitors

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

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

Heartbeat process monitors

When using --heartbeat to send heartbeat process monitors, appsignal-wrap will send heartbeat process monitor events continuously during the lifetime of the process.

Custom identifier

To send process monitor 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 process monitor events with daily-backup as the process monitor 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 process monitors 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 process monitors.

Application revision

If a revision is provided using the --revision flag or the APPSIGNAL_REVISION environment variable, errors will be grouped with the deployment for that revision.

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 process monitors 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.