cruft_tracker 0.1.4 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7dc443c51a9e3e97dce2c669591a34eb840d6ea0e7ea99e2d9fae20410c2a49a
-  data.tar.gz: 81b3d73761b33e0ce81dc2967686502e2c16d796f12826651221209fadf9a08e
+  metadata.gz: e11661e18988d5a678417bb2295abf479c7eecd17644ab9e3fa3386188e6a25a
+  data.tar.gz: 104b7dc62a4590837655618f9eb82786f609e7a0b5733b629afc85628088ea9b
 SHA512:
-  metadata.gz: 583a4dd4ccb6f97e1c10a9dd3e5e2855ae3898bd97ba20abeadf13fe7e2441b0f24a1a1d4208e14054712812a84bb41db1bc7af5f2ed9d259fbdd175f0736a62
-  data.tar.gz: f88a8a2c8bd7a2a652f8dad3f416f84f7b430b4373dd0180b69ee6ff5fe4c982b79beb8ba0b1ca5d939ec66b560605020360e6b2d20528f76add7f67f98d525e
+  metadata.gz: 635d585bc91bc042b6713f40e2da1c782d4e42664c5a69e3b6377089f38cf5bb91744a6f202ff9ef61020d2ce6170b507644d5ec45908ee88b682f685f8a7fa0
+  data.tar.gz: ec22b4e3e545e2adec8094f4a5e6b46156d9d2cf35d0ef3f20f61c347f50e7c2160b98767fd8a1943ba366df13d0459de8391bbfa34f78e2dfa0f79e99d04904

data/README.md

@@ -1,12 +1,12 @@
 # CruftTracker
 
-Have you ever asked yourself, "Is this method even being used?!" Or, "What the heck is this method receiving?" Does your application use Rails? If the answers
+Have you ever asked yourself, "Is this method even being used?!" Or, "What the heck is this method receiving?" Or, perhaps, "is this partial being used?" Does your application use Rails? If the answers
 these questions are yes, this gem may be of use to you!
 
-Large applications can accrue cruft; old methods that might once have been important, but are now unused or code that is difficult to understand, but dangerous to refactor. Unfortunately,
+Large applications can accrue cruft; old methods that might once have been important, but are now unused, or code that is difficult to understand, but dangerous to refactor. The same is can be true for views and partials in Rails applications. Unfortunately,
 software is _complex_ and sometimes it's unclear what's really going on. This adds maintenance burdens, headaches, and uncertainty.
 
-This gem aims to give you a couple tools to make it easier to know what (and how) your code is being used (or not).
+This gem aims to give you some tools to make it easier to know what (and how) your code is being used (or not).
 
 CruftTracker supports Rails versions 5.2 to 6.1 at this time. As of now the gem only supports MySQL, but contributions for Postgres or other DBMS would be welcome.
 
@@ -37,6 +37,26 @@ After that, you can run migrations as you normally would. If you've previously i
 
 ## Usage
 
+### Rails Initializer
+
+You should configure CruftTracker by creating an initializer in your Rails application's `config/initializers` directory named `cruft_tracker.rb`. The structure of the initializer is:
+
+```ruby
+CruftTracker.init do
+  # your configuration.... (more on this below)
+end
+```
+
+Note: you may need to wrap the `CruftTracker.init` call in `Rails.application.reloader.to_prepare` to prevent deprecation warnings related to autoloading constants during initialization. For example:
+
+```ruby
+Rails.application.reloader.to_prepare do
+  CruftTracker.init do
+    # your configuration.... (more on this below)
+  end
+end
+```
+
 ### Tracking method invocations
 
 CruftTracker is pretty simple. Let's say you have a class (or module) like this...
@@ -49,19 +69,17 @@ class SomeOldClass
 end
 ```
 
-You're unsure if the `some_old_method` method is actually being used. All you need to do is use `CruftTracker.is_this_method_used?`. This method requires you to pass `self` and a symbol to identify the name of the method to track. For example:
+You're unsure if the `some_old_method` method is actually being used. All you need to do is add an instance of the  `is_this_method_used? ` to the CruftTracker initializer. This method requires you to pass the class constant and a symbol to identify the name of the method to track. For example:
 
 ```ruby
-class SomeOldClass
-  def some_old_method
-    # do things
-  end
+# config/initializers/cruft_tracker.rb
 
-  CruftTracker.is_this_method_used? self, :some_old_method
+CruftTracker.init do
+  is_this_method_used? SomeOldClass, :some_old_method
 end
 ```
 
-What do you get out of this? Well, as soon as Ruby loads the `SomeOldClass` class, CruftTracker will create a new record
+What do you get out of this? Well, as soon as Rails runs the CruftTracker initializer, CruftTracker will create a new record
 in the `cruft_tracker_methods` table that looks like this:
 
 
@@ -85,30 +103,28 @@ The fields are:
 - `updated_at` - The last time this record was updated. IE: the last time the tracked method was invoked.
 
 Looking at this, we can see that the `some_old_method` method has never been invoked. This is nice because it means that
-you can track uses of methods without changing their behavior and also know when a method has _not_ been used. A similar record is created for every method you annotate
-with `CruftTracker.is_this_method_used?`.
+you can track uses of methods without changing their behavior (or editing their class) and also know when a method has _not_ been used. A similar record is created for every method you track
+with `is_this_method_used?`.
 
-Assuming your production application eagerly loads classes, you should always have records for potentially crufty
+You should always have records for potentially crufty
 methods, even if the class itself is never explicitly used.
 
-So, having annotated the method, you can check this table after a while. If you see that there have been zero invocations,
+So, having configured the method to be tracked, you can check this table after a while. If you see that there have been zero invocations,
 you have a reasonably good hint that the method may not actually be used. Of course, you should consider that there are
 some processes that are not run frequently at all, so this gem isn't a panacea. **Think before you delete!**
 
-`CruftTracker.is_this_method_used?` can be used to track any kind of method (except `initialize`) with any visibility. This includes class and module methods (`self.`), private class methods, eigenclass methods, as well as public, private, and protected instance methods.
+`is_this_method_used?` can be used to track any kind of method (except `initialize`) with any visibility. This includes class and module methods (`self.`), private class methods, eigenclass methods, as well as public, private, and protected instance methods.
 
 ### Comments
 
 Since you may have to track a method for a while, it might be helpful to have a reminder as to _why_ you're tracking it in the first place. This can be recorded by providing an optional `comments:` named argument. For example:
 
 ```ruby
-class SomeOldClass
-  def some_old_method
-    # do things
-  end
+# config/initializers/cruft_tracker.rb
 
-  CruftTracker.is_this_method_used?
-    self,
+CruftTracker.init do
+  is_this_method_used?
+    SomeOldClass,
     :some_old_method,
     comment: "I suspect this method is being called via metaprogramming."
 end
@@ -117,13 +133,11 @@ end
 `comment:` can be anything that can be serialized to JSON. For example:
 
 ```ruby
-class SomeOldClass
-  def some_old_method
-    # do things
-  end
+# config/initializers/cruft_tracker.rb
 
-  CruftTracker.is_this_method_used?
-    self,
+CruftTracker.init do
+  is_this_method_used?
+    SomeOldClass,
     :some_old_method,
     comment: {
       creator: "Doug Hughes",
@@ -139,7 +153,7 @@ The comment is serialized to json and stored in the `comments` field of the `Cru
 By default, CruftTracker will record unique backtraces for each invocation of a tracked method. This data is stored in the `cruft_tracker_backtraces` table and is accessible via the `CruftTracker::Method`'s `backtraces` association. The `cruft_tracker_backtraces` table has the following columns:
 
 - `id` - Ye olde primary key.
-- `traceable_type` - The type for the polymorphic `traceable` association. Future versions of CruftTracker may track data in addition to method invocations.
+- `traceable_type` - The type for the polymorphic `traceable` association. Future versions of CruftTracker may track data in addition to method invocations. (Note: This was originally made polymorphic to support view tracking. Since view tracking can't use the backtraces feature, the polymorphism is vestigial and may be removed in the future.)
 - `traceable_id` - The ID of the polymorphic `traceable` association. EG: the `CruftTracker::Method` the backtrace is recorded for.
 - `trace_hash` - Traces are stored as JSON. This column is an MD5 hash of the trace that is indexed to make it easier / faster to know if we've seen a particular trace before.
 - `trace` - The trace data, stored as a JSON array of hashes.
@@ -147,7 +161,7 @@ By default, CruftTracker will record unique backtraces for each invocation of a
 - `created_at` - The first time we saw a particular backtrace.
 - `updated_at` - The most recent time we saw a particular backtrace.
 
-Backtraces can be referenced to figure out exactly where a tracked method is being used. It also implicitly tells you other code that is definitely being used. Do note that as code changes, these record backtraces are not updated. So, if a backtrace says the tracked method was invoked from line 123 of some file, if that file is edited, the line numbers may no longer match. Also, this would be record as a new backtrace.
+Backtraces can be referenced to figure out exactly where a tracked method is being used. It also implicitly tells you other code that is definitely being used. Do note that as code changes, these backtrace records are not updated. So, if a backtrace says the tracked method was invoked from line 123 of some file, if that file is edited, the line numbers may no longer match and would be recorded as a new backtrace.
 
 Future versions of CruftTracker may provide a UI for exploring backtraces.
 
@@ -185,42 +199,36 @@ Now, I ask you a few questions:
 2. What options does `do_something_via_metaprogramming` receive? Are they always the same options?
 3. What classes and methods does `do_something_via_metaprogramming` invoke via metaprogramming?
 
-The answer: _Who the heck knows?!_ 🤷
+The answers: _Who the heck knows?!_ 🤷
 
 So, let's start collecting some data about these arguments. We can do this with the `track_arguments:` named argument on `is_this_method_used?`. This argument takes a proc that receives an `args` array as an argument. Whatever the proc returns is serialized to JSON and stored in the `cruft_tracker_arguments` table.
 
 The naive approach to tracking arguments would be to use something like this:
 
 ```ruby
-class SomeClass
-  def do_something_via_metaprogramming(options)
-    options[:target_class].constantize.send(options[:method], options[:modifiers])
-    YetAnotherClass.do_something_else(options)
-  end
+# config/initializers/cruft_tracker.rb
 
-  CruftTracker.is_this_method_used?
-    self,
+CruftTracker.init do
+  is_this_method_used?
+    SomeClass,
     :do_something_via_metaprogramming,
     track_arguments: -> (args) { args }
 end
 ```
 
-This will track all of the values of the options provided to the `do_something_via_metaprogramming` method. This could be a problem. Consider a case where the method is used a zillion times per day and where there's a plethora of complicated data being passed through the method via its `options` argument. It's possible that each set of arguments is different. This could result in one `potential_cruft_arguments` record per invocation of the tracked method. This is both probably not what. What you probably want to know in this case is:
+This will track all of the values of the options provided to the `do_something_via_metaprogramming` method. This could be a problem. Consider a case where the method is used a zillion times per day and where there's a plethora of complicated data being passed through the method via its `options` argument. It's possible that each set of arguments is different. This could result in one `potential_cruft_arguments` record per invocation of the tracked method. This may not be what you want to know... What you probably want to know in this case is:
 
 - What are the unique sets of keys in the `options` hash?
 - What classes and methods are we calling via metaprogramming?
 
-We could write a proc that looks like this:
+Instead, we could write a proc that looks like this:
 
 ```ruby
-class SomeClass
-  def do_something_via_metaprogramming(options)
-    options[:target_class].constantize.send(options[:method], options[:modifiers])
-    YetAnotherClass.do_something_else(options)
-  end
+# config/initializers/cruft_tracker.rb
 
-  CruftTracker.is_this_method_used?
-    self,
+CruftTracker.init do
+  is_this_method_used?
+    SomeClass,
     :do_something_via_metaprogramming,
     track_arguments: -> (args) do
       options = args.first
@@ -306,9 +314,11 @@ Arguments are tracked in the `cruft_tracker_arguments` table which has these col
 - `updated_at` - The most recent time we saw a particular set of arguments.
 
 
-### Tracking Everything
+### Tracking All Methods
 
-So, let's say you've got a class with a bunch of methods. You want to know if any of the methods are being used, and you just don't want to think very hard about it. That's where `CruftTracker.are_any_of_these_methods_being_used?` comes to the rescue! Just tack that onto the end of your class like this to track all method invocations:
+So, let's say you've got a class with a bunch of methods. You want to know if any of the methods are being used, and you just don't want to think very hard about it. That's where `are_any_of_these_methods_being_used?` comes to the rescue! Just add this to the CruftTracker initializer as shown below.
+
+Let's say this is your class:
 
 ```ruby
 class SomeClass
@@ -328,18 +338,236 @@ class SomeClass
   end
 
   # ... other methods ...
+end
+```
+
+Here's the configuration in the initializer:
+
+```ruby
+# config/initializers/cruft_tracker.rb
 
-  CruftTracker.are_any_of_these_methods_being_used? self
+CruftTracker.init do
+  are_any_of_these_methods_being_used? SomeClass
 end
 ```
 
 This will result in a `cruft_tracker_methods` record being created for each method in the `SomeClass` class. It will _not_ track methods that exist in the class' (or module's) ancestors. It's a quick and easy way to see what's being used. This method cannot be used to track arguments, though it does accept a `comments:` named argument.
 
-You may want to think twice about using this method, or using this method too widely as it may create more data than you expect. CruftTracker is lightweight, but too much of a good thing is still too much. Generally, you should favor being targeted in your tracking.
+You may want to think twice about using this method, or using this method too widely as it may create more data than you expect. CruftTracker is lightweight, but too much of a good thing is still too much. Generally, you should favor tracking only what you are specifically interested in.
+
+### Tracking Views
+
+In additon to tracking methods, CruftTracker lets you track details about view rendering. Consider this scenario: You have a large legacy application with a ton views and partials. Over time your controllers have been changed and sometimes deleted. Perhaps a partial was once widely used, but isn't anymore. You might want to be able to easily tell if a given partial or view is being used. Once again, CruftTracker to the rescue!
+
+Let's say you have this view and you're just not sure it's being used anymore:
+
+```erb
+<!-- app/views/something/some_view.html.erb -->
+  
+<div>
+  <%- if @data.present? %>
+  	<strong>Woo hoo!</strong>
+  <% end %>
+</div>
+```
+
+You can track renders of this view by using `is_this_view_used?` in the CruftTracker initializer:
+
+```ruby
+# config/initializers/cruft_tracker.rb
+
+CruftTracker.init do
+  is_this_view_used? 'app/views/something/some_view.html.erb'
+end
+```
+
+Note that the path provided is from the application's root.
+
+As soon as Rails runs the CruftTracker initializer, CruftTracker will create a new record
+in the `cruft_tracker_views` table that looks like this:
+
+
+| id   | view                                   | renders | comment | deleted_at | created_at          | updated_at          |
+| ---- | -------------------------------------- | ------- | ------- | ---------- | ------------------- | ------------------- |
+| 1    | app/views/something/some_view.html.erb | 0       | null    | null       | 2022-01-21 14:07:48 | 2022-01-21 14:07:48 |
+
+This record is accessible using the `CruftTracker::View` model. EG: `CruftTracker::View.find(1)`
+
+The fields are:
+
+- `id` - Shockingly, this is the primary key.
+- `view` - This is the path to the view from the Rails application's root.
+- `renders` - The number of times the view has been rendered.
+- `comments` -  This is a JSON field containing extra data provided to the option `comments:` argument for the `is_this_view_used?` method.
+- `deleted_at` - When set, this indicates that the view is no longer being tracked.
+- `created_at` - The date/time we started tracking the view.
+- `updated_at` - The last time this record was updated. IE: the last time the tracked view was rendered.
+
+Looking at this, we can see that the `app/views/something/some_view.html.erb` view has never been rendered. This is nice because it means that
+you can track renders of views, but you can and also know when a view has _not_ been rendered. A similar record is created for every view you track
+with `is_this_view_used?` You should always have records for potentially crufty
+views, even if the view itself is never rendered.
+
+So, having configured the view to be tracked, you can check this table after a while. If you see that there have been zero renders,
+you have a reasonably good hint that the view may not actually be used. Of course, some things aren't used frequently. **Think before you delete!**
+
+`is_this_view_used?` can be used to track ordinary views as well as partials. While only tested with ERB templates, it should work with any other template engine, such as HAML. If you run into problems, please open a Github issue!
+
+### Tracking View Rendering Details
+
+Out of the box, you don't get a lot of information when tracking views. Basically, all you know is the number of times a view has been rendered. That's helpful, but not exactly amazing. Happily, CruftTracker provides a view helper that can be used to track a lot more information about view renders. The only downside is that it requires you to add a line of code to your templates. 
+
+Let's say you have this partial and you want to know not just if it's used, but _what uses it_.
+
+```erb
+<!-- app/views/shared/whatever.html.erb -->
+
+<div>I am a partial. Hear me roar.</div>
+
+<div><%= some_value %></div>
+```
+
+You'll still want to configure view tracking in the initializer:
+
+```ruby
+# config/initializers/cruft_tracker.rb
+
+CruftTracker.init do
+  is_this_view_used? 'app/views/shared/whatever.html.erb'
+end
+```
+
+However, to get additional details about renders of this partial, you can invoke the `record_cruft_tracker_view_render` helper into the view. It's recommended to add this on the first line of the view. EG:
+
+```erb
+<!-- app/views/shared/whatever.html.erb -->
+  
+<%- record_cruft_tracker_view_render %>
+
+<div>I am a partial. Hear me roar.</div>
+
+<div><%= some_value %></div>
+```
+
+When the view is actually rendered, CruftTracker will collect information about the render and store it in the `cruft_tracker_view_renders` table, like this:
+
+| id   | view_id | render_hash                      | controller     | endpoint     | route                  | render_stack | occurrences | created_at          | updated_at          |
+| ---- | ------- | -------------------------------- | -------------- | ------------ | ---------------------- | ------------ | ----------- | ------------------- | ------------------- |
+| 1    | 1       | 98cc3bd79cf6f3606c5afe3b9faf925b | SomeController | do_something | /foo/:id/bar(.:format) | [{...}]      | 1           | 2022-07-06 15:29:06 | 2022-07-06 15:29:06 |
+
+This record is represented by the `CruftTracker::ViewRender` model and can be loaded in the usual ways. You can also access it from a specific view record. EG: `CruftTracker::View.find(1).view_renders`, which will return an association of unique renders.
+
+There's a lot packed into that record. Let's disect it:
+
+* `id` - This is the primary key for the view render.
+
+* `view_id` - This is the id of the view that was rendered. 
+
+* `render_hash` - This is the MD5 hash of the combination of the `controller`, `endpoint`, `route`, `http_method`, and the JSON version of the `render_stack`. The combination of these fields must be unique so that we can count the number of occurrences. The `render_hash` is a shortcut used by CruftTracker to easily determine if the combination of these items is unique. Basically, it's for optimization purposes and you shouldn't worry about it. :wink:
+
+* `controller` - This is the class name for the controller that ultimately triggered rendering this view. Note that this controller is what kicked off the render, not necessarily what directly caused the view to be rendered. In the case of a partial, you could have a deeply nested set of renders. All the `controller` tells you is that a request to the controller ultimately caused the view to be rendered.
+
+* `endpoint` - This is the method within the controller that caused the view to be rendered. The same caveats apply as with `controller`.
+
+* `route` - This is the generic route that caused the view to be rendered. Note that this doesn't include the IDs, but the route's pattern for the IDs.
+
+* `http_method` - This is the HTTP method used to access the `endpoint`.
+
+* `render_stack` - This is an array that is _similar_ to a backtrace, but isn't actually a backtrace. To explain, if you call `render` in a controller, Rails doesn't actually render the view at that time. Instead, it ensues the view for rendering once the controller's method has finished executing. That means that if, while the view is rendering, you call invoke Ruby's `caller_locations`, you wouldn't see the controller that triggered the render. It was decided that this was generally pretty useless. Instead, what this field stores is the hierarchy of views / partials being rendered, but none of the other related code. It can provide a hint of how a deeply nested partial is rendered. Here's an example that shows a partial being rendered from a regular view: 
+
+  ```ruby
+  [
+    { "path": "/app/spec/dummy/app/views/shared/_whatever.html.erb", 
+      "label": "_app_views_shared__whatever_html_erb___436643032048620150_11500", 
+      "lineno": 1, 
+      "base_label": "_app_views_shared__whatever_html_erb___436643032048620150_11500" }, 
+    { "path": "/app/spec/dummy/app/views/main/show.html.erb", 
+      "label": "_app_views_main_show_html_erb__2350809826889573468_11260", 
+      "lineno": 6, 
+      "base_label": "_app_views_main_show_html_erb__2350809826889573468_11260"}
+  ]
+  ```
+
+* `occurrences` - This is the number of times that this particular set of details have been seen when rendering a particular view.
+
+* `created_at` - The date/time we first saw this controller, endpoint, route, etc render the view.
+
+* `updated_at` - The last time we first saw this controller, endpoint, route, etc render the view.
+
+### Tracking View Render Metadata
+
+Knowing what caused a view to render is all well and good, but sometimes you might want a little more insight. Similar to how you can track arguments on methods with CruftTracker, you can track metadata for views. This is simply an argument you provide to the `record_cruft_tracker_view_render`  method. For example:
+
+```erb
+<!-- app/views/shared/whatever.html.erb -->
+  
+<%- record_cruft_tracker_view_render(some_value) %>
+
+<div>I am a partial. Hear me roar.</div>
+
+<div><%= some_value %></div>
+```
+
+The metadata argument can be anything that is serializable to JSON. When you provide the argument, a record will be created or updated in the `cruft_tracker_render_metadata` table that looks like this:
+
+| id   | view_render_id | metadata_hash                    | metadata            | occurrences | created_at          | updated_at          |
+| ---- | -------------- | -------------------------------- | ------------------- | ----------- | ------------------- | ------------------- |
+| 1    | 1              | a434e71475ff330064970fdc9fb123fc | ...your metadata... | 1           | 2022-07-06 16:07:38 | 2022-07-06 16:07:38 |
+
+Let's break this down:
+
+* `id` - Ye olde primary key
+* `view_render_id` - This is the ID of the `CruftTracker::ViewRender` that this metadata is associated with.
+* `metadata_hash` - This is the hash of the `metadata` field so that we can easily create a unique index.
+* `occurrences` - The number of times that this exact metadata has been seen before.
+* `created_at` - The first time we saw this metadata.
+* `updated_at` - The most recent time we saw this metadata.
+
+`CruftTracker::RenderMetadata` can be accessed from a `CruftTracker::ViewRender` via its `render_metadata` association.
+
+A word of caution: don't track ever variable. Variables are, by definition, variable. Each time a view renders you could have a different value for a variable. Instead, this would be better used to track what variables are available. EG:
+
+```erb
+<!-- app/views/shared/whatever.html.erb -->
+  
+<%- record_cruft_tracker_view_render(instance_variables) %>
+
+<div>I am a partial. Hear me roar.</div>
+
+<div><%= some_value %></div>
+```
 
 ### Clean Up
 
-CruftTacker automatically cleans up after itself. ✨🧹 If you remove an instance of `CruftTracker.is_this_method_used?` to stop tracking a method, CruftTracker will recognize this when your application starts up and mark the associated `cruft_tracker_methods` record as deleted. But, only in environments where eager loading is enabled.
+CruftTacker automatically cleans up after itself. ✨🧹 If you remove any configured tracking, CruftTracker will recognize this when your application starts up and mark the associated `cruft_tracker_methods` record as deleted. 
+
+## Configuration
+
+Imagine a scenario where you have a method or view that is used in many places, or maybe as a result of metaprogramming. Perhaps you have some logic that is user-configurable and might lead to a tracked method being called with any number of backtraces. It's not super helpful to track all possible backtraces and it's actively bad, since it wastes space in your database and slows down queries. Besides, it's no fun drinking from the firehose.
+
+CruftTracker provides a few configurable settings to control the amount of data recorded in some of its tables. 
+
+| Name                                             | Default | Description                                                  |
+| ------------------------------------------------ | ------- | ------------------------------------------------------------ |
+| `max_argument_variations_per_tracked_method`     | 50      | Sets the maximum number of distinct arguments that can be recorded for any tracked method. |
+| `max_backtrace_variations_per_tracked_method`    | 50      | Sets the maximum number of distinct backtraces that can be recorded for any tracked method. |
+| `max_view_renders_per_view`                      | 50      | Sets the maximum number of distinct renders that can be recorded for any tracked view. |
+| `max_render_metadata_variations_per_view_render` | 50      | Sets the maximum number of distinct render metadata records that can be recorded for any specific render of a view. |
+
+These configuration values can be set within the CruftTracker initializer like this:
+
+```ruby
+# config/initializers/cruft_tracker.rb
+
+CruftTracker.init do
+  config.max_argument_variations_per_tracked_method = 20
+  config.max_backtrace_variations_per_tracked_method = 25
+  config.max_view_renders_per_view = 30
+  config.max_render_metadata_variations_per_view_render = 35
+  
+  # ... your configuration for tracking methods or views ...
+end
+```
 
 ## API Docs
 
@@ -369,10 +597,10 @@ Returns an array of `CruftTracker::Method` instances.
 
 ##### Arguments
 
-| Name                     | Type                                    | Required? | Default | Description                                                                                                                                                                                                  |
-| ------------------------ | --------------------------------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| owner (positional)       | a class or module constant              | yes       | N/A     | A reference to the class or module that owns the method. Set this to `self`.                                                                                                                                 |
-| comment: (named)         | anything that can be serialized to json | no        | nil     | Arbitrary data you want to include with the `cruft_tracker_methods` record. For example, a note about why the method is being tracked or a hash with keys indicating who is tracking the method and and why. |
+| Name               | Type                                    | Required? | Default | Description                                                  |
+| ------------------ | :-------------------------------------- | --------- | ------- | ------------------------------------------------------------ |
+| owner (positional) | a class or module constant              | yes       | N/A     | A reference to the class or module that owns the method. Set this to `self`. |
+| comment: (named)   | anything that can be serialized to json | no        | nil     | Arbitrary data you want to include with the `cruft_tracker_methods` record. For example, a note about why the method is being tracked or a hash with keys indicating who is tracking the method and and why. |
 
 ## Developing
 

data/app/controllers/cruft_tracker/methods_controller.rb

@@ -2,9 +2,7 @@
 
 module CruftTracker
   class MethodsController < ApplicationController
-
     def index
-      
     end
   end
 end

data/app/helpers/cruft_tracker/application_helper.rb

@@ -1,4 +1,57 @@
 module CruftTracker
   module ApplicationHelper
+    def record_cruft_tracker_view_render(metadata = nil)
+      CruftTracker::RecordViewRender.run!(
+        view: cruft_tracker_view,
+        controller: controller.class.to_s,
+        endpoint: action_name,
+        route: route_path,
+        http_method: request.method,
+        render_stack: render_stack,
+        metadata: metadata
+      )
+    rescue StandardError
+      # Swallow errors
+    end
+
+    private
+
+    def cruft_tracker_view
+      path = render_stack.first[:path].gsub(%r{#{Rails.root}/}, '')
+      view = CruftTracker::View.find_by(view: path)
+
+      return view if view.present?
+
+      CruftTracker::TrackView.run!(view: path)
+    end
+
+    def route_path
+      _routes
+        .router
+        .recognize(request) { |route, _| return route.path.spec.to_s }
+
+      nil
+    end
+
+    def paths_to_views
+      @paths_to_views ||= view_paths.map { |view_path| view_path.to_path }
+    end
+
+    def render_stack
+      caller_locations
+        .select do |caller_location|
+          paths_to_views.any? do |path_for_view|
+            caller_location.path.match?(%r{^#{path_for_view}/})
+          end
+        end
+        .map do |location|
+          {
+            path: location.path,
+            label: location.label,
+            base_label: location.base_label,
+            lineno: location.lineno
+          }
+        end
+    end
   end
 end

data/app/models/cruft_tracker/render_metadata.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module CruftTracker
+  class RenderMetadata < ActiveRecord::Base
+    belongs_to :view_render, class_name: 'CruftTracker::ViewRender'
+  end
+end

data/app/models/cruft_tracker/view.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module CruftTracker
+  class View < ActiveRecord::Base
+    has_many :backtraces, class_name: 'CruftTracker::Backtrace', as: :traceable
+    has_many :view_renders, class_name: 'CruftTracker::ViewRender'
+
+    def still_exists?
+      File.exist?(absolute_path)
+    end
+
+    def still_tracked?
+      return true if CruftTracker::Registry.include?(self)
+      if File.read(absolute_path).match?(/record_cruft_tracker_view_render/)
+        return true
+      end
+
+      false
+    end
+
+    private
+
+    def absolute_path
+      "#{Rails.root}/#{view}"
+    end
+  end
+end

data/app/models/cruft_tracker/view_render.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module CruftTracker
+  class ViewRender < ActiveRecord::Base
+    belongs_to :view, class_name: 'CruftTracker::View'
+    has_many :render_metadata, class_name: 'CruftTracker::RenderMetadata'
+  end
+end

data/app/services/cruft_tracker/cleanup_untracked_views.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module CruftTracker
+  class CleanupUntrackedViews < CruftTracker::ApplicationService
+    private
+
+    def execute
+      CruftTracker::LogSuppressor.suppress_logging do
+        CruftTracker::View
+          .where(deleted_at: nil)
+          .each do |view|
+            unless view.still_exists? && view.still_tracked?
+              view.update(deleted_at: Time.current)
+            end
+          end
+      end
+    rescue StandardError
+      # I'm actively ignoring all errors. Chances are, these are due to something like running rake
+      # tasks in CI when the DB doesn't already exist.
+    end
+  end
+end

data/app/services/cruft_tracker/increment_view_renders.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module CruftTracker
+  class IncrementViewRenders < CruftTracker::ApplicationService
+    record :view, class: CruftTracker::View
+
+    def execute
+      CruftTracker::LogSuppressor.suppress_logging { increment_renders }
+    end
+
+    def increment_renders
+      view.update(renders: view.reload.renders + 1)
+    end
+  end
+end

data/app/services/cruft_tracker/record_arguments.rb

@@ -9,6 +9,8 @@ module CruftTracker
     private
 
     def execute
+      return unless arguments_record.present?
+
       CruftTracker::LogSuppressor.suppress_logging do
         arguments_record.with_lock do
           arguments_record.reload
@@ -22,16 +24,22 @@ module CruftTracker
     def arguments_record
       @arguments_record ||=
         begin
+          return find_existing_arguments_record if max_records_reached?
+
           CruftTracker::Argument.create(
             method: method,
             arguments_hash: arguments_hash,
             arguments: transformed_arguments
           )
         rescue ActiveRecord::RecordNotUnique
-          CruftTracker::Argument.find_by(arguments_hash: arguments_hash)
+          find_existing_arguments_record
         end
     end
 
+    def find_existing_arguments_record
+      CruftTracker::Argument.find_by(arguments_hash: arguments_hash)
+    end
+
     def arguments_hash
       Digest::MD5.hexdigest(transformed_arguments.to_json)
     end
@@ -39,5 +47,9 @@ module CruftTracker
     def transformed_arguments
       @transformed_arguments ||= transformer.call(arguments)
     end
+
+    def max_records_reached?
+      CruftTracker::Argument.where(method: method).count >= CruftTracker.config.max_argument_variations_per_tracked_method
+    end
   end
 end

data/app/services/cruft_tracker/record_backtrace.rb

@@ -7,6 +7,8 @@ module CruftTracker
     private
 
     def execute
+      return unless backtrace_record.present?
+
       CruftTracker::LogSuppressor.suppress_logging do
         backtrace_record.with_lock do
           backtrace_record.reload
@@ -20,16 +22,22 @@ module CruftTracker
     def backtrace_record
       @backtrace_record ||=
         begin
+          return find_existing_backtrace_record if max_records_reached?
+
           CruftTracker::Backtrace.create(
             traceable: method,
             trace_hash: backtrace_hash,
             trace: filtered_backtrace
           )
         rescue ActiveRecord::RecordNotUnique
-          CruftTracker::Backtrace.find_by(trace_hash: backtrace_hash)
+          find_existing_backtrace_record
         end
     end
 
+    def find_existing_backtrace_record
+      CruftTracker::Backtrace.find_by(trace_hash: backtrace_hash)
+    end
+
     def backtrace_hash
       Digest::MD5.hexdigest(filtered_backtrace.to_json)
     end
@@ -51,5 +59,9 @@ module CruftTracker
           }
         end
     end
+
+    def max_records_reached?
+      CruftTracker::Backtrace.where(traceable: method).count >= CruftTracker.config.max_backtrace_variations_per_tracked_method
+    end
   end
 end

data/app/services/cruft_tracker/record_render_metadata.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module CruftTracker
+  # Records provided metadata associated with a given render
+  class RecordRenderMetadata < CruftTracker::ApplicationService
+    record :view_render, class: CruftTracker::ViewRender
+    interface :metadata, methods: %i[to_json], default: nil
+
+    private
+
+    def execute
+      return unless metadata.present?
+      return unless render_metadata_record.present?
+
+      CruftTracker::LogSuppressor.suppress_logging do
+        render_metadata_record.with_lock do
+          render_metadata_record.reload
+          render_metadata_record.update(
+            occurrences: render_metadata_record.occurrences + 1
+          )
+        end
+      end
+    end
+
+    def render_metadata_record
+      @render_metadata_record ||=
+        begin
+          return find_existing_render_metadata_record if max_records_reached?
+
+          CruftTracker::RenderMetadata.create(
+            view_render: view_render,
+            metadata_hash: metadata_hash,
+            metadata: metadata
+          )
+        rescue ActiveRecord::RecordNotUnique
+          find_existing_render_metadata_record
+        end
+    end
+
+    def find_existing_render_metadata_record
+      CruftTracker::RenderMetadata.find_by(metadata_hash: metadata_hash)
+    end
+
+    def metadata_hash
+      Digest::MD5.hexdigest([view_render.render_hash, metadata].to_json)
+    end
+
+    def max_records_reached?
+      CruftTracker::RenderMetadata.where(view_render: view_render).count >= CruftTracker.config.max_render_metadata_variations_per_view_render
+    end
+  end
+end

data/app/services/cruft_tracker/record_view_render.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module CruftTracker
+  class RecordViewRender < CruftTracker::ApplicationService
+    record :view, class: CruftTracker::View
+    string :controller
+    string :endpoint
+    string :route
+    string :http_method
+    array :render_stack do
+      hash do
+        string :path
+        string :label
+        string :base_label
+        integer :lineno
+      end
+    end
+    interface :metadata, methods: %i[to_json], default: nil
+
+    private
+
+    def execute
+      return unless view_render_record.present?
+
+      CruftTracker::LogSuppressor.suppress_logging do
+        view.with_lock do
+          view.reload
+          view.update(renders: view.renders + 1)
+        end
+
+        view_render_record.with_lock do
+          view_render_record.reload
+          view_render_record.update(
+            occurrences: view_render_record.occurrences + 1
+          )
+
+          record_render_metadata(view_render_record)
+
+          view_render_record
+        end
+      end
+    end
+
+    def record_render_metadata(view_render_record)
+      compose(
+        CruftTracker::RecordRenderMetadata,
+        view_render: view_render_record,
+        metadata: metadata
+      )
+    end
+
+    def view_render_record
+      @view_render_record ||=
+        begin
+          return find_existing_view_render_record if max_records_reached?
+
+          CruftTracker::ViewRender.create(
+            view: view,
+            render_hash: render_hash,
+            controller: controller,
+            endpoint: endpoint,
+            route: route,
+            http_method: http_method,
+            render_stack: render_stack
+          )
+        rescue ActiveRecord::RecordNotUnique
+          find_existing_view_render_record
+        end
+    end
+
+    def find_existing_view_render_record
+      CruftTracker::ViewRender.find_by(render_hash: render_hash)
+    end
+
+    def render_hash
+      Digest::MD5.hexdigest(
+        {
+          controller: controller,
+          endpoint: endpoint,
+          route: route,
+          http_method: http_method,
+          render_stack: render_stack.to_json
+        }.to_json
+      )
+    end
+
+    def max_records_reached?
+      CruftTracker::ViewRender.where(view: view).count >= CruftTracker.config.max_view_renders_per_view
+    end
+  end
+end

data/app/services/cruft_tracker/track_method.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# require 'cruft_tracker/record_invocation'
-# require 'cruft_tracker/record_backtrace'
 module CruftTracker
   class TrackMethod < CruftTracker::ApplicationService
     private

data/app/services/cruft_tracker/track_view.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module CruftTracker
+  # creates or updates a CruftTracker:View record and configures subscriptions for render events
+  class TrackView < CruftTracker::ApplicationService
+    private
+
+    string :view
+    interface :comment, methods: %i[to_json], default: nil
+
+    def execute
+      view_record =
+        CruftTracker::LogSuppressor.suppress_logging do
+          view_record = create_or_find_view_record
+          view_record.deleted_at = nil
+          view_record.comment = comment if comment != view_record.comment
+          view_record.save
+          view_record
+        end
+
+      listen_for_render(view_record)
+
+      CruftTracker::Registry << view_record
+
+      view_record
+    rescue ActiveRecord::StatementInvalid => e
+      raise unless e.cause.present? && e.cause.instance_of?(Mysql2::Error)
+
+      Rails.logger.warn(
+        'CruftTracker was unable to record a view. Does the cruft_tracker_views table exist? Have migrations been run?'
+      )
+    rescue NoMethodError
+      Rails.logger.warn(
+        'CruftTracker was unable to record a view. Have migrations been run?'
+      )
+    rescue Mysql2::Error::ConnectionError,
+           ActiveRecord::ConnectionNotEstablished
+      Rails.logger.warn(
+        'CruftTracker was unable to record a view due to being unable to connect to the database. This may be a non-issue in cases where the database is intentionally not available.'
+      )
+    end
+
+    def listen_for_render(view_record)
+      ActiveSupport::Notifications.subscribe /!render_.*\.action_view/ do |*args|
+        event = ActiveSupport::Notifications::Event.new(*args)
+        if event.payload[:identifier] == "#{Rails.root}/#{view}"
+          CruftTracker::IncrementViewRenders.run!(view: view_record.id)
+        end
+      rescue StandardError
+        # suppress errors
+      end
+    end
+
+    def create_or_find_view_record
+      CruftTracker::View.create(view: view, comment: comment)
+    rescue ActiveRecord::RecordNotUnique
+      CruftTracker::View.find_by(view: view)
+    end
+  end
+end

data/config/routes.rb

@@ -1,3 +1 @@
-CruftTracker::Engine.routes.draw do
-  resources :methods, only: %i[index]
-end
+CruftTracker::Engine.routes.draw { resources :methods, only: %i[index] }

data/db/migrate/20220628175222_create_cruft_tracker_views.rb

@@ -0,0 +1,13 @@
+class CreateCruftTrackerViews < ActiveRecord::Migration[5.2]
+  def change
+    create_table :cruft_tracker_views do |t|
+      t.string :view, null: false
+      t.integer :renders, null: false, default: 0
+      t.json :comment, null: true
+      t.datetime :deleted_at
+      t.timestamps
+
+      t.index :view, unique: true
+    end
+  end
+end

data/db/migrate/20220701125925_create_cruft_tracker_view_renders.rb

@@ -0,0 +1,18 @@
+class CreateCruftTrackerViewRenders < ActiveRecord::Migration[5.2]
+  def change
+    create_table :cruft_tracker_view_renders do |t|
+      t.references :view, null: false
+      t.string :render_hash, null: false, index: true, unique: true
+      t.string :controller, null: false, index: true
+      t.string :endpoint, null: false, index: true
+      t.string :route, null: false, index: true
+      t.string :http_method, null: false, index: true
+      t.json :render_stack, null: false
+      t.integer :occurrences, null: false, index: true, default: 0
+
+      t.timestamps
+
+      t.index %i[view_id render_hash], unique: true
+    end
+  end
+end

data/db/migrate/20220705152409_create_render_metadata.rb

@@ -0,0 +1,13 @@
+class CreateRenderMetadata < ActiveRecord::Migration[5.2]
+  def change
+    create_table :cruft_tracker_render_metadata do |t|
+      t.references :view_render, null: false
+      t.string :metadata_hash, null: false
+      t.json :metadata, null: false
+      t.integer :occurrences, null: false, index: true, default: 0
+      t.timestamps
+
+      t.index :metadata_hash, unique: true
+    end
+  end
+end

data/lib/cruft_tracker/engine.rb

@@ -3,15 +3,13 @@ module CruftTracker
     isolate_namespace CruftTracker
 
     config.after_initialize do
+      ActionController::Base.helper CruftTracker::ApplicationHelper
       CruftTracker::CleanupUntrackedMethods.run!
+      CruftTracker::CleanupUntrackedViews.run!
     rescue StandardError
       # Swallow all errors to prevent initialization failures.
     end
 
-    # initializer 'cruft_tracker.action_controller' do |app|
-    #   ActiveSupport.on_load(:action_controller) do
-    #     ::ActionController::Base.helper(CruftTracker::ApplicationHelper)
-    #   end
-    # end
+
   end
 end

data/lib/cruft_tracker/version.rb

@@ -1,3 +1,3 @@
 module CruftTracker
-  VERSION = '0.1.4'
+  VERSION = '0.2.2'
 end

data/lib/cruft_tracker.rb

@@ -4,10 +4,18 @@ require 'cruft_tracker/registry'
 require 'cruft_tracker/log_suppressor'
 
 module CruftTracker
-  # Your code goes here...
+  class << self
+    attr_accessor :config
+  end
+
+  def self.init(&block)
+    self.config = Config.instance
 
-  def self.is_this_view_used?
-    puts '>>>> is this view used?'
+    self.instance_eval(&block)
+  end
+
+  def self.is_this_view_used?(view, comment: nil)
+    CruftTracker::TrackView.run!(view: view, comment: comment)
   end
 
   def self.is_this_method_used?(
@@ -29,4 +37,28 @@ module CruftTracker
   def self.are_any_of_these_methods_being_used?(owner, comment: nil)
     CruftTracker::TrackAllMethods.run!(owner: owner, comment: comment)
   end
+
+  class Config
+    include Singleton
+
+    DEFAULT_MAX_ARGUMENTS_VARIATIONS_PER_TRACKED_METHOD = 50
+    DEFAULT_MAX_BACKTRACE_VARIATIONS_PER_TRACKED_METHOD = 50
+    DEFAULT_MAX_VIEW_RENDERS_PER_VIEW = 50
+    DEFAULT_MAX_RENDER_METADATA_VARIATIONS_PER_VIEW_RENDER = 50
+
+    attr_accessor :max_argument_variations_per_tracked_method,
+                  :max_backtrace_variations_per_tracked_method,
+                  :max_view_renders_per_view,
+                  :max_render_metadata_variations_per_view_render
+
+    def initialize
+      @max_argument_variations_per_tracked_method =
+        DEFAULT_MAX_ARGUMENTS_VARIATIONS_PER_TRACKED_METHOD
+      @max_backtrace_variations_per_tracked_method =
+        DEFAULT_MAX_BACKTRACE_VARIATIONS_PER_TRACKED_METHOD
+      @max_view_renders_per_view = DEFAULT_MAX_VIEW_RENDERS_PER_VIEW
+      @max_render_metadata_variations_per_view_render =
+        DEFAULT_MAX_RENDER_METADATA_VARIATIONS_PER_VIEW_RENDER
+    end
+  end
 end

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: cruft_tracker
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.2.2
 platform: ruby
 authors:
 - Adwerx Inc.
 - Doug Hughes
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-04-25 00:00:00.000000000 Z
+date: 2022-07-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: active_interaction
@@ -235,6 +235,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 2.5.0
+- !ruby/object:Gem::Dependency
+  name: prettier
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: |
   Have you ever asked yourself, "Is this method even being used?!" Or, "What the heck is this method receiving?" Does your application use Rails? If the answers these questions are yes, this gem may be of use to you!
 
@@ -262,13 +276,21 @@ files:
 - app/models/cruft_tracker/argument.rb
 - app/models/cruft_tracker/backtrace.rb
 - app/models/cruft_tracker/method.rb
+- app/models/cruft_tracker/render_metadata.rb
+- app/models/cruft_tracker/view.rb
+- app/models/cruft_tracker/view_render.rb
 - app/services/cruft_tracker/application_service.rb
 - app/services/cruft_tracker/cleanup_untracked_methods.rb
+- app/services/cruft_tracker/cleanup_untracked_views.rb
+- app/services/cruft_tracker/increment_view_renders.rb
 - app/services/cruft_tracker/record_arguments.rb
 - app/services/cruft_tracker/record_backtrace.rb
 - app/services/cruft_tracker/record_invocation.rb
+- app/services/cruft_tracker/record_render_metadata.rb
+- app/services/cruft_tracker/record_view_render.rb
 - app/services/cruft_tracker/track_all_methods.rb
 - app/services/cruft_tracker/track_method.rb
+- app/services/cruft_tracker/track_view.rb
 - app/views/cruft_tracker/methods/index.html.erb
 - app/views/layouts/cruft_tracker/application.html.erb
 - config/routes.rb
@@ -276,6 +298,9 @@ files:
 - db/migrate/20220418133030_create_cruft_tracker_backtraces.rb
 - db/migrate/20220419171326_add_comment_to_cruft_tracker_methods.rb
 - db/migrate/20220419174055_create_cruft_tracker_arguments.rb
+- db/migrate/20220628175222_create_cruft_tracker_views.rb
+- db/migrate/20220701125925_create_cruft_tracker_view_renders.rb
+- db/migrate/20220705152409_create_render_metadata.rb
 - lib/cruft_tracker.rb
 - lib/cruft_tracker/engine.rb
 - lib/cruft_tracker/log_suppressor.rb
@@ -288,7 +313,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/AdWerx/cruft-tracker
   source_code_uri: https://github.com/AdWerx/cruft-tracker
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -303,8 +328,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
-signing_key: 
+rubygems_version: 3.1.6
+signing_key:
 specification_version: 4
 summary: Provides a system to track Ruby method usage somewhat unobtrusively.
 test_files: []