Zum Hauptinhalt springen
Konfiguration. Wichtig, denn ohne sie weiß das AppSignal Ruby-Gem nicht, welche Anwendung es instrumentiert oder in welcher Umgebung. In diesem Thema erklären wir, wie Sie AppSignal konfigurieren, was im Ruby-Gem konfiguriert werden kann, was die minimal benötigte Konfiguration ist und wie die Konfiguration geladen wird.

Minimal erforderliche Konfiguration

Damit Anwendungen Daten an AppSignal melden, ist die folgende Konfiguration erforderlich. Alle weiteren Konfigurationen sind optional. Für Rails-Apps müssen Sie Ihren Anwendungsnamen nicht konfigurieren; AppSignal verwendet standardmäßig den Namen Ihrer Anwendung. Wenn Sie ein Framework verwenden, das Umgebungen kennt und vom AppSignal-Gem unterstützt wird, wird die Umgebung automatisch erkannt.
# 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

Konfigurationsmethoden

In unserem Ruby-Gem stehen mehrere unterschiedliche Konfigurationsmethoden zur Verfügung. Um zu sehen, in welcher Reihenfolge sie geladen werden und welche Konfigurationsmethode Werte aus anderen Quellen überschreibt, lesen Sie unsere Seite zur Ladereihenfolge der Konfiguration.

Ruby-Konfigurationsdatei

Das AppSignal Ruby-Gem kann mit einer Ruby-Konfigurationsdatei konfiguriert werden. Bei Auswahl erstellt der Installer automatisch eine config/appsignal.rb-Datei. Diese Datei enthält Standard-Konfigurationseinstellungen, die an die spezifischen Bedürfnisse Ihrer Anwendung angepasst werden können. Diese Konfigurationsdatei wird gelesen, wenn Appsignal.start aufgerufen wird, was bei den meisten unserer Integrationen automatisch geschieht. Bitte lesen Sie die Anweisungen zur Integration von AppSignal, wenn Appsignal.start nicht automatisch aufgerufen wird. Die Konfigurationsdatei konfiguriert unser Ruby-Gem mit dem Appsignal.configure-Helper. Lesen Sie den Abschnitt Der Appsignal.configure-Helper für weitere Details zur Verwendung. Die YAML-Konfigurationsdatei wird nicht gelesen, wenn diese Datei vorhanden ist.
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

Appsignal.configure-Helper

Der Appsignal.configure-Helper kann verwendet werden, um AppSignal mit Ruby-Code zu konfigurieren. Die Ruby-Konfigurationsdatei verwendet diesen Helper, und er kann auch direkt in Ihrer Anwendung verwendet werden. Wenn Ihre App Appsignal.configure außerhalb der config/appsignal.rb-Datei verwendet, etwa in einem Rails-Initializer, lesen Sie bitte diesen Abschnitt über die Unterschiede im Verhalten. Setzen Sie Konfigurationsoptionen innerhalb des Appsignal.configure-Blocks, indem Sie die Schreibmethoden auf dem config-Objekt aufrufen. Konfigurationsoptionen können mit dem für die Konfigurationsoption aufgeführten “Config file key” gesetzt werden. Beispielsweise kann die send_params-Option so gesetzt werden: 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
Lesen Sie den Rest dieses Abschnitts für weitere Details zur Funktionsweise des Appsignal.configure-Helpers und welche weiteren Helper er hat.

String-Konfigurationsoptionen

Konfigurationsoptionen vom Typ String können sowohl mit Strings als auch mit Symbols gesetzt werden. Beim Setzen wandeln wir Symbols in Strings um.
Appsignal.configure do |config|
  config.activejob_report_errors = :discard

  config.activejob_report_errors
  # => "discard"
end

Array-Konfigurationsoptionen

Konfigurationsoptionen vom Typ Array können wie ein normales Array modifiziert werden:
  • Verwenden Sie eine Zuweisung, um Standardwerte und zuvor aus Umgebungsvariablen gelesene Werte zu überschreiben.
    • Beispiel: config.array_option = ["value 1", "value 2"]
    • Optionswert: ["value 1", "value 2"]
  • Verwenden Sie den Additionsoperator +=, um ein neues Array von Werten mit den Standardwerten und zuvor aus Umgebungsvariablen gelesenen Werten zusammenzuführen.
    • Beispiel: config.array_option += ["value 1", "value 2"]
    • Optionswert: ["DUMMY default value", "value 1", "value 2"]
  • Verwenden Sie den Anhänge-Operator <<, um einen einzelnen Wert an die Liste der Standardwerte und der zuvor aus Umgebungsvariablen gelesenen Werte anzuhängen.
    • Beispiel: config.array_option << "value 1"
    • Optionswert: ["DUMMY default value", "value 1"]

Automatische Erkennung der Umgebung

Das AppSignal Ruby-Gem erkennt die Umgebung der Anwendung automatisch. Wir integrieren uns mit Gems wie Rails, Sinatra, Rack und anderen, um zu erkennen, in welcher Umgebung die Anwendung gestartet wurde. Aus diesem Grund sollte es nicht erforderlich sein, die Umgebung manuell zu konfigurieren. Wenn Sie die Umgebung der Anwendung manuell konfigurieren müssen, übergeben Sie den Umgebungsnamen als erstes Argument an den Appsignal.configure-Helper. Dieses Argument überschreibt den Wert der Umgebungsvariable APPSIGNAL_APP_ENV und die automatische Umgebungserkennung.
# Configure the application environment explicitly to be "production"
Appsignal.configure(:production) do |config|
  # Some config
end

activate_if_environment-Helper

Der Appsignal.configure-Helper hat einen Helper, mit dem Sie konfigurieren können, welche Umgebungen aktiv sein und Daten an AppSignal.com melden sollen. Rufen Sie activate_if_environment mit einer Liste von Umgebungen auf (Strings und/oder Symbols). AppSignal erkennt die Umgebung, wenn der Appsignal.configure-Helper ohne Umgebungsargument aufgerufen wird. Es prüft dann, ob die Umgebung mit einem der angegebenen Werte übereinstimmt, und setzt in diesem Fall die active-Konfigurationsoption auf true.
Appsignal.configure do |config|
  # Enable AppSignal for the following environments
  config.activate_if_environment(:development, :staging, :production)
end
Der activate_if_environment-Helper ist ein Komfort-Helper, damit Anwendungen keine eigenen Prüfungen hinzufügen müssen, wann AppSignal aktiv sein soll, wie:
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

env?-Helper

Der Appsignal.configure-Helper hat einen Helper, um zu prüfen, welche Umgebung AppSignal erkannt hat. Verwenden Sie diesen Helper, um zu prüfen, welche Umgebung aktiv ist, und um Konfigurationsoptionen zu setzen, die nur für diese Umgebung gelten sollen. Rufen Sie den env?-Helper mit einem Umgebungsnamen (String oder Symbol) auf, und er gibt true zurück, wenn der Umgebungsname mit der aktuell aktiven Umgebung übereinstimmt.
Appsignal.configure do |config|
  # Add this configuration only for the staging environment
  if config.env?(:staging)
    config.ignore_actions << "My staging action"
  end
end

Verwendung des Appsignal.configure-Helpers in Ihrer Anwendung

Wir empfehlen, das AppSignal Ruby-Gem mit der Ruby-Konfigurationsdatei unter config/appsignal.rb zu konfigurieren. Falls ein Rails-Initializer oder eine Inline-Konfiguration bevorzugt wird, lesen Sie bitte diesen Abschnitt zu den daraus resultierenden Verhaltensänderungen. Wenn der Appsignal.configure-Helper aufgerufen wird, bevor die config/appsignal.rb Ruby-Konfigurationsdatei beim Aufruf von Appsignal.start gelesen wird, wird die Ruby-Konfigurationsdatei nicht gelesen. In Rails-Apps stellen Sie sicher, dass Sie das AppSignal-Gem so konfigurieren, dass es nach der Initialisierung von Rails startet, da andernfalls die mit Appsignal.configure gesetzte Konfiguration ignoriert wird, wenn sie in einem Rails-Initializer wie config/initializers/appsignal.rb aufgerufen wird.
In Ruby-Gem-Version 3.12 und neuer wird, wenn eine YAML-Konfigurationsdatei vorhanden ist, diese gelesen, wenn Appsignal.configure in einem Rails-Initializer oder inline in einer Anwendung aufgerufen wird. Dies ist veraltetes Verhalten. Bitte verschieben Sie die gesamte Konfiguration in den Appsignal.configure-Helper.Wir werden dieses Verhalten in der nächsten Major-Version des Ruby-Gems entfernen.
Beispiel für einen Rails-Initializer:
# 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
Beispiel für eine Inline-Konfiguration:
# 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

System-Umgebungsvariablen

AppSignal kann auch mit System-Umgebungsvariablen auf dem Host konfiguriert werden, auf dem die von AppSignal überwachte Anwendung läuft. Dies ist auf Plattformen wie Heroku üblich. Stellen Sie sicher, dass diese Umgebungsvariablen so konfiguriert sind, dass sie mit Ihrem Betriebssystem kompatibel sind, und dass die Werte geladen werden, bevor Ihre App mit AppSignal gestartet wird.
export APPSIGNAL_APP_NAME="My app"

YAML-Konfigurationsdatei

Diese Konfigurationsmethode ist eine Legacy-Methode und wird in der nächsten Major-Version des Ruby-Gems entfernt.Bitte verwenden Sie stattdessen die Ruby-Konfigurationsdatei.
Das AppSignal Ruby-Gem kann mit einer YAML-Konfigurationsdatei konfiguriert werden. Während der Installation erstellt das Ruby-Gem (falls ausgewählt) eine config/appsignal.yml-Datei. In dieser Datei wird eine Standardkonfiguration bereitgestellt, die an die Bedürfnisse Ihrer Anwendung angepasst werden kann. Diese config/appsignal.yml-Datei unterstützt ERB-Tags, sodass auch System-Umgebungsvariablen in dieser Datei geladen werden können. Die für Konfigurationsoptionen gezeigten config/appsignal.yml-Konfigurationsbeispiele verwenden den YAML-Anker default. Der AppSignal-Installer erstellt standardmäßig eine config/appsignal.yml-Datei mit diesem Anker. Falls nicht vorhanden, stellen Sie sicher, dass Sie die Konfigurationsoption zur korrekten Umgebung hinzufügen.
# 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

Mehrere App-Umgebungen

In dieser Datei können mehrere App-Umgebungen mit Schlüsseln auf Stammebene konfiguriert werden.
# 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
Um die Konfiguration nicht für jede App-Umgebung wiederholen zu müssen, können wir YAML-Anker verwenden, um YAML-Objekte zu erweitern.
# 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"
Es ist nicht möglich, nur einen defaults-Anker zu konfigurieren und ihn automatisch auf alle Umgebungen anwenden zu lassen. Jede Umgebung muss in der YAML-Datei mit einem Schlüssel auf Stammebene konfiguriert werden und von diesem defaults-Anker erben.

Beispiel einer YAML-Konfigurationsdatei

Hier ist ein Beispiel für eine appsignal.yml-Konfigurationsdatei. Es wird empfohlen, dass Sie nur die Konfiguration zu Ihrer Konfigurationsdatei hinzufügen, die Sie tatsächlich benötigen. Die vollständige Liste der Optionen finden Sie auf der Seite Konfigurationsoptionen.
# 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"