Passer au contenu principal
La configuration. Importante, car sans elle la gem Ruby AppSignal ne saura pas quelle application elle instrumente ou dans quel environnement. Dans cette rubrique, nous expliquerons comment configurer AppSignal, ce qui peut être configuré dans la gem Ruby, quelle est la configuration minimale nécessaire et comment la configuration est chargée.

Configuration minimale requise

Pour que les applications signalent des données à AppSignal, la configuration suivante est requise. Toute autre configuration est facultative. Pour les applications Rails, vous n’avez pas besoin de configurer le nom de votre application, AppSignal utilisera le nom de votre application par défaut. Si vous utilisez un framework qui prend en compte les environnements et qui est pris en charge par la gem AppSignal, l’environnement est détecté automatiquement.
# config/appsignal.rb
Appsignal.configure do |config|
  config.activate_if_environment(:development, :staging, :production)
  config.name = "My app"
  config.push_api_key = "1234-1234-1234"
end

Méthodes de configuration

Plusieurs méthodes de configuration différentes sont disponibles dans notre gem Ruby. Pour voir dans quel ordre elles sont chargées et quelle méthode de configuration remplace les valeurs des autres sources, consultez notre page ordre de chargement de la configuration.

Fichier de configuration Ruby

La gem Ruby AppSignal peut être configurée à l’aide d’un fichier de configuration Ruby. Lorsqu’elle est sélectionnée, l’installateur crée automatiquement un fichier config/appsignal.rb. Ce fichier inclut les paramètres de configuration par défaut qui peuvent être personnalisés pour répondre aux besoins spécifiques de votre application. Ce fichier de configuration est lu lorsque Appsignal.start est appelé, ce qui est fait automatiquement pour la plupart de nos intégrations. Veuillez lire les instructions d’intégration d’AppSignal si Appsignal.start n’est pas appelé automatiquement. Le fichier de configuration configure notre gem Ruby à l’aide de l’assistant Appsignal.configure. Veuillez lire la section l’assistant Appsignal.configure pour plus de détails sur la façon de l’utiliser. Le fichier de configuration YAML ne sera pas lu lorsque ce fichier est présent.
Appsignal.configure do |config|
  # Enable AppSignal for the following environments
  config.activate_if_environment(:development, :staging, :production)

  # Ignore this action for all environments
  config.ignore_actions << "My global action"

  # Ignore this action for only the production environment
  if config.env?(:production)
    config.ignore_actions << "My production action"
  end

  # Ignore this action for only the staging environment
  if config.env?(:staging)
    config.ignore_actions << "My staging action"
  end
end

Assistant Appsignal.configure

L’assistant Appsignal.configure peut être utilisé pour configurer AppSignal à l’aide de code Ruby. Le fichier de configuration Ruby utilise cet assistant et il peut également être utilisé directement dans votre application. Si votre application utilise Appsignal.configure en dehors du fichier config/appsignal.rb, comme un initializer Rails, veuillez lire cette section sur les différences de comportement que cela implique. Définissez les options de configuration à l’intérieur du bloc Appsignal.configure en appelant les méthodes d’écriture sur l’objet config. Les options de configuration peuvent être définies à l’aide de la « Config file key » indiquée pour les options de configuration. Par exemple, l’option send_params peut être définie avec : config.send_params = false.
# Some examples on how to configure config options
Appsignal.configure do |config|
  # Enable AppSignal for the following environments
  config.activate_if_environment(:development, :staging, :production)

  # Configure String config options
  config.name = "My app name"
  # Read a value from an environment variable
  config.hostname = ENV.fetch("HOSTNAME", "default hostname value")

  # Append values to Array config options
  config.ignore_actions += ["My ignored action", "My other ignored action"]
  config.request_headers << "MY_HTTP_HEADER"

  # Configure Boolean config options
  config.send_params = true
  config.enable_host_metrics = false
end
Lisez le reste de cette section pour plus de détails sur le fonctionnement de l’assistant Appsignal.configure et sur les autres assistants dont il dispose.

Options de configuration de type String

Les options de configuration de type String peuvent être définies à l’aide de String et de Symbol. Lorsqu’ils sont définis, nous convertirons les Symbols en Strings.
Appsignal.configure do |config|
  config.activejob_report_errors = :discard

  config.activejob_report_errors
  # => "discard"
end

Options de configuration de type Array

Les options de configuration de type Array peuvent être modifiées comme un tableau normal :
  • Utilisez une affectation pour remplacer les valeurs par défaut et les valeurs précédemment lues depuis les variables d’environnement.
    • Par exemple : config.array_option = ["value 1", "value 2"]
    • Valeur de l’option : ["value 1", "value 2"]
  • Utilisez l’opérateur d’affectation d’addition += pour fusionner un nouveau tableau de valeurs avec les valeurs par défaut et les valeurs précédemment lues depuis les variables d’environnement.
    • Par exemple : config.array_option += ["value 1", "value 2"]
    • Valeur de l’option : ["DUMMY default value", "value 1", "value 2"]
  • Utilisez l’opérateur d’ajout << pour ajouter une seule valeur à la liste des valeurs par défaut et des valeurs précédemment lues depuis les variables d’environnement.
    • Par exemple : config.array_option << "value 1"
    • Valeur de l’option : ["DUMMY default value", "value 1"]

Détection automatique de l’environnement

La gem Ruby AppSignal détecte automatiquement l’environnement de l’application. Nous nous intégrons avec des gems telles que Rails, Sinatra, Rack, et d’autres pour détecter dans quel environnement l’application a démarré. Pour cette raison, il ne devrait pas être nécessaire de configurer l’environnement manuellement. Si vous devez configurer manuellement l’environnement de l’application, passez le nom de l’environnement comme premier argument à l’assistant Appsignal.configure. Cet argument remplacera la valeur de la variable d’environnement APPSIGNAL_APP_ENV et la détection automatique de l’environnement.
# Configure the application environment explicitly to be "production"
Appsignal.configure(:production) do |config|
  # Some config
end

Assistant activate_if_environment

L’assistant Appsignal.configure dispose d’un assistant pour configurer quels environnements doivent être actifs et signaler des données à AppSignal.com. Appelez activate_if_environment avec une liste d’environnements (Strings et/ou Symbols). AppSignal détecte l’environnement lorsque l’assistant Appsignal.configure est appelé sans argument d’environnement. Il vérifie ensuite si l’environnement correspond à l’une des valeurs données, et si c’est le cas, définit l’option de configuration active sur true.
Appsignal.configure do |config|
  # Enable AppSignal for the following environments
  config.activate_if_environment(:development, :staging, :production)
end
L’assistant activate_if_environment est un assistant pratique pour éviter aux applications d’ajouter leurs propres vérifications sur les conditions d’activation d’AppSignal, comme :
Appsignal.configure do |config|
  # Example of a manual check for which environments AppSignal should be active
  config.active = Rails.env.development? || Rails.env.staging? || Rails.env.production?
end

Assistant env?

L’assistant Appsignal.configure dispose d’un assistant pour vérifier quel environnement AppSignal a détecté. Utilisez cet assistant pour vérifier quel environnement est actif afin de définir les options de configuration qui ne doivent s’appliquer qu’à cet environnement. Appelez l’assistant env? avec un nom d’environnement (String ou Symbol), et il renverra true si le nom de l’environnement correspond à l’environnement actuellement actif.
Appsignal.configure do |config|
  # Add this configuration only for the staging environment
  if config.env?(:staging)
    config.ignore_actions << "My staging action"
  end
end

Utilisation de l’assistant Appsignal.configure dans votre application

Nous recommandons de configurer la gem Ruby AppSignal à l’aide du fichier de configuration Ruby situé dans config/appsignal.rb. Si vous préférez un initializer Rails ou une configuration inline, veuillez lire cette section pour les changements de comportement que cela implique. Si l’assistant Appsignal.configure est appelé avant que le fichier de configuration Ruby config/appsignal.rb ne soit lu lorsque Appsignal.start est appelé, il ne lira pas le fichier de configuration Ruby. Dans les applications Rails, assurez-vous de configurer la gem AppSignal pour qu’elle démarre après l’initialisation de Rails, sinon la configuration définie avec Appsignal.configure est ignorée lorsqu’elle est appelée dans un initializer Rails comme config/initializers/appsignal.rb.
Dans la version 3.12 et plus récentes de la gem Ruby, si un fichier de configuration YAML est présent, il sera lu lorsque Appsignal.configure est appelé dans un initializer Rails ou en ligne dans une application. Ce comportement est obsolète. Veuillez déplacer toute la configuration vers l’assistant Appsignal.configure.Nous supprimerons ce comportement dans la prochaine version majeure de la gem Ruby.
Exemple d’initializer Rails :
# Example file: config/initializers/appsignal.rb

# WARNING: In this example the `config/appsignal.rb` config file is not read!
Appsignal.configure do |config|
  # Set some config
end
Exemple de configuration inline :
# Example file: app.rb
require "appsignal"
require "web_framework"

# WARNING: In this example the `config/appsignal.rb` config file is not read!
Appsignal.configure do |config|
  # Set some config
end
Appsignal.start

run WebFramework.app

Variables d’environnement système

AppSignal peut également être configuré à l’aide des variables d’environnement système sur l’hôte de l’application surveillée par AppSignal. C’est courant sur des plateformes telles que Heroku. Assurez-vous que ces variables d’environnement sont configurées de manière compatible avec votre système d’exploitation et que les valeurs sont chargées avant le démarrage de votre application avec AppSignal.
export APPSIGNAL_APP_NAME="My app"

Fichier de configuration YAML

Cette méthode de configuration est une méthode héritée et sera supprimée dans la prochaine version majeure de la gem Ruby.Veuillez utiliser le fichier de configuration Ruby à la place.
La gem Ruby AppSignal peut être configurée avec un fichier de configuration YAML. Lors de l’installation, la gem Ruby créera un fichier config/appsignal.yml, si vous le sélectionnez. Dans ce fichier, une configuration par défaut est fournie et peut être modifiée pour répondre aux besoins de votre application. Ce fichier config/appsignal.yml prend en charge les balises ERB afin que les variables d’environnement système puissent également être chargées dans ce fichier. Les exemples de configuration config/appsignal.yml présentés pour les options de configuration utiliseront l’ancre YAML default. L’installateur AppSignal créera un fichier config/appsignal.yml avec cette ancre par défaut. Si elle n’est pas présente, assurez-vous d’ajouter l’option de configuration à l’environnement approprié.
# config/appsignal.yml
# Define the "defaults" anchor
default: &defaults
  name: "My app"
  # Supports ERB
  push_api_key: "<%= ENV['APPSIGNAL_PUSH_API_KEY'] %>"

production:
  # Loads the defaults in the production environment by referencing the anchor
  <<: *defaults
  # production environment specific configuration
  active: true

Plusieurs environnements d’application

Plusieurs environnements d’application peuvent être configurés dans ce fichier à l’aide de clés au niveau racine.
# Example: config/appsignal.yml
development: # Development app environment
  active: true

production: # Production app environment
  active: true

test: # Testing app environment
  active: false # Disabled for test environment
Pour éviter d’avoir à répéter la configuration pour chaque environnement d’application, nous pouvons utiliser les ancres YAML pour étendre les objets YAML.
# Example: config/appsignal.yml
default: &defaults
  active: true

development: # Development app environment
  <<: *defaults

production: # Production app environment
  <<: *defaults

test: # Testing app environment
  <<: *defaults
  active: false # Overwrites the inherited active config option from "defaults"
Il n’est pas possible de configurer uniquement une ancre defaults et de la faire s’appliquer automatiquement à tous les environnements. Chaque environnement doit être configuré dans le fichier YAML avec une clé au niveau racine et étendre cette ancre defaults.

Exemple de fichier de configuration YAML

Voici un exemple de fichier de configuration appsignal.yml. Nous vous recommandons de n’ajouter à votre fichier de configuration que la configuration dont vous avez besoin. Pour la liste complète des options, veuillez consulter la page options de configuration.
# config/appsignal.yml
default: &defaults
  # Your Push API Key, it is possible to set this dynamically using ERB. Required
  push_api_key: "<%= ENV['APPSIGNAL_PUSH_API_KEY'] %>"

  # Your app's name as reported on AppSignal.com. Required
  name: "My App"

  # Your server's hostname. Optional, auto detected
  hostname: "frontend1.myapp.com"

  # Add default instrumentation of net/http. Default: true
  instrument_net_http: true

  # Skip session data, if it contains private information. Default: false
  skip_session_data: true

  # Ignore these errors (Optional)
  ignore_errors:
    - SystemExit

  # Ignore these actions, used by our Loadbalancer. Optional
  ignore_actions:
    - IsUpController#index

  # Enable allocation tracking for memory metrics. Default: true
  enable_allocation_tracking: true

# Configuration per environment, leave out an environment or set active
# to false to not push metrics for that environment.
development:
  <<: *defaults
  active: true
  # Set the severity level of AppSignal's internal logger. Optional
  # Supported values are error, warning, info, debug, trace
  log_level: debug

staging:
  <<: *defaults
  # Configure AppSignal to be active for this environment. Required
  active: true

production:
  <<: *defaults
  # Configure AppSignal to be active for this environment. Required
  active: true

  # Set different path for the log file. Optional, auto detected
  log_path: "/home/my_app/app/shared/log"

  # Set AppSignal working dir. Optional, auto detected
  working_directory_path: "/tmp/appsignal"

  # When it's not possible to connect to the outside world without a proxy.
  # Optional
  http_proxy: "proxy.mydomain.com:8080"