diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-03-13 18:09:21 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-03-13 18:09:21 +0300 |
commit | c36152ff8c41fad2f413f253eb7ac5c927e47c56 (patch) | |
tree | bbf300da207de3e8bbf272d44111ceedb18f5833 /doc/development | |
parent | 286fe61013674fe2d245ffc8d2233baf09923e70 (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc/development')
-rw-r--r-- | doc/development/api_graphql_styleguide.md | 8 | ||||
-rw-r--r-- | doc/development/logging.md | 61 | ||||
-rw-r--r-- | doc/development/migration_style_guide.md | 28 |
3 files changed, 80 insertions, 17 deletions
diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md index 7d884737f5b..9e419be9419 100644 --- a/doc/development/api_graphql_styleguide.md +++ b/doc/development/api_graphql_styleguide.md @@ -21,6 +21,12 @@ and in [PDF](https://gitlab.com/gitlab-org/create-stage/uploads/8e78ea7f326b2ef6 Everything covered in this deep dive was accurate as of GitLab 11.9, and while specific details may have changed since then, it should still serve as a good introduction. +## GraphiQL + +GraphiQL is an interactive GraphQL API explorer where you can play around with existing queries. +You can access it in any GitLab environment on `https://<your-gitlab-site.com>/-/graphql-explorer`. +For example, the one for [GitLab.com](https://gitlab.com/-/graphql-explorer). + ## Authentication Authentication happens through the `GraphqlController`, right now this @@ -335,7 +341,7 @@ field :id, GraphQL::ID_TYPE, description: 'ID of the resource' Descriptions of fields and arguments are viewable to users through: -- The [GraphiQL explorer](../api/graphql/#graphiql). +- The [GraphiQL explorer](#graphiql). - The [static GraphQL API reference](../api/graphql/#reference). ### Description styleguide diff --git a/doc/development/logging.md b/doc/development/logging.md index a90d78ba8d9..f10737da766 100644 --- a/doc/development/logging.md +++ b/doc/development/logging.md @@ -112,20 +112,57 @@ importer progresses. Here's what to do: all messages might have `current_user_id` and `project_id` to make it easier to search for activities by user for a given time. -1. Do NOT mix and match types. Elasticsearch won't be able to index your - logs properly if you [mix integer and string - types](https://www.elastic.co/guide/en/elasticsearch/guide/current/mapping.html#_avoiding_type_gotchas): +#### Implicit schema for JSON logging + +When using something like Elasticsearch to index structured logs, there is a +schema for the types of each log field (even if that schema is implicit / +inferred). It's important to be consistent with the types of your field values, +otherwise this might break the ability to search/filter on these fields, or even +cause whole log events to be dropped. While much of this section is phrased in +an Elasticsearch-specific way, the concepts should translate to many systems you +might use to index structured logs. GitLab.com uses Elasticsearch to index log +data. + +Unless a field type is explicitly mapped, Elasticsearch will infer the type from +the first instance of that field value it sees. Subsequent instances of that +field value with different types will either fail to be indexed, or in some +cases (scalar/object conflict), the whole log line will be dropped. + +GitLab.com's logging Elasticsearch sets +[`ignore_malformed`](https://www.elastic.co/guide/en/elasticsearch/reference/current/ignore-malformed.html), +which allows documents to be indexed even when there are simpler sorts of +mapping conflict (for example, number / string), although indexing on the affected fields +will break. + +Examples: - ```ruby - # BAD - logger.info(message: "Import error", error: 1) - logger.info(message: "Import error", error: "I/O failure") - ``` +```ruby +# GOOD +logger.info(message: "Import error", error_code: 1, error: "I/O failure") - ```ruby - # GOOD - logger.info(message: "Import error", error_code: 1, error: "I/O failure") - ``` +# BAD +logger.info(message: "Import error", error: 1) +logger.info(message: "Import error", error: "I/O failure") + +# WORST +logger.info(message: "Import error", error: "I/O failure") +logger.info(message: "Import error", error: { message: "I/O failure" }) +``` + +List elements must be the same type: + +```ruby +# GOOD +logger.info(a_list: ["foo", "1", "true"]) + +# BAD +logger.info(a_list: ["foo", 1, true]) +``` + +Resources: + +- [Elasticsearch mapping - avoiding type gotchas](https://www.elastic.co/guide/en/elasticsearch/guide/current/mapping.html#_avoiding_type_gotchas) +- [Elasticsearch mapping types]( https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-types.html) ## Multi-destination Logging diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index 3f202115b4c..776ac252b76 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -176,9 +176,15 @@ Removing a column: ```ruby include Gitlab::Database::MigrationHelpers -def change +def up with_lock_retries do - remove_column :users, :full_name, :string + remove_column :users, :full_name + end +end + +def down + with_lock_retries do + add_column :users, :full_name, :string end end ``` @@ -188,11 +194,17 @@ Removing a foreign key: ```ruby include Gitlab::Database::MigrationHelpers -def change +def up with_lock_retries do remove_foreign_key :issues, :projects end end + +def down + with_lock_retries do + add_foreign_key :issues, :projects + end +end ``` Changing default value for a column: @@ -200,11 +212,17 @@ Changing default value for a column: ```ruby include Gitlab::Database::MigrationHelpers -def change +def up with_lock_retries do change_column_default :merge_requests, :lock_version, from: nil, to: 0 end end + +def down + with_lock_retries do + change_column_default :merge_requests, :lock_version, from: 0, to: nil + end +end ``` ### When to use the helper method @@ -231,6 +249,8 @@ Example changes: **Note:** `with_lock_retries` method **cannot** be used with `disable_ddl_transaction!`. +**Note:** `with_lock_retries` method **cannot** be used within the `change` method, you must manually define the `up` and `down` methods to make the migration reversible. + ### How the helper method works 1. Iterate 50 times. |