appsignal 4.5.17 → 4.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b41543a5c8a4ab168f9e25cb08cb21cac1f2feab07e2ee94948cb3b5e4a93de
-  data.tar.gz: 27cd215ac772b9df1fd0851b0b7cbad6c201d273ddc9d416cf739b928c632c0a
+  metadata.gz: f788b7bfb3d2b44efa664bc031df2a2af56085daef2ff224144d6b06e96912ea
+  data.tar.gz: 8600017362cafa764b5ed3f8dbfc41e083b110bcc49374fc66a9a3583ca12f5a
 SHA512:
-  metadata.gz: 972b6a1e047559e8b5821e6e3749e25b22226f1a3064afbbe1d75f72d5f91882bcb2eee7dab8f7098a58c4419e272e0cb91e8b5ce74f94468f7942b96400502d
-  data.tar.gz: 257ffe63d397bd648fefbf055fd5955851a6a95f605f810c5e2fc6cb0aef5bc5584b34487a4d0625dec08e73f1fd77ca15840a5d2fbd5d669f3c4c0f482817de
+  metadata.gz: a22051b87cae3d4f9d93f34b0cc41765feba84b7eccf8842c178954bf6ba0dbe6977222646c860f0afdf83a26b61ca493728255113455aa1fe49e151604cfc66
+  data.tar.gz: 442959e2bb59a79878852cb1397b477b6100645f95a98a121ce0c83d6d8aea7cfb8d9e78a6ce8235d5482a625a3e4b19495b3da1ac0b3e9029ec0052801ae668

data/CHANGELOG.md

@@ -1,5 +1,38 @@
 # AppSignal for Ruby gem Changelog
 
+## 4.6.0
+
+_Published on 2025-07-29._
+
+### Added
+
+- Add Sorbet and RBS type signatures for the gem's public APIs. If your editor supports showing type signatures, they will now show up in for the AppSignal Ruby gem. (minor [9ed372fc](https://github.com/appsignal/appsignal-ruby/commit/9ed372fc7819eff2fd73aa287b4d0018e008d0da), [4c9118f7](https://github.com/appsignal/appsignal-ruby/commit/4c9118f7bf36475146ed9309e0511c176058efb6))
+- When a deployment tool (Capistrano, Hatchbox.io) provides the `REVISION` file in the deployed application, AppSignal will now use that to set the revision config. (minor [34e4aee5](https://github.com/appsignal/appsignal-ruby/commit/34e4aee5f3010f122501470bad06e02e7aef7ef2), [4c9118f7](https://github.com/appsignal/appsignal-ruby/commit/4c9118f7bf36475146ed9309e0511c176058efb6))
+
+### Changed
+
+- Improve the YARD documentation for public APIs. This will make the documentation clearer and more useful for developers using the Ruby gem. Private APIs have been hidden from the generated output. (patch [989dc495](https://github.com/appsignal/appsignal-ruby/commit/989dc495242a656278186e47b68e41fa785dbae2), [4c9118f7](https://github.com/appsignal/appsignal-ruby/commit/4c9118f7bf36475146ed9309e0511c176058efb6))
+- When an error occurs while initializing AppSignal or when running a probe, use the error log level to log the error's backtrace. (patch [390f4489](https://github.com/appsignal/appsignal-ruby/commit/390f448991e52904d993c2139f4b11642003c345), [385b0262](https://github.com/appsignal/appsignal-ruby/commit/385b0262d1001108bdac07a95b85e90bf6ccde5c), [178bafc2](https://github.com/appsignal/appsignal-ruby/commit/178bafc23888e38b42f58fbaa17b1c28af060f5e))
+
+### Fixed
+
+- When a Hash-like value (such as `ActiveSupport::HashWithIndifferentAccess` or `Sinatra::IndifferentHash`) is passed to a transaction helper (such as `add_params`, `add_session_data`, ...) it is now converted to a Ruby `Hash` before setting it as the value or merging it with the existing value. This allows Hash-like objects to be merged, instead of logging a warning and only storing the new value.
+
+  ```ruby
+  # Example scenario
+  Appsignal.add_params(:key1 => { :abc => "value" })
+  Appsignal.add_params(ActiveSupport::HashWithIndifferentAccess.new(:key2 => { :def => "value" }))
+
+  # Params
+  {
+    :key1 => { :abc => "value" },
+    # Keys from HashWithIndifferentAccess are stored as Strings
+    "key2" => { "def" => "value" }
+  }
+  ```
+
+  (patch [3155cd48](https://github.com/appsignal/appsignal-ruby/commit/3155cd482e1c708d276eb6eb9db158e551116511), [b201e359](https://github.com/appsignal/appsignal-ruby/commit/b201e35917d61f916b59f1809d99bb196d5f1a1c))
+
 ## 4.5.17
 
 _Published on 2025-07-01._

data/CLAUDE.md

@@ -0,0 +1,177 @@
+# AppSignal Ruby Gem
+
+This is the Ruby gem for AppSignal, an application performance monitoring (APM) service.
+
+## Project Structure
+
+Directories:
+
+- `bin/` - Directory with executables that can be called once the Ruby gem is installed
+- `lib/` - Main library code
+  - `appsignal.rb` - Main module of the Ruby gem
+  - `appsignal/` - Library code
+    - `capistrano.rb` - Capistrano integration
+    - `check_in/` - Check-in functionality
+    - `cli/` - Command Line Interface modules
+    - `config.rb` - Configuration management
+    - `event_formatter/` - Event formatting for different frameworks
+    - `extension.rb` - C extension module, extended by the C extension
+    - `extension/` - C extension modules in the Ruby gem
+    - `hooks/` - Ruby gem hooks and may contain integration code
+    - `integrations/` - Ruby gem integrations, loaded by the hooks
+    - `loaders/` - Ruby gem loaders, integrations manually loaded by applications
+    - `logger.rb` - Logger functionality
+    - `probes/` - Minutely probes
+    - `rack/` - Rack middleware for various Ruby gems
+    - `span.rb` - Tracing span API (private API)
+    - `transaction.rb` - Tracing transaction API
+    - `utils/` - Utility modules
+    - `puma/plugin/appsignal.rb` - AppSignal Puma plugin
+    - `sequel/extensions/appsignal_integration.rb` - AppSignal Sequel plugin placeholder
+- `ext/` - Native C extension
+  - `appsignal_extension.c` - Main C extension
+  - `base.rb` - Extension installation script helpers shared between the MRI Ruby and JRuby installers
+  - `extconf.rb` - Extension installation script for MRI Ruby
+  - `Rakefile` - Extension installation script for JRuby
+  - `agent.rb` - Agent bootstrapping
+- `spec/` - RSpec test suite
+  - `lib/` - Unit tests
+  - `integration/` - Integration tests
+  - `support/` - Test helpers, matchers, shared examples, stubs and fixtures
+- `gemfiles/` - Gemfile variations used for testing
+- `resources/` - Configuration templates
+- `script/` - Development scripts
+
+Files:
+
+- `Gemfile`: Additional development dependencies
+- `Rakefile`: Build and development tasks
+- `appsignal.gemspec`: Gem specification
+- `build_matrix.yml`: Build matrix configuration
+- `mono.yml`: [Mono](https://github.com/appsignal/mono/) release configuration
+
+## Key Components
+
+### Core Library Files (`lib/`)
+
+- `appsignal.rb`: Main Ruby gem module with the public API
+- `appsignal/helpers/instrumentation.rb`: Tracing instrumentation helpers
+- `appsignal/helpers/metrics.rb`: Metrics helpers
+- `appsignal/config.rb`: Configuration management and validation
+- `appsignal/transaction.rb`: Transaction API
+- `appsignal/extension.rb`: Interface to native C extension
+- `appsignal/hooks/`: Framework-specific instrumentation hooks
+- `appsignal/integrations/`: Framework integrations (Rails, Sidekiq, etc.)
+- `appsignal/rack/`: Rack middleware for web frameworks
+
+### Native Extension (`ext/`)
+
+- `appsignal_extension.c`: C extension for performance-critical operations
+- `extconf.rb`: Extension build configuration
+- `agent.rb`: Agent initialization and management
+
+### Framework Support
+
+The gem supports numerous web frameworks like:
+
+- Grape
+- Hanami
+- Padrino
+- Rails, including:
+    - Action Cable
+    - Active Support Notifications
+    - Active Job, and all adapters
+    - Action Mailer
+- Sinatra
+- Webmachine
+
+Background job libraries like:
+
+- DelayedJob
+- Resque
+- Shoryuken
+- Sidekiq
+
+Database drivers like:
+
+- DataMapper
+- MongoDB
+- Redis and redis-client
+- Sequel
+
+And gems like:
+
+- Capistrano
+- Excon
+- Net::HTTP
+- Ownership
+- Passenger
+- Puma
+- Rake
+- Unicorn
+
+## Development Commands
+
+### Setup
+
+```bash
+# Install dependencies
+bundle install
+
+# Install the extension
+rake extension:install
+```
+
+### Testing
+
+```bash
+# Run the test suite
+bundle exec rspec
+
+# Run tests for specific framework
+BUNDLE_GEMFILE=gemfiles/<gemfile>.gemfile bundle exec rspec
+```
+
+### Extension development
+
+```bash
+# Install or reinstall the extension
+rake extension:install
+
+# For JRuby
+cd ext && rake
+```
+
+## File organization
+
+### Configuration files
+
+### Testing structure
+
+- `spec/lib/`: Unit tests mirroring `lib/` structure
+- `spec/integration/`: Integration and end-to-end tests
+- `spec/support/`: Test helpers, mocks, and fixtures
+
+### Continuous integration
+
+- `build_matrix.yml`: CI build matrix configuration
+- `.github/workflows/ci.yml`: GitHub Actions workflow (auto-generated)
+
+Update the generated `.github/workflows/ci.yml` file by running the following command:
+
+```bash
+rake build_matrix:github:generate
+```
+
+The script to generate the `.github/workflows/ci.yml` file is part of the `Rakefile`.
+
+## Important Notes
+
+- The gem includes both Ruby and Java (JRuby) versions.
+- Native C extension provides performance-critical functionality.
+- Extensive test matrix covers multiple Ruby versions and frameworks.
+- Uses mono for automated releases and changelog management.
+
+## Documentation
+
+The Ruby gem is documented using YARD and is paired with documentation on the AppSignal documentation website at: https://docs.appsignal.com/ruby.html

data/README.md

@@ -214,6 +214,23 @@ Note that some specs depend on certain other gems to run and if they are not
 loaded RSpec will not run them. See also [Testing with other
 gems](#testing-with-other-gems).
 
+#### Type Signature Validation
+
+The gem includes type signatures for both Sorbet and RBS, automatically generated from YARD documentation using the [sord gem](https://github.com/AaronC81/sord). To generate and validate these signatures:
+
+```bash
+# Generate Sorbet .rbi and RBS .rbs signatures
+script/generate_signatures
+
+# Validate Sorbet .rbi files syntax (this is done on the CI)
+find sig -name "*.rbi" -exec ruby -c {} \;
+
+# Validate RBS .rbs files syntax (this is done on the CI)
+bundle exec rbs parse sig/appsignal.rbs
+```
+
+These type signatures provide enhanced IDE support and static type checking for users of the AppSignal gem. The signatures cover all public APIs and are automatically generated and validated in CI.
+
 #### Testing with other gems
 
 AppSignal runs in many different configurations. To replicate these

data/appsignal.gemspec

@@ -64,6 +64,7 @@ Gem::Specification.new do |gem| # rubocop:disable Metrics/BlockLength
   gem.add_development_dependency "rake", ">= 12"
   gem.add_development_dependency "rspec", "~> 3.8"
   gem.add_development_dependency "rubocop", "1.64.1"
+  gem.add_development_dependency("sord") unless RUBY_PLATFORM == "java"
   gem.add_development_dependency "timecop"
   gem.add_development_dependency "webmock"
   gem.add_development_dependency "yard", ">= 0.9.20"

data/build_matrix.yml

@@ -36,6 +36,35 @@ github:
         - name: "Run RuboCop"
           run: bundle exec rubocop
 
+    validate-signatures:
+      name: "Type signature validation"
+      runs-on: ubuntu-latest
+      steps:
+        - uses: actions/checkout@v4
+        - uses: ruby/setup-ruby@v1
+          with:
+            ruby-version: "3.3"
+            bundler-cache: true
+        - name: "Generate fresh signatures and check sync"
+          run: |
+            # Generate fresh signatures
+            script/generate_signatures
+
+            # Check if any signature files changed
+            if [ -n "$(git status --porcelain sig/)" ]; then
+              echo "❌ ERROR: Signatures are out of sync with YARD documentation"
+              echo "The following files have changes:"
+              git status --porcelain sig/
+              echo "Please run 'script/generate_signatures' to update them"
+              exit 1
+            fi
+
+            echo "✅ Signatures are in sync with YARD documentation"
+        - name: "Validate Sorbet .rbi files"
+          run: find sig -name "*.rbi" -exec ruby -c {} \;
+        - name: "Validate RBS .rbs files"
+          run: bundle exec rbs parse sig/appsignal.rbs
+
     validation:
       name: "Validation of CI"
       runs-on: ubuntu-latest

data/lib/appsignal/auth_check.rb

@@ -14,7 +14,7 @@ module Appsignal
   #
   # @!attribute [r] config
   #   @return [Appsignal::Config] config to use in the authentication request.
-  # @api private
+  # @!visibility private
   class AuthCheck
     # Path used on the AppSignal Push API
     # https://push.appsignal.com/1/auth
@@ -37,7 +37,7 @@ module Appsignal
     # Perform push api validation request and return a descriptive response
     # tuple.
     #
-    # @return [Array<String/nil, String>] response tuple.
+    # @return [Array<String, String>] response tuple.
     #   - First value is the response status code.
     #   - Second value is a description of the response and the exception error
     #     message if an exception occurred.
@@ -57,7 +57,7 @@ module Appsignal
     rescue => e
       result = "Something went wrong while trying to " \
         "authenticate with AppSignal: #{e}"
-      [nil, result]
+      ["error", result]
     end
   end
 end

data/lib/appsignal/check_in/cron.rb

@@ -2,8 +2,8 @@
 
 module Appsignal
   module CheckIn
+    # @!visibility private
     class Cron
-      # @api private
       attr_reader :identifier, :digest
 
       def initialize(identifier:)

data/lib/appsignal/check_in/event.rb

@@ -2,7 +2,7 @@
 
 module Appsignal
   module CheckIn
-    # @api private
+    # @!visibility private
     class Event
       class << self
         def new(check_in_type:, identifier:, digest: nil, kind: nil)

data/lib/appsignal/check_in/scheduler.rb

@@ -2,8 +2,11 @@
 
 module Appsignal
   module CheckIn
+    # @!visibility private
     class Scheduler
+      # @!visibility private
       INITIAL_DEBOUNCE_SECONDS = 0.1
+      # @!visibility private
       BETWEEN_TRANSMISSIONS_DEBOUNCE_SECONDS = 10
 
       def initialize
@@ -75,7 +78,6 @@ module Appsignal
         end
       end
 
-      # @api private
       # For internal testing purposes.
       attr_reader :thread, :waker, :queue, :events, :transmitted
 

data/lib/appsignal/check_in.rb

@@ -2,16 +2,18 @@
 
 module Appsignal
   module CheckIn
+    # @!visibility private
     HEARTBEAT_CONTINUOUS_INTERVAL_SECONDS = 30
+    # @!visibility private
     NEW_SCHEDULER_MUTEX = Mutex.new
 
     class << self
-      # @api private
+      # @!visibility private
       def continuous_heartbeats
         @continuous_heartbeats ||= []
       end
 
-      # @api private
+      # @!visibility private
       def kill_continuous_heartbeats
         continuous_heartbeats.each(&:kill)
       end
@@ -36,8 +38,9 @@ module Appsignal
       #   end
       #
       # @param identifier [String] identifier of the cron check-in to report.
-      # @yield the block to monitor.
-      # @return [void]
+      # @yield [] the block to monitor.
+      # @yieldreturn [Object] The return value of the block
+      # @return [Object] returns the block value.
       # @since 3.13.0
       # @see https://docs.appsignal.com/check-ins/cron
       def cron(identifier)
@@ -84,7 +87,7 @@ module Appsignal
         scheduler.schedule(event)
       end
 
-      # @api private
+      # @!visibility private
       def scheduler
         return @scheduler if @scheduler
 
@@ -95,7 +98,7 @@ module Appsignal
         @scheduler
       end
 
-      # @api private
+      # @!visibility private
       def stop
         scheduler&.stop
       end

data/lib/appsignal/cli/diagnose.rb

@@ -75,7 +75,7 @@ module Appsignal
         # @option options :environment [String] environment to load
         #   configuration for.
         # @return [void]
-        # @api private
+        # @!visibility private
         def run(options = {})
           # Do not start AppSignal on `Appsignal.start` and run the extension
           # and agent in diagnose mode.

data/lib/appsignal/cli.rb

@@ -9,7 +9,7 @@ require "appsignal/cli/diagnose"
 require "appsignal/cli/install"
 
 module Appsignal
-  # @api private
+  # @!visibility private
   class CLI
     AVAILABLE_COMMANDS = %w[demo diagnose install].freeze