Process monitoring

AppSignal provides appsignal-run, 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-run 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 Process monitoring 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-run features

After installing appsignal-run, you can use the tool to start processes you want to monitor. The appsignal-run 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-run is to run the following command:

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

The command will automatically download the latest release of appsignal-run 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-run, you pass the command that you want to monitor as the last argument to appsignal-run. For example:

export APPSIGNAL_APP_LEVEL_API_KEY=[APP_LEVEL_API_KEY]
appsignal-run [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:

appsignal-run 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-run as the argument to the --api-key command-line option, or as the APPSIGNAL_APP_LEVEL_API_KEY environment variable.

By default, appsignal-run 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

By default, appsignal-run 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-run 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:

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

Cron check-ins

When using --cron to send cron check-ins, appsignal-run 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-run will not send a finish cron check-in event.

Heartbeat check-ins

When using --heartbeat to send heartbeat check-ins, appsignal-run 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:

appsignal-run backup --cron daily-backup -- bash /var/app/backup.sh

In the above example, appsignal-run 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-run 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:

appsignal-run mysql --log db -- mysqld

In the above example, appsignal-run 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:

export APPSIGNAL_LOG_SOURCE_API_KEY=[LOG_SOURCE_API_KEY]
appsignal-run mysql -- mysqld

Error reporting

By default, appsignal-run 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-run 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:

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

In the above example, appsignal-run 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-run tool aims to be transparent -- that is, running some command using appsignal-run should have the same behavior as running that same command by itself.

Environment variables

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

Exit status

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

If the process it monitors is terminated by a signal, appsignal-run 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-run 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-run parent process.

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

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

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

Signals

When the appsignal-run 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-run parent process will cause the process it monitors to receive a SIGTERM signal.

When the appsignal-run 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.