docs

Author: GrantBirki

README.md

@@ -294,6 +294,14 @@ See the [Auth Plugins](docs/auth_plugins.md) documentation for even more informa
 
 See the [Handler Plugins](docs/handler_plugins.md) documentation for in-depth information about handler plugins and how you can create your own to extend the functionality of the Hooks framework for your own deployment.
 
+### Lifecycle Plugins
+
+See the [Lifecycle Plugins](docs/lifecycle_plugins.md) documentation for information on how to create lifecycle plugins that can hook into the request/response/error lifecycle of the Hooks framework, allowing you to add custom behavior at various stages of processing webhook requests.
+
+### Instrument Plugins
+
+See the [Instrument Plugins](docs/instrument_plugins.md) documentation for information on how to create instrument plugins that can be used to collect metrics or report exceptions during webhook processing. These plugins can be used to integrate with monitoring and alerting systems.
+
 ## Contributing 🤝
 
 See the [Contributing](CONTRIBUTING.md) document for information on how to contribute to the Hooks project, including setting up your development environment, running tests, and releasing new versions.

docs/instrument_plugins.md

@@ -1,72 +1,35 @@
 # Instrument Plugins
 
-Instrument plugins provide global components for cross-cutting concerns like metrics collection and error reporting. The hooks framework includes two built-in instrument types: `stats` for metrics and `failbot` for error reporting.
+Instrument plugins provide global components for cross-cutting concerns like metrics collection and error reporting. The hooks framework includes two built-in instrument types: `stats` for metrics and `failbot` for error reporting. By default, these instruments are no-op implementations that do not require any external dependencies. You can create custom implementations to integrate with your preferred monitoring and error reporting services.
 
 ## Overview
 
 By default, the framework provides no-op stub implementations that do nothing. This allows you to write code that calls instrument methods without requiring external dependencies. You can replace these stubs with real implementations that integrate with your monitoring and error reporting services.
 
 The instrument plugins are accessible throughout the entire application:
+
 - In handlers via `stats` and `failbot` methods
 - In auth plugins via `stats` and `failbot` class methods  
 - In lifecycle plugins via `stats` and `failbot` methods
 
-## Built-in Instruments
-
-### Stats
-
-The stats instrument provides methods for metrics collection:
-
-```ruby
-# Increment counters
-stats.increment("webhook.processed", { handler: "MyHandler" })
-
-# Record values
-stats.record("webhook.payload_size", 1024, { event: "push" })
-
-# Record timing manually
-stats.timing("webhook.duration", 0.5, { handler: "MyHandler" })
-
-# Measure execution time automatically
-result = stats.measure("database.query", { table: "webhooks" }) do
-  # Database operation here
-  perform_database_query
-end
-```
-
-### Failbot
-
-The failbot instrument provides methods for error reporting:
+## Creating Custom Instruments
 
-```ruby
-# Report exceptions
-begin
-  risky_operation
-rescue => e
-  failbot.report(e, { context: "webhook_processing" })
-end
+To create custom instrument implementations, inherit from the appropriate base class and implement the required methods.
 
-# Report critical errors
-failbot.critical("Database connection lost", { service: "postgres" })
+To actually have `stats` and `failbot` do something useful, you need to create custom classes that inherit from the base classes provided by the framework. Here’s an example of how to implement custom stats and failbot plugins.
 
-# Report warnings
-failbot.warning("Slow response time detected", { duration: 2.5 })
+You would then set the following attribute in your `hooks.yml` configuration file to point to these custom instrument plugins:
 
-# Capture exceptions automatically
-result = failbot.capture({ operation: "webhook_validation" }) do
-  validate_webhook_payload(payload)
-end
+```yaml
+# hooks.yml
+instruments_plugin_dir: ./plugins/instruments
 ```
 
-## Creating Custom Instruments
-
-To create custom instrument implementations, inherit from the appropriate base class and implement the required methods.
-
 ### Custom Stats Implementation
 
 ```ruby
-# custom_stats.rb
-class CustomStats < Hooks::Plugins::Instruments::StatsBase
+# plugins/instruments/stats.rb
+class Stats < Hooks::Plugins::Instruments::StatsBase
   def initialize
     # Initialize your metrics client
     @client = MyMetricsService.new(
@@ -107,8 +70,8 @@ end
 ### Custom Failbot Implementation
 
 ```ruby
-# custom_failbot.rb  
-class CustomFailbot < Hooks::Plugins::Instruments::FailbotBase
+# plugins/instruments/failbot.rb  
+class Failbot < Hooks::Plugins::Instruments::FailbotBase
   def initialize
     # Initialize your error reporting client
     @client = MyErrorService.new(
@@ -168,11 +131,11 @@ lifecycle_plugin_dir: ./plugins/lifecycle
 
 Place your instrument plugin files in the specified directory:
 
-```
+```text
 plugins/
 └── instruments/
-    ├── custom_stats.rb
-    └── custom_failbot.rb
+    ├── stats.rb
+    └── failbot.rb
 ```
 
 ## File Naming and Class Detection
@@ -183,11 +146,11 @@ The framework automatically detects which type of instrument you're creating bas
 - Classes inheriting from `FailbotBase` become the `failbot` instrument
 
 File naming follows snake_case to PascalCase conversion:
-- `custom_stats.rb` → `CustomStats`
-- `datadog_stats.rb` → `DatadogStats`  
+
+- `stats.rb` → `stats`
 - `sentry_failbot.rb` → `SentryFailbot`
 
-You can only have one stats plugin and one failbot plugin loaded. If multiple plugins of the same type are found, the last one loaded will be used.
+You can only have one `stats` plugin and one `failbot` plugin loaded. If multiple plugins of the same type are found, the last one loaded will be used.
 
 ## Usage in Your Code
 
@@ -364,4 +327,4 @@ expect(test_stats.recorded_metrics).to include(
 4. **Validate configuration**: Check for required environment variables in `initialize`
 5. **Document custom methods**: If you add methods beyond the base interface, document them
 6. **Consider performance**: Instruments are called frequently, so keep operations fast
-7. **Use connection pooling**: For high-throughput scenarios, use connection pooling for external services
+7. **Use connection pooling**: For high-throughput scenarios, use connection pooling for external services

docs/lifecycle_plugins.md

@@ -104,20 +104,20 @@ end
 
 ```ruby
 def on_request(env)
-  # Increment counters
+  # Increment counters (example)
   stats.increment("webhook.requests", { event: env["HTTP_X_GITHUB_EVENT"] })
 
-  # Record values
+  # Record values (example)
   stats.record("webhook.payload_size", env["CONTENT_LENGTH"].to_i)
 
-  # Measure execution time
+  # Measure execution time (example)
   stats.measure("webhook.processing", { handler: env["hooks.handler"] }) do
     # Processing happens in the handler
   end
 end
 
 def on_response(env, response)
-  # Record timing from environment
+  # Record timing from environment (example)
   stats.timing("webhook.duration", env["hooks.processing_time"])
 end
 ```
@@ -126,22 +126,22 @@ end
 
 ```ruby
 def on_error(exception, env)
-  # Report errors with context
+  # Report errors with context (example)
   failbot.report(exception, {
     endpoint: env["PATH_INFO"],
     event_type: env["HTTP_X_GITHUB_EVENT"],
     handler: env["hooks.handler"]
   })
 
-  # Report critical errors
+  # Report critical errors (example)
   failbot.critical("Handler crashed", { handler: env["hooks.handler"] })
 
-  # Report warnings
+  # Report warnings (example)
   failbot.warning("Slow webhook processing", { duration: env["hooks.processing_time"] })
 end
 
 def on_request(env)
-  # Capture and report exceptions during processing
+  # Capture and report exceptions during processing (example)
   failbot.capture({ context: "request_validation" }) do
     validate_webhook_signature(env)
   end
@@ -161,7 +161,7 @@ auth_plugin_dir: ./plugins/auth
 
 Place your lifecycle plugin files in the specified directory:
 
-```
+```text
 plugins/
 └── lifecycle/
     ├── metrics_lifecycle.rb
@@ -252,4 +252,4 @@ end
 2. **Handle errors gracefully**: Lifecycle plugins should not cause webhook processing to fail
 3. **Use appropriate log levels**: Debug for detailed info, info for normal flow, warn for issues, error for failures
 4. **Include relevant context**: Add useful tags and context to metrics and error reports
-5. **Test thoroughly**: Lifecycle plugins run for every webhook request, so bugs have high impact
+5. **Test thoroughly**: Lifecycle plugins run for every webhook request, so bugs have high impact