Configuring Applications

Welcome to our Configuration Guide. This guide will teach you how to add and modify configurations for your AppSignal integration.

Choose a Configuration Option

This guide will walk you through the steps necessary to configure your application to best suit your needs. There are, of course, multiple configuration options for your application, but since the implementation method for all options is identical, in this guide, we'll focus on the following configurations:

We'll be using the log_level option as an example for Ruby, Elixir, Node.js and Python applications.

We'll use the namespace option as an example for Front-end JavaScript applications.

Configuration Methods

There are multiple ways to configure your AppSignal integration, and integrations can vary depending on your application's language, but they all have the following configuration methods:

• File Based Configuration:
  A config file where the AppSignal integration reads the AppSignal configuration.
• System Environment Variable Configuration:
  Environment variables are set on the host system (server) on the parent process that starts your application. Note: This method is not available for front-end JavaScript integrations.
  Note: This method is not available for front-end JavaScript.

File Based Configuration

File-based configuration is the easiest way to configure your integration.

Some integrations create a config file during the installation of AppSignal in the app. In these config files, you can uniquely configure one or multiple application environments.

Config options for:

• Ruby
• Elixir
• Node.js
• Python
• Front-end Javascript

Ruby

When using the Ruby integration gem, it will create the config/appsignal.yml in your applications root folder, with basic configuration settings upon installation. If your application reports data to AppSignal without an appsignal.yml file, your application is most likely using system environment variables.

In the below example config file, two environments are defined, development and production - each has environment specific configuration options nested under them. Everything defined and nested within default applies to all environments, as long as default is included in the environment mapping.

We want to set the log_level to debug exclusively in our development environment; to do this, we've added log_level: "debug" in the development environment configuration (line 10).

# Example: config/appsignal.yml
default: &defaults # Shared configuration options for all environments
  active: true
  name: "My awesome app"
  push_api_key: "<YOUR PUSH API KEY>"
 
development: # Development environment
  <<: *defaults
  log_level: "debug" # This enables debug mode for only the development environment
 
production: # Production environment
  <<: *defaults

Remember, everything nested within default is applied to all environments, so to set the log_level to debug in all environments, we can instead nest the configuration under default, as done in line 6 of the below example code:

# Example: config/appsignal.yml
default: &defaults
  active: true
  name: "My awesome app"
  push_api_key: "<YOUR PUSH API KEY>"
  log_level: "debug" # This enables debug mode for all environments
  # Other AppSignal config...
 
development: # Development environment
  <<: *defaults
  # Other AppSignal config...
 
production: # Production environment
  <<: *defaults
  # Other AppSignal config...

Great, now you've learned how to configure AppSignal in your Ruby application!

Read More:

• Ruby Integration Configuration Topic
• Ruby Integration Configuration Load Order Details

Elixir

Upon installation, the Elixir integration creates a config/appsignal.exs (default location) file with basic configurations. If this file is not present but your application reports data to AppSignal, check any of the other .exs files in the config/ directory of your Elixir app. If no AppSignal configuration is present in any of the files, your application is likely using system environment variables as a configuration method instead.

To add a configuration option and have it apply to all your application's environments, add the config option to the config/appsignal.exs file, like on line 7 of the example below:

# Example: config/config.exs
config :appsignal, :config,
  active: true,
  name: "My awesome app",
  push_api_key: "<YOUR PUSH API KEY>",
  env: Mix.env,
  log_level: "debug" # This sets the log_level to debug for all environments

To only apply the config option to a single environment, add the AppSignal configuration to the environment's config file, located in the config/ directory.

In the example below, the log_level option has been added on line 3 of the development (or "dev") environment:

# Example: config/dev.exs
config :appsignal, :config,
  log_level: "debug" # This only sets the log_level to debug for the "dev" environment

Great, now you've learned how to configure AppSignal in your Elixir application!

Read More

• Elixir Integration Configuration Topic
• Elixir Integration Configuration Load Order Details

Node.js

After installation, you need to create an AppSignal config file to configure your application. If no file with AppSignal configuration is present, it is most likely using system environment variables as a configuration method instead.

To configure AppSignal for Node.js apps, we recommend creating an appsignal.js file with the AppSignal config in your application's root or src directory. Then require/import it from the app's code before any other packages are required or imported.

In the example below, there is an appsignal.js file in the root of the app directory. In this file, we'll add the logLevel config option.

// appsignal.js
const { Appsignal } = require("@appsignal/nodejs");
 
const appsignal = new Appsignal({
  active: true,
  name: "<YOUR APPLICATION NAME>",
  pushApiKey: "<YOUR API KEY>",
  logLevel: "debug", // Sets logLevel to debug for the Node.js environment
});
 
module.exports = { appsignal };

The config in the example above applies to the environment Node.js is running in (NODE_ENV, defaults to "development").

In Node.js there are many ways to create environment-specific configurations for AppSignal. If you are unsure how to do this within your own application, one method we recommend is using conditionals in your appsignal.js, such as in the example below where we specify debug for the production environment.

1. On line 4 - we only activate the AppSignal integration if the environment is production.
2. On line 8 - as in our previous code example we set the logLevel to debug

// appsignal.js
 
const appsignal = new Appsignal({
  active: process.env.NODE_ENV === "production"
  name: "<YOUR APPLICATION NAME>",
  pushApiKey: "<YOUR API KEY>",
  logLevel: "debug" // Sets logLevel to debug for the Node.js environment
});

Once your configuration is completed, you need to require appsignal.js at the very top of your app's main file. Your application's main file name may vary depending on how your application is structured. It is the file you use to start your Node application and is usually called index.js or app.js. Ensure AppSignal is required at the very top of the the file like in the example below:

// index.js
// Place this at the top
const { appsignal } = require("./appsignal"); // Update to the location used in the previous step
 
// Place your app code below this

Great, now you've learned how to configure AppSignal in your Node.js application!

Read More

• Node.js Integration Configuration
• Node.js Integration Configuration Load Order

Python

When using the Python integration installer, it will create the __appsignal__.py in your applications root folder, with basic configuration settings. Your application can also be configured using system environment variables.

To add a configuration option and have it apply to your development application environment, add the config option to the __appsignal__.py file, like in the example below.

# __appsignal__.py
from appsignal import Appsignal
 
appsignal = Appsignal(
    active=True,
    name="My awesome app",
    push_api_key="<YOUR PUSH API KEY>",
    environment="development",
    log_level="debug",
)

To configure AppSignal for Python for another environment, or apply the config to all to environments, configure the environment config option in the same way your app determines its environment (development/staging/production). This can be using a system environment variable or some other application specific method. In the example below we'll be using a system environment variable MY_APP_ENV to both set the app environment and only activate for the production environment.

# __appsignal__.py
import os
from appsignal import Appsignal
 
app_env = os.environ.get("MY_APP_ENV")
 
appsignal = Appsignal(
    active=app_env == "production",
    name="My awesome app",
    push_api_key="<YOUR PUSH API KEY>",
    environment=app_env,
)

If you want some config options to only apply to certain environments, create conditionals to fit your needs.

# __appsignal__.py
import os
from appsignal import Appsignal
 
app_env = os.environ.get("MY_APP_ENV")
 
options = {
    "active": app_env == "development",
    "name": "python/django4-celery",
    "environment": app_env,
}
if app_env == "development":
    options["log_level"] = "debug"
 
appsignal = Appsignal(**options)

Great, now you've learned how to configure AppSignal in your Python application!

Read More:

• Python Integration Configuration Topic
• Python Integration Configuration Load Order Details

Front-end JavaScript

To configure AppSignal for front-end JavaScript, we recommend creating an appsignal.js file with the AppSignal config in your project's root or src directory. Then require or import it from the app's code before any other packages are required or imported.

In the example below, there is an appsignal.js file in the root of the applications directory. On line 8 we've added the namespace config option.

// appsignal.js
import Appsignal from "@appsignal/javascript"; // For ES Module
const Appsignal = require("@appsignal/javascript").default; // For CommonJS module
 
const appsignal = new Appsignal({
  key: "<YOUR FRONTEND API KEY>",
  namespace: "frontend", // Configure the AppSignal namespace for front-end errors in this app
});
 
module.exports = { appsignal };

Once you're done with your application's config, you need to require appsignal.js the very top of your application's main file, like in the example below:

// index.js
// Place this at the top
const { appsignal } = require("./appsignal"); // Update to the location used in the previous step
 
// Place your app code below this

And that's it - you're ready to roll! Follow these simple steps for all future config option modifications.

Read More

• Front-end JavaScript Integration Configuration

System Environment Variable Configuration

System environment variables, or "environment variables" for short, are variables that are accessible by processes, and are inherited from the parent process who starts them. Instead of using a configuration file for configuration, it's possible to configure AppSignal using only environment variables. It is also possible to store config keys that contain sensitive data, such as the Push API key in an environment variable, and use config files for the rest of the config.

This configuration method is compatible with Ruby, Elixir, and Node.js applications.

Before moving on to the following example of setting environment variables via a shell, let's explain how environment variables work concerning shells and processes.

Environment variables can belong to a process such as a shell or your application. The command export FOO=BAR, for example, would set your shell's FOO environment variable to equal BAR. Environment variables are inherited between processes, so when that shell starts a new process, that process will also have any of the shell's environment variables.

When you launch a process in the shell (i.e., npm start) you can also provide more environment variables for only that process by assigning the variables like so: FOO=BAR npm start

For convenience, you may want to configure your shell to set certain environment variables when it starts, so that any processes started from that shell inherits those environment variables. If you're using the bash shell, the commands in the .bash_profile file in your home directory are executed when the shell is started. If using zsh, which is the default shell in macOS, the .zshenv file would be used instead to configure environment variables.

In the example file below, we export the environment variables that configure AppSignal's push API key and log level, so that when a new shell is started, the correct environment variables are accessible to your application, allowing it to communicate with AppSignal.

Config options set via environment variables apply to all application environments, however some config options are language specific. For example, the config option instrument_sequel only exists in the Ruby integration, because Sequel is a Ruby gem, and therefore setting the APPSIGNAL_INSTRUMENT_SEQUEL environment variable has no effect for other integrations.

# Bash shell example
export APPSIGNAL_PUSH_API_KEY=<YOUR PUSH API KEY>
export APPSIGNAL_LOG_LEVEL=debug # Sets log_level to debug for all environments.

There are several possible locations for files with environment variables configuration. Please choose the best option that suits your application, and be sure to reload your terminal shell after making any changes to ensure it has access to your updated variables.

• ~/.profile or ~/.bash_profile - User specific settings. Use this location to configure environment variables per user.
• /etc/profile - System-wide settings. If multiple users or apps use the same host machine, do not use this location.

Platform As A Service (PaaS) hosting providers like Heroku, do not provide a system for directly configuring environment variables in the shell. You can instead use their web interface or CLI to configure these environment variables.

Completing The Configuraiton

After changing your AppSignal configuration, your application needs to be restarted or deployed for the configuration changes to be detected by AppSignal.

Are configuration changes not being detected? Get in touch, and we'll help you out! To help us debug your issue quicker, we recommend sending us a diagnose report from your application's host.

Further Reading

Read more about configuration in our Application Configuration documentation.