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

# Configuring Applications

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

<Tip>
  Read more information about AppSignal integration configuration in your app in
  our [configuration section][config topic].
</Tip>

## 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](/ruby/configuration/options#option-log_level), [Elixir](/elixir/configuration/options#option-log_level), [Node.js](/nodejs/3.x/configuration/options#option-loglevel) and [Python](/python/configuration/options#option-log_level) applications.

We'll use the `namespace` option as an example for [Front-end JavaScript applications](/front-end/configuration).

## 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:](#file-based-configuration)
  <br />A config file where the AppSignal integration reads the AppSignal
  configuration.
* [System Environment Variable Configuration:][env]
  <br />
  Environment variables are set on the host system (server) on the parent
  process that starts your application.
  <br /> **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.

<Tip>
  Make sure to use the "Config file key" value from the config options table as
  the config key. This key is either a snake\_cased (Ruby, Elixir, Python) or
  camelCased string (Node, Front-End JavaScript).
</Tip>

Config options for:

* [Ruby](/ruby/configuration/options)
* [Elixir](/elixir/configuration/options)
* [Node.js](/nodejs/3.x/configuration/options)
* [Python](/python/configuration/options)
* [Front-end Javascript](/front-end/configuration/)
* [Go](/go/configuration/options)

<Warning>
  Make sure to not check-in any sensitive configuration values, such as the Push
  API key into a source-control management system like Git, unless they are
  encrypted.
</Warning>

### 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][env].

<Tip>
  The `config/appsignal.yml` file is a YAML (Yet Another Markup Language) file.
  and is interpreted as an ERB (Embeded Ruby) template, Please see the [Ruby
  Configuration][ruby config] documentation for more details on how the YAML
  configuration works.
</Tip>

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

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

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:

<CodeGroup>
  ```yaml YAML theme={null}
  # 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...
  ```
</CodeGroup>

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

#### Read More:

* [Ruby Integration Configuration Topic][ruby config]
* [Ruby Integration Configuration Load Order Details](/ruby/configuration/load-order)

### 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][env] 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:

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

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:

<CodeGroup>
  ```elixir Elixir theme={null}
  # Example: config/dev.exs
  config :appsignal, :config,
    log_level: "debug" # This only sets the log_level to debug for the "dev" environment
  ```
</CodeGroup>

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

#### Read More

* [Elixir Integration Configuration Topic](/elixir/configuration/)
* [Elixir Integration Configuration Load Order Details](/elixir/configuration/load-order)

### 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][env] 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.

<CodeGroup>
  ```javascript Node.js theme={null}
  // 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 };
  ```
</CodeGroup>

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`

<CodeGroup>
  ```javascript Node.js theme={null}
  // 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
  });
  ```
</CodeGroup>

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 file like in the example below:

<CodeGroup>
  ```javascript Node.js theme={null}
  // 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
  ```
</CodeGroup>

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

#### Read More

* [Node.js Integration Configuration][nodejs config]
* [Node.js Integration Configuration Load Order](/nodejs/3.x/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][env].

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.

<CodeGroup>
  ```python Python theme={null}
  # __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",
  )
  ```
</CodeGroup>

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.

<CodeGroup>
  ```python Python theme={null}
  # __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,
  )
  ```
</CodeGroup>

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

<CodeGroup>
  ```python Python theme={null}
  # __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)
  ```
</CodeGroup>

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

#### Read More:

* [Python Integration Configuration Topic][python config]
* [Python Integration Configuration Load Order Details](/python/configuration/load-order)

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

<CodeGroup>
  ```javascript JavaScript theme={null}
  // 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 };
  ```
</CodeGroup>

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:

<CodeGroup>
  ```javascript JavaScript theme={null}
  // 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
  ```
</CodeGroup>

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](/front-end/configuration/)

## System Environment Variable Configuration

<Warning>
  This configuration method is not available for Front-end JavaScript.
</Warning>

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][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][file] 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.

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

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.

<Note>
  When using system environment variable based configuration, make sure to use
  the "System environment key" value from the config options table as the config
  key. This key is always is capitalized\* snake case, like this:
  `EXAMPLE_OF_A_CONFIG_KEY`

  <br />

  ***Fun Fact:** this is also known as SCREAMING\_SNAKE\_CASE 🐍*
</Note>

## Completing The Configuration

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][contact], and we'll help you out! To help us debug your issue quicker, we recommend sending us a [diagnose report](/support/debugging#diagnose) from your application's host.

## Further Reading

Read more about configuration in our [Application Configuration][config topic] documentation.

[config topic]: /application/configuration.html

[contact]: mailto:support@appsignal.com

[env]: #system-environment-variable-configuration

[file]: #file-based-configuration

[nodejs config]: /nodejs/3.x/configuration/

[ruby config]: /ruby/configuration/

[python config]: /python/configuration/