> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AppSignal Wrap for process monitoring

export const Compatibility = ({versions = [], label = "Available in"}) => {
  if (!Array.isArray(versions) || versions.length === 0) {
    return null;
  }
  const defaultPillStyle = {
    borderColor: "#d4d4d8",
    background: "#f4f4f5",
    color: "#3f3f46"
  };
  const pillStyles = {
    "AppSignal for Elixir": {
      background: "#f3e8ff",
      borderColor: "#d8b4fe",
      color: "#6b21a8"
    },
    "AppSignal for Front-end": {
      background: "#fef9c3",
      borderColor: "#fde047",
      color: "#854d0e"
    },
    "AppSignal for Go": {
      background: "#ccfbf1",
      borderColor: "#5eead4",
      color: "#115e59"
    },
    "AppSignal for JavaScript": {
      background: "#fef9c3",
      borderColor: "#fde047",
      color: "#854d0e"
    },
    "AppSignal for Node.js": {
      background: "#dcfce7",
      borderColor: "#86efac",
      color: "#166534"
    },
    "AppSignal for Python": {
      background: "#dbeafe",
      borderColor: "#93c5fd",
      color: "#1e40af"
    },
    "AppSignal for Ruby": {
      background: "#fee2e2",
      borderColor: "#fca5a5",
      color: "#991b1b"
    },
    "AppSignal for Rust": {
      background: "#ffedd5",
      borderColor: "#fdba74",
      color: "#9a3412"
    }
  };
  const getPillStyle = name => ({
    ...defaultPillStyle,
    ...pillStyles[name] || ({})
  });
  return <div className="not-prose my-4 rounded-lg border border-zinc-200 bg-zinc-50 px-4 py-3 text-sm dark:border-white/10 dark:bg-white/5">
      <div className="flex flex-wrap items-center gap-x-2 gap-y-1">
        <span className="font-semibold text-zinc-700 dark:text-zinc-200">
          {label}:
        </span>
        {versions.map((v, i) => <span key={`${v.name}-${v.version}-${i}`} className="inline-flex items-center gap-1 rounded-full border px-2 py-0.5 text-xs font-medium" style={getPillStyle(v.name)}>
            <span>{v.name}</span>
            <span className="opacity-70">
              {v.version}
              {v.exact ? "" : "+"}
            </span>
          </span>)}
      </div>
    </div>;
};

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:

<div style={{ display: 'flex', alignItems: 'center', gap: '12px', marginBottom: '12px' }}>
  <span style={{ display: 'inline-flex', alignItems: 'center', justifyContent: 'center', width: '32px', height: '32px', minWidth: '32px', backgroundColor: '#dcfce7', borderRadius: '8px' }}>
    <Icon icon="check" color="#22c55e" />
  </span>

  <span>Is my database process up and running?</span>
</div>

<div style={{ display: 'flex', alignItems: 'center', gap: '12px', marginBottom: '12px' }}>
  <span style={{ display: 'inline-flex', alignItems: 'center', justifyContent: 'center', width: '32px', height: '32px', minWidth: '32px', backgroundColor: '#dcfce7', borderRadius: '8px' }}>
    <Icon icon="check" color="#22c55e" />
  </span>

  <span>Is my cron job running on time?</span>
</div>

<div style={{ display: 'flex', alignItems: 'center', gap: '12px', marginBottom: '12px' }}>
  <span style={{ display: 'inline-flex', alignItems: 'center', justifyContent: 'center', width: '32px', height: '32px', minWidth: '32px', backgroundColor: '#dcfce7', borderRadius: '8px' }}>
    <Icon icon="check" color="#22c55e" />
  </span>

  <span>What went wrong with my backup script?</span>
</div>

<div style={{ display: 'flex', alignItems: 'center', gap: '12px', marginBottom: '12px' }}>
  <span style={{ display: 'inline-flex', alignItems: 'center', justifyContent: 'center', width: '32px', height: '32px', minWidth: '32px', backgroundColor: '#dcfce7', borderRadius: '8px' }}>
    <Icon icon="check" color="#22c55e" />
  </span>

  <span>Did my application server fail to start?</span>
</div>

### 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:

<div style={{ display: 'flex', alignItems: 'flex-start', gap: '12px', marginBottom: '12px' }}>
  <span style={{ display: 'inline-flex', alignItems: 'center', justifyContent: 'center', width: '32px', height: '32px', minWidth: '32px', backgroundColor: '#fce7f3', borderRadius: '8px' }}>
    <Icon icon="line-columns" color="#ec4899" />
  </span>

  <span>Report the standard output and standard error of the process, as logs that you can filter and query on [AppSignal Logging](/logging).</span>
</div>

<div style={{ display: 'flex', alignItems: 'flex-start', gap: '12px', marginBottom: '12px' }}>
  <span style={{ display: 'inline-flex', alignItems: 'center', justifyContent: 'center', width: '32px', height: '32px', minWidth: '32px', backgroundColor: '#dbeafe', borderRadius: '8px' }}>
    <Icon icon="square-check" iconType="solid" color="#3b82f6" />
  </span>

  <span>Send [cron process monitors](/check-ins) to report that the process has started and finished successfully, or [heartbeat process monitors](/check-ins) to keep track of its uptime.</span>
</div>

<div style={{ display: 'flex', alignItems: 'flex-start', gap: '12px', marginBottom: '12px' }}>
  <span style={{ display: 'inline-flex', alignItems: 'center', justifyContent: 'center', width: '32px', height: '32px', minWidth: '32px', backgroundColor: '#fee2e2', borderRadius: '8px' }}>
    <Icon icon="siren-on" iconType="solid" color="#ef4444" />
  </span>

  <span>Report failure exit statuses as errors to AppSignal.</span>
</div>

## Installation

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

<CodeGroup>
  ```bash Bash theme={null}
  curl -sSL https://github.com/appsignal/appsignal-wrap/releases/latest/download/install.sh | sudo sh
  ```
</CodeGroup>

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](https://github.com/appsignal/appsignal-wrap/releases/latest/) 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:

<CodeGroup>
  ```sh Shell theme={null}
  export APPSIGNAL_APP_PUSH_API_KEY=[APP_LEVEL_API_KEY]
  appsignal-wrap [NAME] -- [COMMAND]
  ```
</CodeGroup>

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:

<CodeGroup>
  ```sh Shell theme={null}
  appsignal-wrap backup-script -- bash /var/app/backup.sh
  ```
</CodeGroup>

You'll need an AppSignal app-level API key, which you can find in the ["Push & Deploy"](https://appsignal.com/redirect-to/app?to=api_keys\&key_tab=app) 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.

<span id="check-ins" />

## Process Monitoring

<Tip>
  [Read our Process Monitoring documentation](/check-ins) for more information on how
  AppSignal Process Monitoring works.
</Tip>

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:

<CodeGroup>
  ```sh Shell theme={null}
  appsignal-wrap backup-script --cron -- bash /var/app/backup.sh
  ```
</CodeGroup>

### 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:

<CodeGroup>
  ```sh Shell theme={null}
  appsignal-wrap backup --cron daily-backup -- bash /var/app/backup.sh
  ```
</CodeGroup>

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:

<CodeGroup>
  ```sh Shell theme={null}
  appsignal-wrap mysql --log db -- mysqld
  ```
</CodeGroup>

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](https://docs.appsignal.com/logging/configuration.html#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:

<CodeGroup>
  ```sh Shell theme={null}
  export APPSIGNAL_LOG_SOURCE_API_KEY=[LOG_SOURCE_API_KEY]
  appsignal-wrap mysql -- mysqld
  ```
</CodeGroup>

## 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:

<CodeGroup>
  ```sh Shell theme={null}
  appsignal-wrap backup --error user-backup -- bash /var/app/backup.sh --only-users
  ```
</CodeGroup>

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

<Compatibility versions={[{ name: "AppSignal Wrap", version: "0.3.1" }]} />

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.

<Note>
  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.
</Note>

### 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:

<CodeGroup>
  ```sh Shell theme={null}
  # 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
  ```
</CodeGroup>

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