{"id":13394999,"url":"https://github.com/basecamp/marginalia","last_synced_at":"2025-05-13T19:11:40.855Z","repository":{"id":2696536,"uuid":"3689879","full_name":"basecamp/marginalia","owner":"basecamp","description":"Attach comments to ActiveRecord's SQL queries","archived":false,"fork":false,"pushed_at":"2024-08-05T02:12:32.000Z","size":206,"stargazers_count":1757,"open_issues_count":10,"forks_count":143,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-05-12T13:47:29.271Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/basecamp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-03-11T21:35:11.000Z","updated_at":"2025-05-05T23:48:32.000Z","dependencies_parsed_at":"2023-02-16T10:30:43.014Z","dependency_job_id":"eff73f21-8561-4d05-823d-f5e4be47f60e","html_url":"https://github.com/basecamp/marginalia","commit_stats":{"total_commits":206,"total_committers":52,"mean_commits":"3.9615384615384617","dds":0.7475728155339806,"last_synced_commit":"226f93234b0ca58f548c5af23e229bdf3bf15ad5"},"previous_names":["37signals/marginalia"],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basecamp%2Fmarginalia","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basecamp%2Fmarginalia/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basecamp%2Fmarginalia/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basecamp%2Fmarginalia/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/basecamp","download_url":"https://codeload.github.com/basecamp/marginalia/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253958004,"owners_count":21990544,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-30T17:01:38.737Z","updated_at":"2025-05-13T19:11:40.835Z","avatar_url":"https://github.com/basecamp.png","language":"Ruby","readme":"# marginalia [![Build Status](https://github.com/basecamp/marginalia/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/basecamp/marginalia/actions/workflows/ci.yml)\n\nAttach comments to your ActiveRecord queries. By default, it adds the application, controller, and action names as a\ncomment at the end of each query.\n\nThis helps when searching log files for queries, and seeing where slow queries came from.\n\nFor example, once enabled, your logs will look like:\n\n    Account Load (0.3ms)  SELECT `accounts`.* FROM `accounts` \n    WHERE `accounts`.`queenbee_id` = 1234567890 \n    LIMIT 1 \n    /*application:BCX,controller:project_imports,action:show*/\n\nYou can also use these query comments along with a tool like [pt-query-digest](http://www.percona.com/doc/percona-toolkit/2.1/pt-query-digest.html#query-reviews) \nto automate identification of controllers and actions that are hotspots for slow queries.\n\nThis gem was created at 37signals. You can read more about how we use it [on\nour blog](http://37signals.com/svn/posts/3130-tech-note-mysql-query-comments-in-rails).\n\nThis has been tested and used in production with the mysql2 and pg gems, and is\ntested on Rails 5.2 through 6.1, and Ruby 2.6 through 3.0. It is also tested\nfor sqlite3. **As of Rails 7, [Marginalia is a part of Rails itself](https://api.rubyonrails.org/classes/ActiveRecord/QueryLogs.html) and does not need to be separately included.**\n\nRails version support will follow supported versions in the [Ruby on Rails maintenance policy](https://guides.rubyonrails.org/maintenance_policy.html)\nand Ruby support will follow maintained versions in the [Ruby maintenance policy](https://www.ruby-lang.org/en/downloads/branches/).\n\nPatches are welcome for other database adapters. \n\n## Installation\n\n    # Gemfile\n    gem 'marginalia'\n\n### Customization\nOptionally, you can set the application name shown in the log like so in an initializer (e.g. `config/initializers/marginalia.rb`):\n\n    Marginalia.application_name = \"BCX\"\n\nThe name will default to your Rails application name.\n\n#### Components\n\nYou can also configure the components of the comment that will be appended,\nby setting `Marginalia::Comment.components`. By default, this is set to:\n\n    Marginalia::Comment.components = [:application, :controller, :action]\n\nWhich results in a comment of\n`application:#{application_name},controller:#{controller.name},action:#{action_name}`.\n\nYou can re-order or remove these components. You can also add additional\ncomment components of your desire by defining new module methods for\n`Marginalia::Comment` which return a string. For example:\n\n    module Marginalia\n      module Comment\n        def self.mycommentcomponent\n          \"TEST\"\n        end\n      end\n    end\n\n    Marginalia::Comment.components = [:application, :mycommentcomponent]\n\nWhich will result in a comment like\n`application:#{application_name},mycommentcomponent:TEST`\nThe calling controller is available to these methods via `@controller`.\n\nMarginalia ships with `:application`, `:controller`, and `:action` enabled by\ndefault. In addition, implementation is provided for:\n  * `:line` (for file and line number calling query). :line supports\n    a configuration by setting a regexp in `Marginalia::Comment.lines_to_ignore`\n    to exclude parts of the stacktrace from inclusion in the line comment.\n  * `:controller_with_namespace` to include the full classname (including namespace)\n    of the controller.\n  * `:job` to include the classname of the ActiveJob being performed.\n  * `:hostname` to include ```Socket.gethostname```.\n  * `:pid` to include current process id. \n  * `:db_host` to include the configured database hostname.\n  * `:socket` to include the configured database socket.\n  * `:database` to include the configured database name.\n\nPull requests for other included comment components are welcome.\n\n#### Prepend comments\n\nBy default marginalia appends the comments at the end of the query. Certain databases, such as MySQL will truncate\nthe query text. This is the case for slow query logs and the results of querying some InnoDB internal tables where the\nlength of the query is more than 1024 bytes.\n\nIn order to not lose the marginalia comments from your logs, you can prepend the comments using this option:\n\n    Marginalia::Comment.prepend_comment = true\n\n#### Inline query annotations\n\nIn addition to the request or job-level component-based annotations,\nMarginalia may be used to add inline annotations to specific queries using a\nblock-based API.\n\nFor example, the following code:\n\n    Marginalia.with_annotation(\"foo\") do\n      Account.where(queenbee_id: 1234567890).first\n    end\n\nwill issue this query:\n\n    Account Load (0.3ms)  SELECT `accounts`.* FROM `accounts`\n    WHERE `accounts`.`queenbee_id` = 1234567890\n    LIMIT 1\n    /*application:BCX,controller:project_imports,action:show*/ /*foo*/\n\nNesting `with_annotation` blocks will concatenate the comment strings.\n\n### Caveats\n\n#### Prepared statements\n\nBe careful when using Marginalia with prepared statements. If you use a component\nlike `request_id` then every query will be unique and so ActiveRecord will create\na new prepared statement for each potentially exhausting system resources.\n[Disable prepared statements](https://guides.rubyonrails.org/configuring.html#configuring-a-postgresql-database)\nif you wish to use components with high cardinality values.\n\n## Contributing\n\nStart by bundling and creating the test database:\n\n    bundle\n    rake db:mysql:create\n    rake db:postgresql:create\n\nThen, running `rake` will run the tests on all the database adapters (`mysql`, `mysql2`, `postgresql` and `sqlite`):\n\n    rake\n\n","funding_links":[],"categories":["Ruby","Gems","ORM/ODM Extensions"],"sub_categories":["Articles"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbasecamp%2Fmarginalia","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbasecamp%2Fmarginalia","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbasecamp%2Fmarginalia/lists"}