diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2019-12-14 00:07:41 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2019-12-14 00:07:41 +0300 |
commit | 0e2fc1701bd0c87cc458cbbb34c618b0e0dc5a14 (patch) | |
tree | 5f08f2602120b0555e5c0dc0061d7c8eea054c22 /doc | |
parent | 7cc6c10c68915f5019ab8c2029eeb462c8fed4ef (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc')
-rw-r--r-- | doc/development/README.md | 4 | ||||
-rw-r--r-- | doc/development/database_query_comments.md | 56 |
2 files changed, 60 insertions, 0 deletions
diff --git a/doc/development/README.md b/doc/development/README.md index 6aeaf31ed29..3a972c4c588 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -103,6 +103,10 @@ description: 'Learn how to contribute to GitLab.' - [Swapping tables](swapping_tables.md) - [Deleting migrations](deleting_migrations.md) +### Debugging + +- Tracing the source of an SQL query using query comments with [Marginalia](database_query_comments.md) + ### Best practices - [Merge Request checklist](database_merge_request_checklist.md) diff --git a/doc/development/database_query_comments.md b/doc/development/database_query_comments.md new file mode 100644 index 00000000000..c1a927ef234 --- /dev/null +++ b/doc/development/database_query_comments.md @@ -0,0 +1,56 @@ +# Database query comments with Marginalia + +The [Marginalia gem](https://github.com/basecamp/marginalia) is used to add +query comments containing application related context information to PostgreSQL +queries generated by ActiveRecord. + +It is very useful for tracing problematic queries back to the application source. + +A DB Engineer during an on-call incident will have the full context of a query +and its application source from the comments. + +## Metadata information in comments + +Queries generated from **Rails** include the following metadata in comments: + +- `application` +- `controller` +- `action` +- `correlation_id` +- `line` + +Queries generated from **Sidekiq** workers will include the following metadata +in comments: + +- `application` +- `jid` +- `job_class` +- `correlation_id` +- `line` + +Examples of queries with comments as observed in `development.log`: + +1. Rails: + + ```sql + SELECT "project_features".* FROM "project_features" WHERE "project_features"."project_id" = $1 LIMIT $2 [["project_id", 5], ["LIMIT", 1]] /*application:web,controller:jobs,action:trace,correlation_id:rYF4mey9CH3,line:/app/policies/project_policy.rb:504:in `feature_available?'*/ + ``` + +1. Sidekiq: + + ```sql + SELECT "ci_pipelines".* FROM "ci_pipelines" WHERE "ci_pipelines"."id" = $1 LIMIT $2 [["id", 64], ["LIMIT", 1]] /*application:sidekiq,jid:e7d6668a39a991e323009833,job_class:ExpireJobCacheWorker,correlation_id:rYF4mey9CH3,line:/app/workers/expire_job_cache_worker.rb:14:in `perform'*/ + ``` + +## Enable/Disable the feature + +Enabling or disabling the feature requires a **restart/SIGHUP** of the Web and +Sidekiq workers, as the feature flag's state is memoized upon starting up. + +The `feature_flag` for this feature is **disabled** by default. You can enable +or disable it with: + +```ruby +Feature.enable(:marginalia) +Feature.disable(:marginalia) +``` |