DOCSEARCHbyAlgolia
Submit Docs

AppSignal Ruby

repository·main·Indexed 42 days ago

https://github.com/appsignal/appsignal-ruby

An APM (Application Performance Monitoring) tool for Ruby applications that collects exceptions, performance data, and metrics. It provides automatic monitoring for frameworks like Ruby on Rails, Sinatra, and Padrino, as well as background job processors like Sidekiq and Resque. Features include custom instrumentation via Appsignal.instrument, manual error reporting with Appsignal.report_error, and a CLI for installation, diagnostics, and demonstrations.

Tokens
4.7K
Snippets
25
Records
30
Agent score
51%

What's inside AppSignal

  1. What is the AppSignal OpenTelemetry gem?

    main
    The appsignal-opentelemetry gem is a companion gem for the main appsignal Ruby gem. It does not provide runtime functionality itself; instead, it acts as a dependency manager that ensures the correct versions of OpenTelemetry gems are installed to support AppSignal's collector mode. Its version is kept in lockstep with the appsignal gem to ensure compatibility.

  2. Install the AppSignal OpenTelemetry gem

    main

    To enable AppSignal's collector mode, add the appsignal-opentelemetry gem to your Gemfile alongside the main appsignal gem. This gem manages the necessary OpenTelemetry dependencies required for AppSignal to run in collector mode.

    Requirements:

    • Ruby 3.1 or newer.
    • The version of appsignal-opentelemetry must match the version of the appsignal gem (e.g., appsignal-opentelemetry 4.10.3 for appsignal 4.10.3).
    gem "appsignal"
gem "appsignal-opentelemetry"

  3. Install AppSignal in your Ruby application

    main

    To install AppSignal, first add the appsignal gem to your Gemfile and run bundle install. Then, use the appsignal install command with your Push API key to run the installation wizard, which will guide you through the setup process.

    Note that depending on your framework (e.g., Rails, Sinatra) or other gems (e.g., Sidekiq), some manual integration steps may be required as indicated by the wizard.

    # Gemfile
gem "appsignal"
    appsignal install [push api key]

  4. Sidekiq instrumentation metrics

    main

    AppSignal automatically instruments Sidekiq to provide visibility into your background job processing. It tracks several key metrics using gauges, which are categorized under the sidekiq_ prefix.

    Redis Metrics

    • sidekiq_connection_count: Number of connected clients to Redis.
    • sidekiq_memory_usage: Redis memory usage.
    • sidekiq_memory_usage_rss: Redis memory usage (RSS).

    Sidekiq Stats

    • sidekiq_worker_count: Number of active workers.
    • sidekiq_process_count: Number of Sidekiq processes.
    • sidekiq_job_count: Tracks jobs by status, including:
      • :processed (via delta tracking)
      • :failed (via delta tracking)
      • :died (via delta tracking)
      • :retry_queue (current retry size)
      • :scheduled (current scheduled size)
      • :enqueued (current enqueued size)

    Queue Metrics

    For every queue in Sidekiq, AppSignal tracks:

    • sidekiq_queue_length: The number of jobs currently in the queue.
    • sidekiq_queue_latency: The latency of the queue (converted from seconds to milliseconds).

    Note: All metrics include a hostname tag, which defaults to the Redis server hostname unless configured otherwise via the probe configuration.

  5. Configure AppSignal using the DSL

    main

    You can customize AppSignal's behavior using the Appsignal.configure method. This method accepts an optional environment parameter (e.g., :production) and a block that provides a configuration DSL.

    Important Notes:

    • Configuration must be done before calling Appsignal.start. Once started, configuration changes are ignored.
    • If a config/appsignal.rb file exists, it is preferred over config/appsignal.yml.
    • You can specify a custom root_path if your configuration files are not in the standard location.
    # Configure for a specific environment
Appsignal.configure(:production) do |config|
  config.path = "/the/app/path"
  config.active = true
  config.push_api_key = "YOUR_API_KEY"
  config.ignore_actions = ["/ping"]
  config.request_headers << "MY_CUSTOM_HEADER"
end

# Start the integration after configuration
Appsignal.start

  6. Use the AppSignal CLI

    main

    The appsignal command-line interface provides tools for running demonstrations, diagnosing your installation, and performing automated installations.

    Basic usage follows the pattern: appsignal <command> [options]

    Available commands are:

    • demo: Runs a demonstration of AppSignal features.
    • diagnose: Checks your current AppSignal configuration and environment for issues.
    • install: Handles the installation process.

    To see all available commands and global options, run appsignal -h or appsignal --help.

    appsignal <command> [options]

  7. Start the AppSignal integration

    main

    To begin monitoring your application, call Appsignal.start. This method initializes the AppSignal agent, loads the configuration (either from config/appsignal.rb, config/appsignal.yml, or environment variables), and starts the instrumentation hooks.

    For pure Ruby applications or non-automatic integrations, calling .start is required. For automatic integrations (like Rails), AppSignal may start itself, but calling it explicitly ensures the agent is active.

    Appsignal.start

  8. Run AppSignal diagnostics via CLI

    main

    The appsignal diagnose command is a diagnostic tool used to validate your local AppSignal configuration and ensure the agent can run correctly on your host system. It checks for valid configuration, API key connectivity, system path permissions, and provides version information for both the Ruby gem and the AppSignal agent.

    What it checks:

    • Host System Compatibility: Architecture, OS, Ruby version, and whether it's running in a container or on Heroku.
    • Installation Status: Details about how the extension was installed (download URL, checksum, build flags, etc.).
    • Configuration: Validates the active configuration and shows which sources (e.g., file, env, dsl) provided each setting.
    • Agent Health: Checks if the agent is started, the logger is active, and if the working directory/lock paths are writable.
    • API Connectivity: Validates the Push API key by attempting to communicate with AppSignal servers.
    • File System: Verifies that required system paths exist and are writable by the current process.

    Exit Codes:

    • 0: Command finished successfully.
    • 1: Command failed to finish.

    For more detailed information, see the AppSignal diagnose documentation.

    # Basic usage
appsignal diagnose

# Run for a specific environment (e.g., production)
appsignal diagnose --environment=production

# Automatically send the diagnostics report to AppSignal without a prompt
appsignal diagnose --send-report

# Run without prompting and without sending the report
appsignal diagnose --no-send-report

  9. Install and configure AppSignal via the CLI

    main

    The AppSignal installer automates the setup process for various Ruby frameworks. It validates your Push API key, detects your framework (Rails, Sinatra, Padrino, Grape, or Hanami), and offers three configuration methods:

    1. Ruby config file: Writes a configuration to config/appsignal.rb.
    2. YAML config file: Writes a legacy configuration to config/appsignal.yml.
    3. Environment variables: Provides the necessary export commands for your shell.

    Note for Windows users: The AppSignal agent does not currently work on Microsoft Windows. You should push your changes to a staging or production environment for monitoring to work.

  11. Add custom tags to requests

    main

    Use Appsignal.add_tags to attach metadata to your requests. This helps identify common factors (like user IDs or locales) associated with errors or performance issues.

    Appsignal.add_tags(
  :user => current_user.id,
  :locale => I18n.locale
)

  12. Use custom instrumentation with Appsignal.instrument

    main

    For fine-grained performance monitoring, use Appsignal.instrument. You can wrap code blocks to track execution time and provide context.

    • Simple instrumentation: Wrap a block of code with a name and an optional description.
    • Database/Query instrumentation: Pass a SQL string as the third argument to track specific queries.
    • Nested instrumentation: You can nest Appsignal.instrument calls to see a hierarchical view of execution in AppSignal.
    # Simple instrumentation
Appsignal.instrument("array_to_hash.expensive_logic", "Complex calculations") do
  array = [["a", 1], ["b", 2], ["c", 3]]
  Hash[array]
end

# Add the query that you're monitoring
sql = "SELECT * FROM posts ORDER BY created_at DESC LIMIT 1"
Appsignal.instrument("fetch.custom_database", "Fetch latest post", sql) do
  # ...
end

# Nested instrumentation calls are also supported!
Appsignal.instrument("fetch.custom_database", "Fetch current user") do
  # ...

  Appsignal.instrument("write.custom_database", "Write user update") do
    # ...
  end
end