Supported operating systems - AppSignal Documentation

The AppSignal integrations for Ruby, Elixir & Node.js contain native extensions and a separate lightweight agent process. These native extensions are supported on most Linux distributions, FreeBSD and macOS/OSX. Our Go and Python integrations only use our agent process and don’t require additional packages to be installed. Like the other integrations, they only work on the supported Operating Systems listed in the support table. If an Operating System you use is not supported, please get in touch.

Support table

Table of different Operating Systems and architecture combinations we support. Check the notes below the table for any exceptions and version requirements.

Integrations

Our integrations include the: Ruby gem, Elixir package, Node.js package and Python package.

	x86 64-bit	ARM 64-bit
macOS/OSX ¹
Linux
- Alpine Linux		²
- CentOS
- Debian / Ubuntu
- Fedora
FreeBSD ^{1 3}	?
Microsoft Windows⁴
- Subsystem for Linux	? ⁴

1: Does not support host metrics.
2: Not supported for our Node.js integration.
3: Support level unclear, see FreeBSD.
4: Does not work natively on Windows. AppSignal does not provide official support for the Windows Subsystem for Linux.

Components

Additional components include: Collector, Standalone agent, Wrap.

	x86 64-bit	ARM 64-bit
macOS/OSX
Linux
- Alpine Linux	¹	¹
- CentOS
- Debian / Ubuntu
Microsoft Windows²
- Subsystem for Linux	? ²	? ²
Docker image	³	³

No additional dependencies have to be installed for these components unless listed in their installation guides.

1: Alpine Linux is only supported by Wrap.
2: Does not work natively on Windows. AppSignal does not provide official support for the Windows Subsystem for Linux.
3: Wrap is not available as a Docker image.

Linux

AppSignal tries to support Linux as best as possible, but some changes in our build process have caused some problems with supporting certain Linux distributions and versions. Our agent and extension are compiled against libc, and based on which version of libc we compile against we support certain older versions of Linux distributions and some not.

Supported versions

AppSignal support for versions of libc has changed over the past few versions of the Ruby gem and Elixir package. AppSignal for Ruby v2.4.1 and AppSignal for Elixir v1.4.3 and higher detect an older libc version and switch to the musl build automatically, so most apps need nothing from this section. For older versions, this table lists the libc and musl versions each package version range was compiled against:

Package	Versions	Compiled against libc	Compiled against musl
Elixir	`v0.0.x` – `v0.10.x`	`v2.5`	None ¹
Elixir	`v0.11.x` – `v1.3.x`	None ²	`v1.1.16`
Elixir	`v1.4.x` and higher	`v2.15`	`v1.1.16`
Node.js	`v1.0.0` and higher	`v2.15`	`v1.1.16`
Python	`v0.1.0` and higher	`v2.15`	`v1.1.16`
Ruby	`v1.0.0` – `v2.0.x`	`v2.5`	None ¹
Ruby	`v2.1.x` – `v2.3.x`	None ²	`v1.1.16`
Ruby	`v2.4.x` and higher	`v2.15`	`v1.1.16`

1: These versions shipped a libc build only. There was no musl build.
2: These versions shipped a musl build only, which was used on every system, including libc systems. See the DNS timeouts known issue.

If your system uses an older libc version than the AppSignal extension is compiled against, you will experience problems installing or running the AppSignal agent. If this is the case you can instead opt in to the musl build, which doesn’t have this issue. Warning for JRuby: JRuby support on Alpine Linux (musl build) is supported since Ruby gem 2.8.0. This scenario requires a dynamic build of the AppSignal extension, which is not supported for the musl build for older versions of the gem. You can see which version of libc your system uses by running the following command: ldd --version 2>&1 Example of output on Ubuntu 12.04:

$ ldd --version 2>&1
ldd (Ubuntu EGLIBC 2.15-0ubuntu10.18) 2.15
Copyright (C) 2012 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
Written by Roland McGrath and Ulrich Drepper.

Musl build override

To opt-in to the musl build manually, add the APPSIGNAL_BUILD_FOR_MUSL environment variable to your system environment before installing AppSignal and compiling your application. This environment variable is only needed if our auto detection does not detect the correct architecture.

# For Ruby
export APPSIGNAL_BUILD_FOR_MUSL=1
gem install appsignal
# or with Bundler
bundle install

# For Elixir
export APPSIGNAL_BUILD_FOR_MUSL=1
mix deps.get
mix compile

# For Node.js
export APPSIGNAL_BUILD_FOR_MUSL=1
npm install

# For Python
# Not supported

Linux ARM build override

The AppSignal packages will automatically detect ARM based hosts and select the agent and extension to install for ARM systems. When this detection doesn’t work, opt-in to the Linux ARM build manually with the APPSIGNAL_BUILD_FOR_LINUX_ARM environment variable. Add it to your system environment before installing AppSignal and compiling your application. This environment variable is only needed if our auto detection does not detect the correct architecture.

Available in these packages:

Ruby gem 3.0.8 or newer.
Elixir package 2.1.8 or newer.
Node.js package 1.2.6 or newer.

Not supported in our Python package.

# Set this environment variable
# Note: How environment variables are set may be different for your Operating
# System.
export APPSIGNAL_BUILD_FOR_LINUX_ARM=1
# Run the install command, such as: bundle install, npm install, mix compile

Alpine Linux

Ruby: supports Alpine Linux since Ruby gem version 2.1.0. (JRuby is not supported on Alpine Linux.)
Elixir: supports Alpine Linux since Elixir package version 0.11.0.
Node.js: supports Alpine Linux since Node.js package version 3.0.2. Not supported for Node.js version 14.

In AppSignal for Ruby version 2.4.0 and AppSignal for Elixir 1.4.0 we started shipping a separate build for Alpine Linux. If you upgraded from an earlier version and are have problems compiling your app, our detection isn’t working properly. The following system dependencies are required for Alpine Linux:

# Dependencies for the AppSignal Ruby gem
apk add make gcc musl-dev musl-utils

# Dependencies for the AppSignal Node.js package
apk add python3 make g++

# Dependencies for the AppSignal for Elixir package version 1.7.0 and newer
apk add make gcc musl-dev musl-utils
# Dependencies for the AppSignal for Elixir package version 1.6.3 and older
apk add make gcc musl-dev musl-utils curl

For all integrations, detection is based on the output from ldd --version. If your app is unable to call the ldd program or the detection is off for some reason, you can force the Alpine Linux compatible build by providing a special environment variable on install.

# For Ruby
export APPSIGNAL_BUILD_FOR_MUSL=1
gem install appsignal
# or with Bundler
bundle install

# For Elixir
export APPSIGNAL_BUILD_FOR_MUSL=1
mix deps.get
mix compile

# For Node.js
export APPSIGNAL_BUILD_FOR_MUSL=1
npm install

Ruby

For the Ruby gem add this to your Gemfile:

gem "appsignal", ">= 2.1.0" # or a newer version

For the latest available version see the full list on RubyGems.org and if you run into any problems please let us know.

Elixir

If you’re using the Elixir package, add this to the deps section your mix.exs file:

{:appsignal, ">= 1.0.0"} # or a newer version

For the latest available version see the full list on Hex.pm and if you run into any problems please let us know.

Node.js

If you’re using the Node.js package, add this to the dependencies section of your package.json file:

Text

"@appsignal/nodejs": "^3.0.2"

For the latest available version see the full list on NPM and if you run into any problems please let us know.

CentOS

CentOS is fully supported by the AppSignal extension. Depending on your CentOS version you may need to select another build type for AppSignal Ruby gem v2.4.0 and AppSignal for Elixir v1.4.0 and higher. The following system dependencies are required for CentOS:

# Dependencies for the AppSignal Ruby gem and Node.js package
yum install gcc gcc-c++ make openssl-devel

# Dependencies for the AppSignal for Elixir package version 1.7.0 and newer
yum install gcc gcc-c++ make openssl-devel
# Dependencies for the AppSignal for Elixir package version 1.6.3 and older
yum install gcc gcc-c++ make openssl-devel curl

# Dependencies for the AppSignal for Node.js package version 2.3.4 or newer, the supported Python versions are those between Python 3.7 and Python 3.10.
# Dependencies for the AppSignal for Node.js package version 2.3.3 or below, the supported Python versions are those between Python 3.5 and Python 3.8.
yum install python3

For CentOS 7 and higher there is no problem upgrading to AppSignal for Ruby v2.4.0 and AppSignal for Elixir 1.4.0 and higher. For CentOS 6 and older versions you will need to opt-in to the musl build for AppSignal instead. For more information, see the Linux section.

Debian / Ubuntu

The following system dependencies are required for Debian Linux distributions:

# Dependencies for the AppSignal Ruby gem and Node.js package
apt-get update
apt-get install build-essential ca-certificates

# Dependencies for the AppSignal for Elixir package version 1.7.0 and newer
apt-get update
apt-get install build-essential ca-certificates
# Dependencies for the AppSignal for Elixir package version 1.6.3 and older
apt-get update
apt-get install build-essential ca-certificates curl

# Dependencies for the AppSignal for Node.js package version 2.3.4 or newer, the supported Python versions are those between Python 3.7 and Python 3.10.
# Dependencies for the AppSignal for Node.js package version 2.3.3 or below, the supported Python versions are those between Python 3.5 and Python 3.8.
apt-get install python3

Fedora

The following system dependencies are required for Fedora Linux distributions:

# Dependencies for the AppSignal Ruby gem
dnf install gcc gcc-c++ make openssl-devel

# Dependencies for the AppSignal for Elixir package version 1.7.0 and newer
dnf install gcc gcc-c++ make openssl-devel
# Dependencies for the AppSignal for Elixir package version 1.6.3 and older
dnf install gcc gcc-c++ make openssl-devel curl

# Dependencies for the AppSignal for Node.js package version 2.3.4 or newer, the supported Python versions are those between Python 3.7 and Python 3.10.
# Dependencies for the AppSignal for Node.js package version 2.3.3 or below, the supported Python versions are those between Python 3.5 and Python 3.8.
dnf install python3

FreeBSD

Our level of FreeBSD support is currently unclear. Our tests show it works on FreeBSD 11, but we have not been able to see it report data on FreeBSD 12 and newer. Assume it will not report data on FreeBSD 12 and newer.

Support for FreeBSD systems was added in AppSignal for Ruby gem 2.4.0 and AppSignal for Elixir package 1.4.0. It currently does not support the host metrics feature. The following system dependencies are required for FreeBSD Linux distributions:

pkg install gcc gmake openssl-devel

# Dependencies for the AppSignal for Node.js package version 2.3.4 or newer, the supported Python versions are those between Python 3.7 and Python 3.10.
# Dependencies for the AppSignal for Node.js package version 2.3.3 or below, the supported Python versions are those between Python 3.5 and Python 3.8.
pkg install python3

macOS

macOS (OS X) 10.14.x and up is supported by AppSignal for Ruby, Elixir & Node.js. It currently does not support the host metrics feature. Please make sure Xcode is installed with the command line build tools.

xcode-select --install

# Dependencies for the AppSignal for Node.js package version 2.3.4 or newer, the supported Python versions are those between Python 3.7 and Python 3.10.
# Dependencies for the AppSignal for Node.js package version 2.3.3 or below, the supported Python versions are those between Python 3.5 and Python 3.8.
brew install python@3

Microsoft Windows

We currently have no plans to support the Microsoft Windows Operating System. We do try to make the AppSignal libraries installable on Microsoft Windows without any errors or build issues so that the app it’s installed in continues to operate. If you use Microsoft Windows and would like us to support it, send us an e-mail.

Ruby

To install the AppSignal Ruby gem on Microsoft Windows, make sure you have the RubyInstaller DevKit installed before installing AppSignal. Otherwise there will be the following error during installation of our C-extension. We will not install the C-extension on Microsoft Windows, but the Ruby installation detects it’s part of the gem and will not continue without the DevKit.

$ gem install appsignal
Fetching appsignal 2.2.1
Installing appsignal 2.2.1 with native extensions
Gem::InstallError: The 'appsignal' native gem requires installed build tools.
Please update your PATH to include build tools or download the DevKit
from 'http://rubyinstaller.org/downloads' and follow the instructions
at 'http://github.com/oneclick/rubyinstaller/wiki/Development-Kit'

Microsoft Windows Subsystem for Linux

We do not provide support for the Microsoft Windows Subsystem for Linux.

The Microsoft Windows Subsystem for Linux (WSL) is a layer between Microsoft Windows and a Linux distribution. This allows users to run certain GNU/Linux distributions, that are available in the Microsoft Store, on their Microsoft Windows computer. Running an app on WSL using an AppSignal integration will not cause any errors or build issues, as described in the Microsoft Windows section. Running AppSignal on WSL will work as well as the WSL supports it. Follow the steps for your Linux distribution on this page in the WSL environment to properly install the AppSignal dependencies, before installing AppSignal in your app. In our testing using the Ubuntu WSL, we’ve found that most AppSignal features will work, but we can’t say how accurate the information gathered from it is. Some small differences between WSL’s implementation and our Linux test setups, may cause odd behavior or inaccurately reporting of metrics. We do not actively test against WSL and cannot guarantee its successful operation. We do not provide support for AppSignal on the WSL. Not all AppSignal features will work on the WSL system, in our testing we’ve confirmed host metrics for disks (usage and IO) do not work. Use the WSL system to test AppSignal’s integration with your app in a development environment, but not do not use this setup in a production environment. Always test your app using AppSignal on a staging environment with a similar environment (Operating System) to the app’s production environment first.

​Support table

​Integrations

​Components

​Linux

​Supported versions

​Musl build override

​Linux ARM build override

​Alpine Linux

​Ruby

​Elixir

​Node.js

​CentOS

​Debian / Ubuntu

​Fedora

​FreeBSD

​macOS

​Microsoft Windows

​Ruby

​Microsoft Windows Subsystem for Linux

Support table

Integrations

Components

Linux

Supported versions

Musl build override

Linux ARM build override

Alpine Linux

Ruby

Elixir

Node.js

CentOS

Debian / Ubuntu

Fedora

FreeBSD

macOS

Microsoft Windows

Ruby

Microsoft Windows Subsystem for Linux