appsignal-wrap is a tool that allows you to monitor any process with AppSignal. You can use it to:

• Send the process' standard output and standard error as logs to AppSignal, to be able to troubleshoot issues.
• Send a start cron check-in to AppSignal when the process starts, and a finish cron check-in if it finishes successfully, to be able to track whether it runs successfully and on schedule.
• Send heartbeat check-ins to AppSignal periodically, for as long as the process is active, to be able to monitor its uptime.

The easiest way to get appsignal-wrap in your machine is to run our installation one-liner:

curl -sSL https://raw.githubusercontent.com/appsignal/appsignal-wrap/refs/heads/main/install.sh | sh

You'll need to run it with super-user privileges -- if you're not running this as root, prefix it with sudo.

Currently, appsignal-wrap is only supported for Linux, in the x86_64 and ARM64 architectures. Linux distributions based on musl, such as Alpine, are also supported.

Not a fan of curl | sh one-liners? Download the binary for your operating system and architecture from our latest release.

appsignal-wrap [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 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.

See appsignal-wrap --help for detailed information on all configuration options.

You can use the --heartbeat command-line option to send heartbeat check-ins (named database in this example) to AppSignal periodically, for as long as the database process is running. This allows you to set up alerts that will notify you if the database is no longer running.

In this example, we'll start mysqld, the MySQL server process, using appsignal-wrap:

appsignal-wrap --heartbeat database -- mysqld

This invocation can then be added to the mysql.service service definition:

# /usr/lib/systemd/system/mysql.service

[Service]
# Modify the existing ExecStart line to add `appsignal-wrap`
ExecStart=/usr/local/bin/appsignal-wrap --heartbeat database -- /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.

You can use the --cron command-line option to send cron check-ins (named backup in this example) to notify AppSignal when your cron job starts, and when it finishes, if and only if it finishes successfully.

In this example, we'll run /usr/local/bin/backup.sh, our custom backup shell script, using appsignal-wrap:

appsignal-wrap --cron backup -- bash /usr/local/bin/backup.sh

This invocation can then be added to the /etc/crontab file:

# /etc/crontab

APPSIGNAL_APP_PUSH_API_KEY=...

0 2 * * * appsignal-wrap --cron backup -- 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.