diff options
| author | Ivan Blinkov <ivan@ydb.tech> | 2024-04-02 21:48:57 -0700 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2024-04-03 07:48:57 +0300 |
| commit | df9e63f1dcd8944441fb10e24a6eed82a6503e8e (patch) | |
| tree | cbaecfc654a4eaef82f0df4163a6929e6a211594 | |
| parent | 83ba1e5faf7263053823863d5fda8230f6fb9354 (diff) | |
| download | ydb-df9e63f1dcd8944441fb10e24a6eed82a6503e8e.tar.gz | |
YDB-633: continue reorganizing docs (#3353)
257 files changed, 1073 insertions, 2770 deletions
diff --git a/ydb/docs/en/core/administration/upgrade.md b/ydb/docs/en/core/administration/upgrade.md index a378f3b705d..8188ae63d09 100644 --- a/ydb/docs/en/core/administration/upgrade.md +++ b/ydb/docs/en/core/administration/upgrade.md @@ -23,7 +23,7 @@ All minor versions within a major version are compatible for updates. Major vers * X.Y.* → X.Y+2.*: Update is impossible, major versions are inconsistent. * X.Y.* → X.Y-2.*: Update is impossible, major versions are inconsistent. -A list of available versions can be found on the [download page](https://ydb.tech/en/docs/downloads/). The YDB release policy is described in more details in the [Release management](../development/manage-releases.md) article of the YDB development documentation. +A list of available versions can be found on the [download page](https://ydb.tech/en/docs/downloads/). The YDB release policy is described in more details in the [Release management](../contributor/manage-releases.md) article of the YDB development documentation. {% note warning %} diff --git a/ydb/docs/en/core/best_practices/_includes/index.md b/ydb/docs/en/core/best_practices/_includes/index.md deleted file mode 100644 index 4aa758e4b80..00000000000 --- a/ydb/docs/en/core/best_practices/_includes/index.md +++ /dev/null @@ -1,10 +0,0 @@ -# Recommendations - -This section contains articles about the purpose, specifics, and best practices of using YDB tools for app development. - -- [Choosing a primary key for maximum performance](../pk_scalability.md) -- [Secondary indexes](../secondary_indexes.md) -- [Paginated output](../paging.md) -- [Uploading large data volumes](../batch_upload.md) -- [Using timeouts](../timeouts.md) - diff --git a/ydb/docs/en/core/best_practices/_includes/schema_design.md b/ydb/docs/en/core/best_practices/_includes/schema_design.md deleted file mode 100644 index 331cf83b08c..00000000000 --- a/ydb/docs/en/core/best_practices/_includes/schema_design.md +++ /dev/null @@ -1,2 +0,0 @@ -This article has been deleted. Its content has been moved to [Impact of the primary key on performance](../pk_scalability.md). - diff --git a/ydb/docs/en/core/best_practices/_includes/table_sharding.md b/ydb/docs/en/core/best_practices/_includes/table_sharding.md deleted file mode 100644 index 57291253c34..00000000000 --- a/ydb/docs/en/core/best_practices/_includes/table_sharding.md +++ /dev/null @@ -1,2 +0,0 @@ -This article has been deleted. Its content has been moved to [Partitioning tables](../../concepts/datamodel/table.md#partitioning) in the article about data schema objects in the "Concepts" section. - diff --git a/ydb/docs/en/core/best_practices/batch_upload.md b/ydb/docs/en/core/best_practices/batch_upload.md deleted file mode 100644 index e2e399826c4..00000000000 --- a/ydb/docs/en/core/best_practices/batch_upload.md +++ /dev/null @@ -1,2 +0,0 @@ -{% include [batch_upload.md](_includes/batch_upload.md) %} - diff --git a/ydb/docs/en/core/best_practices/index.md b/ydb/docs/en/core/best_practices/index.md deleted file mode 100644 index eb2590567da..00000000000 --- a/ydb/docs/en/core/best_practices/index.md +++ /dev/null @@ -1 +0,0 @@ -{% include [_includes/index.md](_includes/index.md) %}
\ No newline at end of file diff --git a/ydb/docs/en/core/best_practices/paging.md b/ydb/docs/en/core/best_practices/paging.md deleted file mode 100644 index 93d9375281d..00000000000 --- a/ydb/docs/en/core/best_practices/paging.md +++ /dev/null @@ -1,3 +0,0 @@ - -{% include [paging.md](_includes/paging.md) %} - diff --git a/ydb/docs/en/core/best_practices/pk_scalability.md b/ydb/docs/en/core/best_practices/pk_scalability.md deleted file mode 100644 index 1cbf3a123c4..00000000000 --- a/ydb/docs/en/core/best_practices/pk_scalability.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: "Instructions for selecting a primary key for maximum performance in {{ ydb-short-name }}" -description: "This article describes general guidelines for selecting a primary key in {{ ydb-short-name }}. We review the methods of distributing the load evenly across table partitions." ---- - -{% include [pk_scalability.md](_includes/pk_scalability.md) %} diff --git a/ydb/docs/en/core/best_practices/schema_design.md b/ydb/docs/en/core/best_practices/schema_design.md deleted file mode 100644 index 18ab3a34ac4..00000000000 --- a/ydb/docs/en/core/best_practices/schema_design.md +++ /dev/null @@ -1,2 +0,0 @@ - -{% include [timeouts.md](_includes/schema_design.md) %} diff --git a/ydb/docs/en/core/best_practices/secondary_indexes.md b/ydb/docs/en/core/best_practices/secondary_indexes.md deleted file mode 100644 index 7a4630af675..00000000000 --- a/ydb/docs/en/core/best_practices/secondary_indexes.md +++ /dev/null @@ -1,3 +0,0 @@ - -{% include [secondary_indexes.md](_includes/secondary_indexes.md) %} - diff --git a/ydb/docs/en/core/best_practices/table_sharding.md b/ydb/docs/en/core/best_practices/table_sharding.md deleted file mode 100644 index 05274ea2892..00000000000 --- a/ydb/docs/en/core/best_practices/table_sharding.md +++ /dev/null @@ -1,2 +0,0 @@ - -{% include [timeouts.md](_includes/table_sharding.md) %} diff --git a/ydb/docs/en/core/best_practices/timeouts.md b/ydb/docs/en/core/best_practices/timeouts.md deleted file mode 100644 index 48cb4d6cf33..00000000000 --- a/ydb/docs/en/core/best_practices/timeouts.md +++ /dev/null @@ -1,2 +0,0 @@ - -{% include [timeouts.md](_includes/timeouts.md) %} diff --git a/ydb/docs/en/core/best_practices/toc_i.yaml b/ydb/docs/en/core/best_practices/toc_i.yaml deleted file mode 100644 index 2f92347f1a5..00000000000 --- a/ydb/docs/en/core/best_practices/toc_i.yaml +++ /dev/null @@ -1,24 +0,0 @@ -items: -- name: Overview - href: index.md -- name: Selecting a primary key for maximum performance - href: pk_scalability.md -- name: Selecting a primary key for maximum analytical table performance - href: pk-olap-scalability.md -- name: Schema design - href: schema_design.md - hidden: true -- name: Partitioning tables - href: table_sharding.md - hidden: true -- name: Secondary indexes - href: secondary_indexes.md -- name: Change Data Capture - href: cdc.md - when: feature_changefeed -- name: Paginated output - href: paging.md -- name: Uploading large data volumes - href: batch_upload.md -- name: Using timeouts - href: timeouts.md diff --git a/ydb/docs/en/core/best_practices/toc_p.yaml b/ydb/docs/en/core/best_practices/toc_p.yaml deleted file mode 100644 index 5bfec4365de..00000000000 --- a/ydb/docs/en/core/best_practices/toc_p.yaml +++ /dev/null @@ -1,2 +0,0 @@ -items: -- include: { mode: link, path: toc_i.yaml }
\ No newline at end of file diff --git a/ydb/docs/en/core/changelog-cli.md b/ydb/docs/en/core/changelog-cli.md index 0642920827b..755ce6bc019 100644 --- a/ydb/docs/en/core/changelog-cli.md +++ b/ydb/docs/en/core/changelog-cli.md @@ -137,7 +137,7 @@ Release date: May 1, 2023. To update to version **2.3.0**, select the [Downloads **Features:** * Added the interactive mode of query execution. To switch to the interactive mode, run [ydb yql](reference/ydb-cli/yql.md) without arguments. This mode is experimental: backward compatibility is not guaranteed yet. -* Added the [ydb index rename](reference/ydb-cli/commands/secondary_index.md#rename) command for [atomic replacement](best_practices/secondary_indexes.md#atomic-index-replacement) or renaming of a secondary index. +* Added the [ydb index rename](reference/ydb-cli/commands/secondary_index.md#rename) command for [atomic replacement](dba/secondary-indexes.md#atomic-index-replacement) or renaming of a secondary index. * Added the `ydb workload topic` command for generating the load that reads messages from topics and writes messages to topics. * Added the [--recursive](reference/ydb-cli/commands/dir.md#rmdir-options) option for the `ydb scheme rmdir` command. Use it to delete a directory recursively, with all its content. * Added support for the `topic` and `coordination node` types in the [ydb scheme describe](reference/ydb-cli/commands/scheme-describe.md) command. diff --git a/ydb/docs/en/core/changelog-server.md b/ydb/docs/en/core/changelog-server.md index 6536982f309..890cef609d1 100644 --- a/ydb/docs/en/core/changelog-server.md +++ b/ydb/docs/en/core/changelog-server.md @@ -154,7 +154,7 @@ Release date: May 5, 2023. To update to version 23.1, select the [Downloads](dow **Functionality:** * Added [initial table scan](concepts/cdc.md#initial-scan) when creating a CDC changefeed. Now, you can export all the data existing at the time of changefeed creation. -* Added [atomic index replacement](best_practices/secondary_indexes.md#atomic-index-replacement). Now, you can atomically replace one pre-defined index with another. This operation is absolutely transparent for your application. Indexes are replaced seamlessly, with no downtime. +* Added [atomic index replacement](dba/secondary-indexes.md#atomic-index-replacement). Now, you can atomically replace one pre-defined index with another. This operation is absolutely transparent for your application. Indexes are replaced seamlessly, with no downtime. * Added the [audit log](cluster/audit-log.md): Event stream including data about all the operations on {{ ydb-short-name }} objects. **Performance:** diff --git a/ydb/docs/en/core/cluster/index.md b/ydb/docs/en/core/cluster/index.md index 485908e4631..6ae4da5f735 100644 --- a/ydb/docs/en/core/cluster/index.md +++ b/ydb/docs/en/core/cluster/index.md @@ -5,6 +5,6 @@ This section provides information about deploying, configuring, maintaining, mon * [{#T}](../deploy/index.md). * [{#T}](../maintenance/embedded_monitoring/index.md). * [{#T}](../maintenance/manual/index.md). -* [{#T}](../troubleshooting/system_views_cluster.md). +* [{#T}](../devops/manual/system-views.md). * [{#T}](../administration/monitoring.md). * [{#T}](../administration/upgrade.md). diff --git a/ydb/docs/en/core/cluster/toc_i.yaml b/ydb/docs/en/core/cluster/toc_i.yaml index 29766fc6f98..2b4297cc9ab 100644 --- a/ydb/docs/en/core/cluster/toc_i.yaml +++ b/ydb/docs/en/core/cluster/toc_i.yaml @@ -8,7 +8,7 @@ items: - name: Embedded UI include: { mode: link, path: ../maintenance/embedded_monitoring/toc_p.yaml } - name: Cluster system views - href: ../troubleshooting/system_views_cluster.md + href: ../devops/manual/system-views.md - name: Audit log href: audit-log.md - name: Short access control notation diff --git a/ydb/docs/en/core/concepts/_includes/scan_query.md b/ydb/docs/en/core/concepts/_includes/scan_query.md index b4cba8cc41c..98fd0080dd6 100644 --- a/ydb/docs/en/core/concepts/_includes/scan_query.md +++ b/ydb/docs/en/core/concepts/_includes/scan_query.md @@ -11,7 +11,7 @@ This method of executing queries has the following unique features: {% node info %} -From the *Scan Queries* interface, you can query [system tables](../../troubleshooting/system_views_db.md). +From the *Scan Queries* interface, you can query [system tables](../../dba/system-views.md). {% endnote %} diff --git a/ydb/docs/en/core/concepts/_includes/secondary_indexes.md b/ydb/docs/en/core/concepts/_includes/secondary_indexes.md index e57ce1cf7ad..deaaca26fc0 100644 --- a/ydb/docs/en/core/concepts/_includes/secondary_indexes.md +++ b/ydb/docs/en/core/concepts/_includes/secondary_indexes.md @@ -59,5 +59,5 @@ A secondary index can be: ## Purpose and use of secondary indexes {#best_practices} -For information about the purpose and use of secondary indexes for app development, see the [recommendations](../../best_practices/secondary_indexes.md). +For information about the purpose and use of secondary indexes for app development, see the [recommendations](../../dba/secondary-indexes.md). diff --git a/ydb/docs/en/core/concepts/cdc.md b/ydb/docs/en/core/concepts/cdc.md index d4118d57ff1..bdc9c215818 100644 --- a/ydb/docs/en/core/concepts/cdc.md +++ b/ydb/docs/en/core/concepts/cdc.md @@ -243,4 +243,4 @@ You can add a changefeed to an existing table or erase it using the [ADD CHANGEF ## CDC purpose and use {#best_practices} -For information about using CDC when developing apps, see [best practices](../best_practices/cdc.md). +For information about using CDC when developing apps, see [best practices](../dba/cdc.md). diff --git a/ydb/docs/en/core/concepts/datamodel/_includes/table.md b/ydb/docs/en/core/concepts/datamodel/_includes/table.md index beb675136da..11281be52bc 100644 --- a/ydb/docs/en/core/concepts/datamodel/_includes/table.md +++ b/ydb/docs/en/core/concepts/datamodel/_includes/table.md @@ -28,7 +28,7 @@ Searching using an index allows you to swiftly locate the required rows without You can create a row-oriented table through the YDB web interface, CLI, or SDK. Regardless of the method you choose to interact with YDB, it's important to keep in mind the following rule: the table must have at least one primary key column, and it's permissible to create a table consisting solely of primary key columns. -By default, when creating a row-oriented table, all columns are optional and can have `NULL` values. This behavior can be modified by setting the `NOT NULL` conditions for key columns that are part of the primary key. Primary keys are unique, and row-oriented tables are always sorted by this key. This means that point reads by the key, as well as range queries by key or key prefix, are efficiently executed (essentially using an index). It's permissible to create a table consisting solely of key columns. When choosing a key, it's crucial to be careful, so we recommend reviewing the article: ["Choosing a Primary Key for Maximum Performance"](../../../best_practices/pk_scalability.md). +By default, when creating a row-oriented table, all columns are optional and can have `NULL` values. This behavior can be modified by setting the `NOT NULL` conditions for key columns that are part of the primary key. Primary keys are unique, and row-oriented tables are always sorted by this key. This means that point reads by the key, as well as range queries by key or key prefix, are efficiently executed (essentially using an index). It's permissible to create a table consisting solely of key columns. When choosing a key, it's crucial to be careful, so we recommend reviewing the article: ["Choosing a Primary Key for Maximum Performance"](../../../dba/primary-key/row-oriented.md). ### Partitioning row-oriented tables {#partitioning} @@ -167,9 +167,9 @@ Column-oriented {{ ydb-short-name }} tables are in the Preview mode. {% endnote %} -YDB's column-oriented tables stores data of each column separately (independently) from each other. This data storage principle is optimized for handling Online Analytical Processing (OLAP) workloads, as only the columns directly involved in the query are read during its execution. One of the key advantages of this approach is the high data compression ratios since columns often contain repetitive or similar data. A downside, however, is that operations on whole rows become more resource-intensive. +YDB's column-oriented tables store data of each column separately (independently) from each other. This data storage principle is optimized for handling Online Analytical Processing (OLAP) workloads, as only the columns directly involved in the query are read during its execution. One of the key advantages of this approach is the high data compression ratios since columns often contain repetitive or similar data. A downside, however, is that operations on whole rows become more resource-intensive. -At the moment, the main use case for YDB column-oriented tables is writing data with an increasing primary key (for example, event time), analyzing this data, and deleting outdated data based on TTL. The optimal way to add data to YDB column-oriented tables is [batch upload](../../../best_practices/batch_upload.md), performed in MB-sized blocks. Data packet insertion is atomic: data will be written either to all partitions or none. +At the moment, the main use case for YDB column-oriented tables is writing data with an increasing primary key (for example, event time), analyzing this data, and deleting outdated data based on TTL. The optimal way to add data to YDB column-oriented tables is [batch upload](../../../dev/batch-upload.md), performed in MB-sized blocks. Data packet insertion is atomic: data will be written either to all partitions or none. In most cases, working with YDB column-oriented tables is similar to working with row tables, but there are differences: * Only `NOT NULL` columns can be used as the primary key. @@ -221,7 +221,7 @@ WITH (STORE = COLUMN); Unlike data partitioning in row-oriented {{ ydb-short-name }} tables, key values are not used to partition data in column-oriented tables. This way, you can uniformly distribute data across all your existing partitions. This kind of partitioning enables you to avoid hotspots at data inserta and speeding up analytical queries that process (that is, read) large amounts of data. -How you select partitioning keys substantially affects the performance of queries to your column-oriented tables. Learn more in [{#T}](../../../best_practices/pk-olap-scalability.md). +How you select partitioning keys substantially affects the performance of queries to your column-oriented tables. Learn more in [{#T}](../../../dba/primary-key/column-oriented.md). To manage data partitioning, use the `AUTO_PARTITIONING_MIN_PARTITIONS_COUNT` additional parameter. The system ignores other partitioning parameters for column-oriented tables. diff --git a/ydb/docs/en/core/concepts/datatypes.md b/ydb/docs/en/core/concepts/datatypes.md deleted file mode 100644 index 887ba20535e..00000000000 --- a/ydb/docs/en/core/concepts/datatypes.md +++ /dev/null @@ -1,2 +0,0 @@ -This page has been deleted, for information about data types, see [YQL Data Types](../yql/reference/types/index.md). - diff --git a/ydb/docs/en/core/concepts/toc_i.yaml b/ydb/docs/en/core/concepts/toc_i.yaml index 00493dad118..eae2d485a1d 100644 --- a/ydb/docs/en/core/concepts/toc_i.yaml +++ b/ydb/docs/en/core/concepts/toc_i.yaml @@ -6,7 +6,6 @@ items: href: auth.md - name: Data model and schema include: { path: datamodel/toc_p.yaml, mode: link } -- { name: Data types, href: datatypes.md, hidden: true } # Deprecated - { name: Transactions, href: transactions.md } - { name: Secondary indexes, href: secondary_indexes.md } - { name: Change Data Capture (CDC), href: cdc.md, when: feature_changefeed } diff --git a/ydb/docs/en/core/development/_includes/corp_cli_tags.md b/ydb/docs/en/core/contributor/_includes/corp_cli_tags.md index e69de29bb2d..e69de29bb2d 100644 --- a/ydb/docs/en/core/development/_includes/corp_cli_tags.md +++ b/ydb/docs/en/core/contributor/_includes/corp_cli_tags.md diff --git a/ydb/docs/en/core/development/_includes/corp_release_stable.md b/ydb/docs/en/core/contributor/_includes/corp_release_stable.md index e69de29bb2d..e69de29bb2d 100644 --- a/ydb/docs/en/core/development/_includes/corp_release_stable.md +++ b/ydb/docs/en/core/contributor/_includes/corp_release_stable.md diff --git a/ydb/docs/en/core/development/_includes/corp_release_testing.md b/ydb/docs/en/core/contributor/_includes/corp_release_testing.md index e69de29bb2d..e69de29bb2d 100644 --- a/ydb/docs/en/core/development/_includes/corp_release_testing.md +++ b/ydb/docs/en/core/contributor/_includes/corp_release_testing.md diff --git a/ydb/docs/en/core/development/_includes/index.md b/ydb/docs/en/core/contributor/_includes/index.md index db824cd22a8..db824cd22a8 100644 --- a/ydb/docs/en/core/development/_includes/index.md +++ b/ydb/docs/en/core/contributor/_includes/index.md diff --git a/ydb/docs/en/core/development/build-ya.md b/ydb/docs/en/core/contributor/build-ya.md index 813bcb7ac27..813bcb7ac27 100644 --- a/ydb/docs/en/core/development/build-ya.md +++ b/ydb/docs/en/core/contributor/build-ya.md diff --git a/ydb/docs/en/core/development/datashard-locks-and-change-visibility.md b/ydb/docs/en/core/contributor/datashard-locks-and-change-visibility.md index bb248eba59c..bb248eba59c 100644 --- a/ydb/docs/en/core/development/datashard-locks-and-change-visibility.md +++ b/ydb/docs/en/core/contributor/datashard-locks-and-change-visibility.md diff --git a/ydb/docs/en/core/development/index.md b/ydb/docs/en/core/contributor/index.md index e7d14a405a8..e7d14a405a8 100644 --- a/ydb/docs/en/core/development/index.md +++ b/ydb/docs/en/core/contributor/index.md diff --git a/ydb/docs/en/core/development/load-actors-key-value.md b/ydb/docs/en/core/contributor/load-actors-key-value.md index e96671fac32..e96671fac32 100644 --- a/ydb/docs/en/core/development/load-actors-key-value.md +++ b/ydb/docs/en/core/contributor/load-actors-key-value.md diff --git a/ydb/docs/en/core/development/load-actors-kqp.md b/ydb/docs/en/core/contributor/load-actors-kqp.md index ba433176fff..ba433176fff 100644 --- a/ydb/docs/en/core/development/load-actors-kqp.md +++ b/ydb/docs/en/core/contributor/load-actors-kqp.md diff --git a/ydb/docs/en/core/development/load-actors-memory.md b/ydb/docs/en/core/contributor/load-actors-memory.md index 36d671fe8b7..36d671fe8b7 100644 --- a/ydb/docs/en/core/development/load-actors-memory.md +++ b/ydb/docs/en/core/contributor/load-actors-memory.md diff --git a/ydb/docs/en/core/development/load-actors-overview.md b/ydb/docs/en/core/contributor/load-actors-overview.md index 4735539480e..4735539480e 100644 --- a/ydb/docs/en/core/development/load-actors-overview.md +++ b/ydb/docs/en/core/contributor/load-actors-overview.md diff --git a/ydb/docs/en/core/development/load-actors-pdisk-log.md b/ydb/docs/en/core/contributor/load-actors-pdisk-log.md index 1ccc5a0f65a..1ccc5a0f65a 100644 --- a/ydb/docs/en/core/development/load-actors-pdisk-log.md +++ b/ydb/docs/en/core/contributor/load-actors-pdisk-log.md diff --git a/ydb/docs/en/core/development/load-actors-pdisk-read.md b/ydb/docs/en/core/contributor/load-actors-pdisk-read.md index a60414511dc..a60414511dc 100644 --- a/ydb/docs/en/core/development/load-actors-pdisk-read.md +++ b/ydb/docs/en/core/contributor/load-actors-pdisk-read.md diff --git a/ydb/docs/en/core/development/load-actors-pdisk-write.md b/ydb/docs/en/core/contributor/load-actors-pdisk-write.md index c318f6327ff..c318f6327ff 100644 --- a/ydb/docs/en/core/development/load-actors-pdisk-write.md +++ b/ydb/docs/en/core/contributor/load-actors-pdisk-write.md diff --git a/ydb/docs/en/core/development/load-actors-stop.md b/ydb/docs/en/core/contributor/load-actors-stop.md index 21def5ea141..21def5ea141 100644 --- a/ydb/docs/en/core/development/load-actors-stop.md +++ b/ydb/docs/en/core/contributor/load-actors-stop.md diff --git a/ydb/docs/en/core/development/load-actors-storage.md b/ydb/docs/en/core/contributor/load-actors-storage.md index b36d6354c38..b36d6354c38 100644 --- a/ydb/docs/en/core/development/load-actors-storage.md +++ b/ydb/docs/en/core/contributor/load-actors-storage.md diff --git a/ydb/docs/en/core/development/load-actors-vdisk.md b/ydb/docs/en/core/contributor/load-actors-vdisk.md index d63fe9dbdf0..d63fe9dbdf0 100644 --- a/ydb/docs/en/core/development/load-actors-vdisk.md +++ b/ydb/docs/en/core/contributor/load-actors-vdisk.md diff --git a/ydb/docs/en/core/development/localdb-uncommitted-txs.md b/ydb/docs/en/core/contributor/localdb-uncommitted-txs.md index f3ad2636b60..f3ad2636b60 100644 --- a/ydb/docs/en/core/development/localdb-uncommitted-txs.md +++ b/ydb/docs/en/core/contributor/localdb-uncommitted-txs.md diff --git a/ydb/docs/en/core/development/manage-releases.md b/ydb/docs/en/core/contributor/manage-releases.md index a467d2aa7f4..a467d2aa7f4 100644 --- a/ydb/docs/en/core/development/manage-releases.md +++ b/ydb/docs/en/core/contributor/manage-releases.md diff --git a/ydb/docs/en/core/development/suggest-change.md b/ydb/docs/en/core/contributor/suggest-change.md index 448d49fd8e8..448d49fd8e8 100644 --- a/ydb/docs/en/core/development/suggest-change.md +++ b/ydb/docs/en/core/contributor/suggest-change.md diff --git a/ydb/docs/en/core/development/toc_i.yaml b/ydb/docs/en/core/contributor/toc_i.yaml index 087cbe06685..087cbe06685 100644 --- a/ydb/docs/en/core/development/toc_i.yaml +++ b/ydb/docs/en/core/contributor/toc_i.yaml diff --git a/ydb/docs/en/core/db/toc_p.yaml b/ydb/docs/en/core/contributor/toc_p.yaml index 94ce1108684..94ce1108684 100644 --- a/ydb/docs/en/core/db/toc_p.yaml +++ b/ydb/docs/en/core/contributor/toc_p.yaml diff --git a/ydb/docs/en/core/db/_includes/cloud_remark.md b/ydb/docs/en/core/db/_includes/cloud_remark.md deleted file mode 100644 index b56e3099144..00000000000 --- a/ydb/docs/en/core/db/_includes/cloud_remark.md +++ /dev/null @@ -1,2 +0,0 @@ -YDB cloud services provide self-service tools for creating, modifying, and deleting databases. Documentation for these features is available as part of the documentation for the respective cloud services. - diff --git a/ydb/docs/en/core/db/index.md b/ydb/docs/en/core/db/index.md deleted file mode 100644 index 395e7166132..00000000000 --- a/ydb/docs/en/core/db/index.md +++ /dev/null @@ -1,8 +0,0 @@ -# Managing databases - -This section contains articles describing YDB tools for database management and maintenance intended for SREs and application developers and administrators. - -{% include [cloud_remark.md](_includes/cloud_remark.md) %} - -In YDB non-cloud configurations, the operations for creating, modifying, and deleting databases are run by cluster administrators. For operation descriptions, see [Managing a cluster](../cluster/index.md). - diff --git a/ydb/docs/en/core/db/toc_i.yaml b/ydb/docs/en/core/db/toc_i.yaml deleted file mode 100644 index 0657e8201ad..00000000000 --- a/ydb/docs/en/core/db/toc_i.yaml +++ /dev/null @@ -1,8 +0,0 @@ -items: -- name: Backup and recovery - href: ../maintenance/backup_and_recovery.md -- name: Diagnostics - hidden: true - include: { mode: link, path: ../troubleshooting/toc_p.yaml } -- name: DB system views - href: ../troubleshooting/system_views_db.md diff --git a/ydb/docs/en/core/maintenance/_includes/backup_and_recovery/cli_overlay.md b/ydb/docs/en/core/dba/_includes/backup_and_recovery/cli_overlay.md index e69de29bb2d..e69de29bb2d 100644 --- a/ydb/docs/en/core/maintenance/_includes/backup_and_recovery/cli_overlay.md +++ b/ydb/docs/en/core/dba/_includes/backup_and_recovery/cli_overlay.md diff --git a/ydb/docs/en/core/maintenance/_includes/backup_and_recovery/options_overlay.md b/ydb/docs/en/core/dba/_includes/backup_and_recovery/options_overlay.md index e69de29bb2d..e69de29bb2d 100644 --- a/ydb/docs/en/core/maintenance/_includes/backup_and_recovery/options_overlay.md +++ b/ydb/docs/en/core/dba/_includes/backup_and_recovery/options_overlay.md diff --git a/ydb/docs/en/core/maintenance/_includes/backup_and_recovery/others_overlay.md b/ydb/docs/en/core/dba/_includes/backup_and_recovery/others_overlay.md index e69de29bb2d..e69de29bb2d 100644 --- a/ydb/docs/en/core/maintenance/_includes/backup_and_recovery/others_overlay.md +++ b/ydb/docs/en/core/dba/_includes/backup_and_recovery/others_overlay.md diff --git a/ydb/docs/en/core/maintenance/backup_and_recovery.md b/ydb/docs/en/core/dba/backup-and-recovery.md index ca7693f102e..ca7693f102e 100644 --- a/ydb/docs/en/core/maintenance/backup_and_recovery.md +++ b/ydb/docs/en/core/dba/backup-and-recovery.md diff --git a/ydb/docs/en/core/best_practices/cdc.md b/ydb/docs/en/core/dba/cdc.md index 80ad1f79f8c..3d007e3b216 100644 --- a/ydb/docs/en/core/best_practices/cdc.md +++ b/ydb/docs/en/core/dba/cdc.md @@ -8,7 +8,7 @@ CDC is represented as a data schema object: a changefeed that can be added to a ## Reading data from a topic {#read} -You can read data using an [SDK](../reference/ydb-sdk/) or the [{{ ydb-short-name }} CLI](../reference/ydb-cli/). As with any other data schema object, you can access a changefeed using its path that has the following format: +You can read data using an [SDK](../reference/ydb-sdk/index.md) or the [{{ ydb-short-name }} CLI](../reference/ydb-cli/index.md). As with any other data schema object, you can access a changefeed using its path that has the following format: ```txt path/to/table/changefeed_name diff --git a/ydb/docs/en/core/operations/manage-users-attr.md b/ydb/docs/en/core/dba/custom-attributes.md index 581a3af76a4..581a3af76a4 100644 --- a/ydb/docs/en/core/operations/manage-users-attr.md +++ b/ydb/docs/en/core/dba/custom-attributes.md diff --git a/ydb/docs/en/core/dba/index.md b/ydb/docs/en/core/dba/index.md new file mode 100644 index 00000000000..25d33821901 --- /dev/null +++ b/ydb/docs/en/core/dba/index.md @@ -0,0 +1,14 @@ +# {{ ydb-short-name }} for Database Administrators (DBA) + +This section of {{ ydb-short-name }} documentation covers everything you need to know to properly manage contents of {{ ydb-short-name}} databases: [tables](../concepts/datamodel/table.md), [topics](../concepts/topic.md), and other entities. + +The creation and management of databases are out of the scope of this section because in {{ ydb-short-name }} clusters these operations are either [executed by DevOps Engineers](../devops/index.md) or automated externally if you are using a managed service. + +- [Backup and recovery](backup-and-recovery.md) +- Choosing a primary key for: + - [Row-oriented tables](primary-key/row-oriented.md) + - [Column-oriented tables](primary-key/column-oriented.md) +- [Secondary indices](secondary-indexes.md) +- [Change Data Capture](cdc.md) +- [Database system views](system-views.md) +- [Custom attributes](custom-attributes.md) diff --git a/ydb/docs/en/core/best_practices/pk-olap-scalability.md b/ydb/docs/en/core/dba/primary-key/column-oriented.md index 67a62060611..2e705258d7b 100644 --- a/ydb/docs/en/core/best_practices/pk-olap-scalability.md +++ b/ydb/docs/en/core/dba/primary-key/column-oriented.md @@ -20,4 +20,4 @@ Column-oriented tables do not support automatic repartitioning at the moment. Th Example: -When your data stream is 1 GB per second, an analytical table with 1,000 partitions is an optimal choice. Nevertheless, it is not advisable to create tables with an excessive number of partitions: this could raise resource consumption in the cluster and negatively impact the query rate. +When your data stream is 1 GB per second, an analytical table with 1,000 partitions is an optimal choice. Nevertheless, it is not advisable to create tables with an excessive number of partitions: this could raise resource consumption in the cluster and negatively impact the query rate.
\ No newline at end of file diff --git a/ydb/docs/en/core/dba/primary-key/index.md b/ydb/docs/en/core/dba/primary-key/index.md new file mode 100644 index 00000000000..a71756d94f7 --- /dev/null +++ b/ydb/docs/en/core/dba/primary-key/index.md @@ -0,0 +1,6 @@ +# Choosing a primary key + +The recommendations for choosing a proper primary key for a table depend on its type: + +- [Row-oriented tables](row-oriented.md) +- [Column-oriented tables](column-oriented.md)
\ No newline at end of file diff --git a/ydb/docs/en/core/best_practices/_includes/pk_scalability.md b/ydb/docs/en/core/dba/primary-key/row-oriented.md index 4d6142b2ca8..f217287c5ff 100644 --- a/ydb/docs/en/core/best_practices/_includes/pk_scalability.md +++ b/ydb/docs/en/core/dba/primary-key/row-oriented.md @@ -44,4 +44,4 @@ In {{ ydb-short-name }}, all columns, including key ones, may contain a NULL val ## Row size limit {#limit-string} -To achieve high performance, we don't recommend writing rows larger than 8 MB and key columns larger than 2 KB to the DB. +To achieve high performance, we don't recommend writing rows larger than 8 MB and key columns larger than 2 KB to the DB.
\ No newline at end of file diff --git a/ydb/docs/en/core/dba/primary-key/toc_p.yaml b/ydb/docs/en/core/dba/primary-key/toc_p.yaml new file mode 100644 index 00000000000..ec46c2af983 --- /dev/null +++ b/ydb/docs/en/core/dba/primary-key/toc_p.yaml @@ -0,0 +1,7 @@ +items: +- name: Overview + href: index.md +- name: Row-oriented + href: row-oriented.md +- name: Column-oriented + href: column-oriented.md
\ No newline at end of file diff --git a/ydb/docs/en/core/operations/crud.md b/ydb/docs/en/core/dba/query-plans-optimization.md index 3667a042788..3667a042788 100644 --- a/ydb/docs/en/core/operations/crud.md +++ b/ydb/docs/en/core/dba/query-plans-optimization.md diff --git a/ydb/docs/en/core/best_practices/_includes/secondary_indexes.md b/ydb/docs/en/core/dba/secondary-indexes.md index 982a60f5843..86098f4ad4d 100644 --- a/ydb/docs/en/core/best_practices/_includes/secondary_indexes.md +++ b/ydb/docs/en/core/dba/secondary-indexes.md @@ -1,6 +1,6 @@ # Secondary indexes -[Indexes]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Индекс_(базы_данных)){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Database_index){% endif %} are auxiliary structures within databases that help find data by certain criteria without having to search an entire database, and retrieve sorted samples without actually sorting, which would require processing the entire dataset. +[Indexes](https://en.wikipedia.org/wiki/Database_index) are auxiliary structures within databases that help find data by certain criteria without having to search an entire database, and retrieve sorted samples without actually sorting, which would require processing the entire dataset. Data in a YDB table is always sorted by the primary key. That means that retrieving any entry from the table with specified field values comprising the primary key always takes the minimum fixed time, regardless of the total number of table entries. Indexing by the primary key makes it possible to retrieve any consecutive range of entries in ascending or descending order of the primary key. Execution time for this operation depends only on the number of retrieved entries rather than on the total number of table records. @@ -8,13 +8,13 @@ To use a similar feature with any field or combination of fields, additional ind In transactional systems, indexes are used to limit or avoid performance degradation and increase of query cost as your data grows. -This article describes the main operations with secondary indexes and gives references to detailed information on each operation. For more information about various types of secondary indexes and their specifics, see [Secondary indexes](../../concepts/secondary_indexes.md) in the Concepts section. +This article describes the main operations with secondary indexes and gives references to detailed information on each operation. For more information about various types of secondary indexes and their specifics, see [Secondary indexes](../concepts/secondary_indexes.md) in the Concepts section. ## Creating secondary indexes {#create} -A secondary index is a data schema object that can be defined when creating a table with the [`CREATE TABLE` YQL command](../../yql/reference/syntax/create_table.md) or added to it later with the [`ALTER TABLE` YQL command](../../yql/reference/syntax/alter_table.md). +A secondary index is a data schema object that can be defined when creating a table with the [`CREATE TABLE` YQL command](../yql/reference/syntax/create_table.md) or added to it later with the [`ALTER TABLE` YQL command](../yql/reference/syntax/alter_table.md). -The [`table index add` command](../../reference/ydb-cli/commands/secondary_index.md#add) is supported in the YDB CLI. +The [`table index add` command](../reference/ydb-cli/commands/secondary_index.md#add) is supported in the YDB CLI. Since an index contains its own data derived from table data, when creating an index on an existing table with data, an operation is performed to initially build an index. This may take a long time. This operation is executed in the background and you can keep working with the table while it's in progress. However, you can't use the new index until it's build is completed. @@ -33,7 +33,7 @@ Considering the above, there's no use in pre-indexing all possible combinations ## Using secondary indexes when selecting data {#use} -For a table to be accessed by a secondary index, its name must be explicitly specified in the `VIEW` section after the table name as described in the article about the YQL [`SELECT` statement](../../yql/reference/syntax/select#secondary_index). For example, a query to retrieve orders from the `orders` table by the specified customer ID (`id_customer`) looks like this: +For a table to be accessed by a secondary index, its name must be explicitly specified in the `VIEW` section after the table name as described in the article about the YQL [`SELECT` statement](../yql/reference/syntax/select#secondary_index). For example, a query to retrieve orders from the `orders` table by the specified customer ID (`id_customer`) looks like this: ```sql DECLARE $customer_id AS Uint64; @@ -44,9 +44,9 @@ WHERE o.id_customer = $customer_id Where `idx_customer` is the name of the secondary index on the `orders` table with the `id_customer` field specified first. -If no `VIEW` section is specified, making a query like this results in a full scan of the `orders` table . +If no `VIEW` section is specified, making a query like this results in a full scan of the `orders` table. -In transactional applications, such information queries are executed with paginated data output. This eliminates an increase in the cost and time of query execution if the number of entries that meet the filtering conditions grows. The described approach to writing [paginated queries](../paging.md) using the primary key can also be applied to columns that are part of a secondary index. +In transactional applications, such information queries are executed with paginated data output. This eliminates an increase in the cost and time of query execution if the number of entries that meet the filtering conditions grows. The described approach to writing [paginated queries](../dev/paging.md) using the primary key can also be applied to columns that are part of a secondary index. ## Checking the cost of queries {#cost} @@ -56,7 +56,7 @@ If you use the YDB CLI, select the `--stats` option to enable printing statistic ## Updating data using a secondary index {#update} -The [`UPDATE`](../../yql/reference/syntax/update.md), [`UPSERT`](../../yql/reference/syntax/upsert_into.md), and [`REPLACE`](../../yql/reference/syntax/replace_into.md) YQL statements don't permit specifying a secondary index to perform a search for data, so an attempt to make an `UPDATE ... WHERE indexed_field = $value` will result in a full scan of the table. To avoid this, you can first run `SELECT` by index to get the primary key value and then `UPDATE` by the primary key. You can also use `UPDATE ON`. +The [`UPDATE`](../yql/reference/syntax/update.md), [`UPSERT`](../yql/reference/syntax/upsert_into.md), and [`REPLACE`](../yql/reference/syntax/replace_into.md) YQL statements don't permit specifying a secondary index to perform a search for data, so an attempt to make an `UPDATE ... WHERE indexed_field = $value` will result in a full scan of the table. To avoid this, you can first run `SELECT` by index to get the primary key value and then `UPDATE` by the primary key. You can also use `UPDATE ON`. To update data in the `table1` table, run the query: @@ -84,14 +84,14 @@ WHERE views = 0; ## Atomic replacement of a secondary index {#atomic-index-replacement} -You can atomically replace a secondary index. This can be useful if you want your index to become [covering](../../concepts/secondary_indexes.md#covering). This operation is totally transparent for your running applications: when you replace the index, the compiled queries are invalidated. +You can atomically replace a secondary index. This can be useful if you want your index to become [covering](../concepts/secondary_indexes.md#covering). This operation is totally transparent for your running applications: when you replace the index, the compiled queries are invalidated. -To replace an existing index atomically, use the YDB CLI command [{{ ydb-cli }} table index rename](../../reference/ydb-cli/commands/secondary_index.md#rename) with the `--replace` parameter. +To replace an existing index atomically, use the YDB CLI command [{{ ydb-cli }} table index rename](../reference/ydb-cli/commands/secondary_index.md#rename) with the `--replace` parameter. ## Performance of data writes to tables with secondary indexes {#write_performance} You need additional data structures to enable secondary indexes. Support for these structures makes table data update operations more costly. -During synchronous index updates, a transaction is only committed after all the necessary data is written in both a table and synchronous indexes. As a result, it takes longer to execute it and makes it necessary to use [distributed transactions](../../concepts/transactions#distributed-tx) even if adding or updating entries in a single partition. +During synchronous index updates, a transaction is only committed after all the necessary data is written in both a table and synchronous indexes. As a result, it takes longer to execute it and makes it necessary to use [distributed transactions](../concepts/transactions.md#distributed-tx) even if adding or updating entries in a single partition. Indexes that are updated asynchronously let you use single-shard transactions. However, they only guarantee eventual consistency and still put a load on the database. diff --git a/ydb/docs/en/core/dba/system-views.md b/ydb/docs/en/core/dba/system-views.md new file mode 100644 index 00000000000..d2eca07c2b5 --- /dev/null +++ b/ydb/docs/en/core/dba/system-views.md @@ -0,0 +1,303 @@ +# Database system views + +You can make queries to special service tables (system views) to monitor the DB status. These tables are accessible from the root of the database tree and use the `.sys` system path prefix. + +You can find the corresponding table's primary key field index in the descriptions of available fields below. + +DB system views contain: + +* [Details of individual DB table partitions](#partitions). +* [Top queries by certain characteristics](#top-queries). +* [Query details](#query-metrics). +* [History of overloaded partitions](#top-overload-partitions). + +{% note info %} + +Loads caused by accessing system views are more analytical in nature. Making frequent queries to them in large DBs will consume a lot of system resources. The recommended load is no more than 1-2 RPS. + +{% endnote %} + +## Partitions {#partitions} + +The following system view stores detailed information about individual [partitions](../concepts/datamodel/table.md#partitioning) of all DB tables: + +* `partition_stats`: Contains information about instant metrics and cumulative operation counters. Instant metrics are, for example, CPU load or count of in-flight [transactions](../concepts/transactions.md). Cumulative counters, for example, count the total number of rows read. + +The system view is designed to detect various irregularities in the load on a table partition or show the size of table partition data. + +Cumulative fields (`RowReads`, `RowUpdates`, and so on) store the accumulated values since the last start of the tablet serving the partition. + +Table structure: + +| Field | Description | +--- | --- +| `OwnerId` | ID of the SchemeShard serving the table.<br>Type: `Uint64`.<br>Key: `0`. | +| `PathId` | ID of the SchemeShard path.<br>Type: `Uint64`.<br>Key: `1`. | +| `PartIdx` | Partition sequence number.<br>Type: `Uint64`.<br>Key: `2`. | +| `DataSize` | Approximate partition size in bytes.<br>Type: `Uint64`. | +| `RowCount` | Approximate number of rows.<br>Type: `Uint64`. | +| `IndexSize` | Partition index size in a tablet.<br>Type: `Uint64`. | +| `CPUCores` | Double Instant value of load per partition (CPU share) | +| `TabletId` | ID of the tablet serving the partition.<br>Type: `Uint64`. | +| `Path` | Full path to the table.<br>Type: `Utf8`. | +| `NodeId` | ID of the node that the partition is being served on.<br>Type: `Uint32`. | +| `StartTime` | Last time when the tablet serving the partition was started.<br>Type: `Timestamp`. | +| `AccessTime` | Last time when data from the partition was read.<br>Type: `Timestamp`. | +| `UpdateTime` | Last time when data was written to the partition.<br>Type: `Timestamp`. | +| `RowReads` | Number of point reads since the start of the partition tablet.<br>Type: `Uint64`. | +| `RowUpdates` | Number of rows written since the start.<br>Type: `Uint64`. | +| `RowDeletes` | Number of rows deleted since the start.<br>Type: `Uint64`. | +| `RangeReads` | Number of row range reads since the start.<br>Type: `Uint64`. | +| `RangeReadRows` | Number of rows read in the ranges since the start.<br>Type: `Uint64`. | +| `InFlightTxCount` | Number of in-flight transactions.<br>Type: `Uint64`. | +| `ImmediateTxCompleted` | Number of one-shard transactions completed since the start.<br>Type: `Uint64`. | +| `CoordinatedTxCompleted` | Number of coordinated transactions completed since the start.<br>Type: `Uint64`. | +| `TxRejectedByOverload` | Number of transactions rejected due to overload (since the start).<br>Type: `Uint64`. | +| `TxRejectedByOutOfStorage` | Number of transactions rejected due to lack of storage space (since the start).<br>Type: `Uint64`. | + +### Example queries + +Top 5 of most loaded partitions among all DB tables: + +```sql +SELECT + Path, + PartIdx, + CPUCores +FROM `.sys/partition_stats` +ORDER BY CPUCores DESC +LIMIT 5 +``` + +List of DB tables with in-flight sizes and loads: + +```sql +SELECT + Path, + COUNT(*) as Partitions, + SUM(RowCount) as Rows, + SUM(DataSize) as Size, + SUM(CPUCores) as CPU +FROM `.sys/partition_stats` +GROUP BY Path +``` + +## Top queries {#top-queries} + +The following system views store data for analyzing the flow of user queries: + +* `top_queries_by_duration_one_minute`: Data is split into one-minute intervals, contains Top 5 queries with the maximum total execution time for the last 6 hours. +* `top_queries_by_duration_one_hour`: Data is split into one-hour intervals, contains Top 5 queries with the maximum total execution time for the last 2 weeks. +* `top_queries_by_read_bytes_one_minute`: Data is split into one-minute intervals, contains Top 5 queries with the maximum number of bytes read from the table for the last 6 hours. +* `top_queries_by_read_bytes_one_hour`: Data is split into one-hour intervals, contains Top 5 queries with the maximum number of bytes read from the table for the last 2 weeks. +* `top_queries_by_cpu_time_one_minute`: Data is split into one-minute intervals, contains Top 5 queries with the maximum CPU time used for the last 6 hours. +* ` top_queries_by_cpu_time_one_hour`: Data is split into one-hour intervals, contains Top 5 queries with the maximum CPU time used for the last 2 weeks. + +Different runs of a query with the same text are deduplicated. The top list contains information about a specific run with the maximum value of the corresponding query metric within a single interval. + +Fields that provide information about the used CPU time (...`CPUTime`) are expressed in microseconds. + +Query text limit is 4 KB. + +All tables have the same set of fields: + +| Field | Description | +--- | --- +| `IntervalEnd` | The end of a one-minute or one-hour interval.<br>Type: `Timestamp`.<br>Key: `0`. | +| `Rank` | Rank of a top query.<br>Type: `Uint32`.<br>Key: `1`. | +| `QueryText` | Query text.<br>Type: `Utf8`. | +| `Duration` | Total query execution time.<br>Type: `Interval`. | +| `EndTime` | Query execution end time. <br>Type: `Timestamp`. | +| `Type` | Query type (data, scan, or script).<br>Type: `String`. | +| `ReadRows` | Number of rows read.<br>Type: `Uint64`. | +| `ReadBytes` | Number of bytes read.<br>Type: `Uint64`. | +| `UpdateRows` | Number of rows written.<br>Type: `Uint64`. | +| `UpdateBytes` | Number of bytes written.<br>Type: `Uint64`. | +| `DeleteRows` | Number of rows deleted.<br>Type: `Uint64`. | +| `DeleteBytes` | Number of bytes deleted.<br>Type: `Uint64`. | +| `Partitions` | Number of table partitions used during query execution.<br>Type: `Uint64`. | +| `UserSID` | User Security ID.<br>Type: `String`. | +| `ParametersSize` | Size of query parameters in bytes.<br>Type: `Uint64`. | +| `CompileDuration` | Duration of query compilation.<br>Type: `Interval`. | +| `FromQueryCache` | Shows whether the cache of prepared queries was used.<br>Type: `Bool`. | +| `CPUTime` | Total CPU time used to execute the query (microseconds).<br>Type: `Uint64`. | +| `ShardCount` | Number of shards used during query execution.<br>Type: `Uint64`. | +| `SumShardCPUTime` | Total CPU time used in shards.<br>Type: `Uint64`. | +| `MinShardCPUTime` | Minimum CPU time used in shards.<br>Type: `Uint64`. | +| `MaxShardCPUTime` | Maximum CPU time used in shards.<br>Type: `Uint64`. | +| `ComputeNodesCount` | Number of compute nodes used during query execution.<br>Type: `Uint64`. | +| `SumComputeCPUTime` | Total CPU time used in compute nodes.<br>Type: `Uint64`. | +| `MinComputeCPUTime` | Minimum CPU time used in compute nodes.<br>Type: `Uint64`. | +| `MaxComputeCPUTime` | Maximum CPU time used in compute nodes.<br>Type: `Uint64`. | +| `CompileCPUTime` | CPU time used to compile a query.<br>Type: `Uint64`. | +| `ProcessCPUTime` | CPU time used for overall query handling.<br>Type: `Uint64`. | + +### Example queries + +Top queries by execution time for the last minute when queries were made: + +```sql +PRAGMA AnsiInForEmptyOrNullableItemsCollections; +$last = ( + SELECT + MAX(IntervalEnd) + FROM `.sys/top_queries_by_duration_one_minute` +); +SELECT + IntervalEnd, + Rank, + QueryText, + Duration +FROM `.sys/top_queries_by_duration_one_minute` +WHERE IntervalEnd IN $last +``` + +Queries that read the most bytes, broken down by minute: + +```sql +SELECT + IntervalEnd, + QueryText, + ReadBytes, + ReadRows, + Partitions +FROM `.sys/top_queries_by_read_bytes_one_minute` +WHERE Rank = 1 +``` + +## Query details {#query-metrics} + +The following system view stores detailed information about queries: + +* `query_metrics_one_minute`: Data is split into one-minute intervals, contains up to 256 queries for the last 6 hours. + +Each table row contains information about a set of queries with identical text that were made during one minute. The table fields provide the minimum, maximum, and total values for each query metric tracked. Within the interval, queries are sorted in descending order of the total CPU time used. + +Restrictions: + +* Query text limit is 4 KB. +* Statistics may be incomplete if the database is under heavy load. + +Table structure: + +| Field | Description | +---|--- +| `IntervalEnd` | The end of a one-minute interval.<br>Type: `Timestamp`.<br>Key: `0`. | +| `Rank` | Query rank within an interval (by the SumCPUTime field).<br>Type: `Uint32`.<br>Key: `1`. | +| `QueryText` | Query text.<br>Type: `Utf8`. | +| `Count` | Number of query runs.<br>Type: `Uint64`. | +| `SumDuration` | Total duration of queries.<br>Type: `Interval`. | +| `Count` | Number of query runs.<br>Type: `Uint64`. | +| `SumDuration` | Total duration of queries.<br>Type: `Interval`. | +| `MinDuration` | Minimum query duration.<br>Type: `Interval`. | +| `MaxDuration` | Maximum query duration.<br>Type: `Interval`. | +| `SumCPUTime` | Total CPU time used.<br>Type: `Uint64`. | +| `MinCPUTime` | Minimum CPU time used.<br>Type: `Uint64`. | +| `MaxCPUTime` | Maximum CPU time used.<br>Type: `Uint64`. | +| `SumReadRows` | Total number of rows read.<br>Type: `Uint64`. | +| `MinReadRows` | Minimum number of rows read.<br>Type: `Uint64`. | +| `MaxReadRows` | Maximum number of rows read.<br>Type: `Uint64`. | +| `SumReadBytes` | Total number of bytes read.<br>Type: `Uint64`. | +| `MinReadBytes` | Minimum number of bytes read.<br>Type: `Uint64`. | +| `MaxReadBytes` | Maximum number of bytes read.<br>Type: `Uint64`. | +| `SumUpdateRows` | Total number of rows written.<br>Type: `Uint64`. | +| `MinUpdateRows` | Minimum number of rows written.<br>Type: `Uint64`. | +| `MaxUpdateRows` | Maximum number of rows written.<br>Type: `Uint64`. | +| `SumUpdateBytes` | Total number of bytes written.<br>Type: `Uint64`. | +| `MinUpdateBytes` | Minimum number of bytes written.<br>Type: `Uint64`. | +| `MaxUpdateBytes` | Maximum number of bytes written.<br>Type: `Uint64`. | +| `SumDeleteRows` | Total number of rows deleted.<br>Type: `Uint64`. | +| `MinDeleteRows` | Minimum number of rows deleted.<br>Type: `Uint64`. | +| `MaxDeleteRows` | Maximum number of rows deleted.<br>Type: `Uint64`. | + + +### Example queries + +Top 10 queries for the last 6 hours by the total number of rows updated per minute: + +```sql +SELECT + SumUpdateRows, + Count, + QueryText, + IntervalEnd +FROM `.sys/query_metrics_one_minute` +ORDER BY SumUpdateRows DESC LIMIT 10 +``` + +Recent queries that read the most bytes per minute: + +```sql +SELECT + IntervalEnd, + SumReadBytes, + MinReadBytes, + SumReadBytes / Count as AvgReadBytes, + MaxReadBytes, + QueryText +FROM `.sys/query_metrics_one_minute` +WHERE SumReadBytes > 0 +ORDER BY IntervalEnd DESC, SumReadBytes DESC +LIMIT 100 +``` + +## History of overloaded partitions {#top-overload-partitions} + +The following system views (tables) store the history of points in time when the load on individual DB table partitions was high: + +* `top_partitions_one_minute`: The data is split into one-minute intervals, contains the history for the last 6 hours. +* `top_partitions_one_hour`: The data is split into one-hour intervals, contains the history for the last 2 weeks. + +These tables contain partitions with peak loads of more than 70% (`CPUCores` > 0.7). Partitions within a single interval are ranked by peak load value. + +Both tables have the same set of fields: + +| Field | Description | +--- | --- +| `IntervalEnd` | The end of a one-minute or one-hour interval.<br>Type: `Timestamp`.<br>Key: `0`. | +| `Rank` | Partition rank within an interval (by CPUCores).<br>Type: `Uint32`.<br>Key: `1`. | +| `TabletId` | ID of the tablet serving the partition.<br>Type: `Uint64`. | +| `Path` | Full path to the table.<br>Type: `Utf8`. | +| `PeakTime` | Peak time within an interval.<br>Type: `Timestamp`. | +| `CPUCores` | Peak load per partition (CPU share).<br>Type: `Double`. | +| `NodeId` | ID of the node where the partition was located during the peak load.<br>Type: `Uint32`. | +| `DataSize` | Approximate partition size, in bytes, during the peak load.<br>Type: `Uint64`. | +| `RowCount` | Approximate row count during the peak load.<br>Type: `Uint64`. | +| `IndexSize` | Partition index size per tablet during the peak load.<br>Type: `Uint64`. | +| `InFlightTxCount` | The number of in-flight transactions during the peak load.<br>Type: `Uint32`. | + +### Example queries + +The following query returns partitions with CPU usage of more than 70% in the specified interval, with tablet IDs and sizes as of the time when the percentage was exceeded. The query is made to the `.sys/top_partitions_one_minute` table with data over the last six hours split into one-minute intervals: + +```sql +SELECT + IntervalEnd, + CPUCores, + Path, + TabletId, + DataSize +FROM `.sys/top_partitions_one_minute` +WHERE CPUCores > 0.7 +AND IntervalEnd BETWEEN Timestamp("YYYY-MM-DDThh:mm:ss.uuuuuuZ") AND Timestamp("YYYY-MM-DDThh:mm:ss.uuuuuuZ") +ORDER BY IntervalEnd desc, CPUCores desc +``` + +* `"YYYY-MM-DDTHH:MM:SS.UUUUUUZ"`: Time in the UTC 0 zone (`YYYY` stands for year, `MM`, for month, `DD`, for date, `hh`, for hours, `mm`, for minutes, `ss`, for seconds, and `uuuuuu`, for microseconds). For example, `"2023-01-26T13:00:00.000000Z"`. + +The following query returns partitions with CPU usage of over 90% in the specified interval, with tablet IDs and sizes as of the time when the percentage was exceeded. The query is made to the `.sys/top_partitions_one_hour` table with data over the last two weeks split into one-hour intervals: + +```sql +SELECT + IntervalEnd, + CPUCores, + Path, + TabletId, + DataSize +FROM `.sys/top_partitions_one_hour` +WHERE CPUCores > 0.9 +AND IntervalEnd BETWEEN Timestamp("YYYY-MM-DDThh:mm:ss.uuuuuuZ") AND Timestamp("YYYY-MM-DDThh:mm:ss.uuuuuuZ") +ORDER BY IntervalEnd desc, CPUCores desc +``` + +* `"YYYY-MM-DDTHH:MM:SS.UUUUUUZ"`: Time in the UTC 0 zone (`YYYY` stands for year, `MM`, for month, `DD`, for date, `hh`, for hours, `mm`, for minutes, `ss`, for seconds, and `uuuuuu`, for microseconds). For example, `"2023-01-26T13:00:00.000000Z"`. diff --git a/ydb/docs/en/core/operations/query_plans_optimization.md b/ydb/docs/en/core/dba/terraform.md index 3667a042788..3667a042788 100644 --- a/ydb/docs/en/core/operations/query_plans_optimization.md +++ b/ydb/docs/en/core/dba/terraform.md diff --git a/ydb/docs/en/core/dba/toc_i.yaml b/ydb/docs/en/core/dba/toc_i.yaml new file mode 100644 index 00000000000..82222d4446a --- /dev/null +++ b/ydb/docs/en/core/dba/toc_i.yaml @@ -0,0 +1,21 @@ +items: +- name: Backup and recovery + href: backup-and-recovery.md +- name: Primary keys + include: + mode: link + path: primary-key/toc_p.yaml +- name: Secondary indexes + href: secondary-indexes.md +- name: Query plans optimization + href: query-plans-optimization.md + hidden: true +- name: System views + href: system-views.md +- name: Custom attributes + href: custom-attributes.md +- name: Change Data Capture + href: cdc.md +- name: Terraform + href: terraform.md + hidden: true
\ No newline at end of file diff --git a/ydb/docs/en/core/development/toc_p.yaml b/ydb/docs/en/core/dba/toc_p.yaml index 94ce1108684..94ce1108684 100644 --- a/ydb/docs/en/core/development/toc_p.yaml +++ b/ydb/docs/en/core/dba/toc_p.yaml diff --git a/ydb/docs/en/core/best_practices/_includes/batch_upload.md b/ydb/docs/en/core/dev/batch-upload.md index 34863e4f07f..34863e4f07f 100644 --- a/ydb/docs/en/core/best_practices/_includes/batch_upload.md +++ b/ydb/docs/en/core/dev/batch-upload.md diff --git a/ydb/docs/en/core/dev/index.md b/ydb/docs/en/core/dev/index.md new file mode 100644 index 00000000000..5ce6df75c35 --- /dev/null +++ b/ydb/docs/en/core/dev/index.md @@ -0,0 +1,5 @@ +# {{ ydb-short-name }} for Application Developers / Software Engineers + +This section of {{ ydb-short-name }} documentation covers everything you need to know to develop applications interacting with YDB. + +If you're interested in developing {{ ydb-short-name }} core or satellite projects, refer to the [documentation for contributors](../contributor/index.md).
\ No newline at end of file diff --git a/ydb/docs/en/core/best_practices/_includes/paging.md b/ydb/docs/en/core/dev/paging.md index c4b25606113..c4b25606113 100644 --- a/ydb/docs/en/core/best_practices/_includes/paging.md +++ b/ydb/docs/en/core/dev/paging.md diff --git a/ydb/docs/en/core/best_practices/_includes/timeouts.md b/ydb/docs/en/core/dev/timeouts.md index 38417b4bd12..38417b4bd12 100644 --- a/ydb/docs/en/core/best_practices/_includes/timeouts.md +++ b/ydb/docs/en/core/dev/timeouts.md diff --git a/ydb/docs/en/core/dev/toc_p.yaml b/ydb/docs/en/core/dev/toc_p.yaml new file mode 100644 index 00000000000..b8224fd6af3 --- /dev/null +++ b/ydb/docs/en/core/dev/toc_p.yaml @@ -0,0 +1,9 @@ +items: +- name: Overview + href: index.md +- name: Batch upload + href: batch-upload.md +- name: Paging + href: paging.md +- name: Timeouts + href: timeouts.md
\ No newline at end of file diff --git a/ydb/docs/en/core/devops/index.md b/ydb/docs/en/core/devops/index.md index 9bf028b1b0a..39eb4c39d19 100644 --- a/ydb/docs/en/core/devops/index.md +++ b/ydb/docs/en/core/devops/index.md @@ -1,4 +1,4 @@ -# {{ ydb-short-name }} for SRE +# {{ ydb-short-name }} for DevOps Engineers This section of {{ ydb-short-name }} documentation covers everything you need to know to run a production-grade {{ ydb-short-name }} cluster. It is subdivided based on what's your preferred approach to managing infrastructure: diff --git a/ydb/docs/en/core/troubleshooting/_includes/system_views/distributed_storage.md b/ydb/docs/en/core/devops/manual/system-views.md index b6cd28b3a4e..a07ea319fd7 100644 --- a/ydb/docs/en/core/troubleshooting/_includes/system_views/distributed_storage.md +++ b/ydb/docs/en/core/devops/manual/system-views.md @@ -1,3 +1,17 @@ +# Cluster system views + +To enable internal introspection of the cluster state, the user can make queries to special system views. These tables are accessible from the cluster's root directory and use the `.sys` system path prefix. + +Cloud database users usually don't have access to cluster system tables, as cluster support and timely diagnostics are the prerogatives of the cloud team. + +Hereinafter, in the descriptions of available fields, the **Key** column contains the corresponding table's primary key field index. + +{% note info %} + +There are also similar system views describing what's happening inside a given database, they are covered in a [separate article for DBAs](../../dba/system-views.md). + +{% endnote %} + ## Distributed Storage Information about the operation of distributed storage is contained in several interconnected tables, each of which is responsible for describing its entity, such as: @@ -101,3 +115,9 @@ Unlike other tables that show physical entities, the `ds_storage_stats` table sh It should be noted that AvailableGroupsToCreate shows the maximum number of groups that can be created if no other types of groups are created. So when extending a storage pool, the count of AvailableGroupsToCreate in several rows of statistics may change. + +{% note info %} + +Loads caused by accessing system views are more analytical in nature. Making frequent queries to them in large DBs will consume a lot of system resources. The recommended load is no more than 1-2 RPS. + +{% endnote %} diff --git a/ydb/docs/en/core/devops/manual/toc_p.yaml b/ydb/docs/en/core/devops/manual/toc_p.yaml new file mode 100644 index 00000000000..3ecf84f5d7d --- /dev/null +++ b/ydb/docs/en/core/devops/manual/toc_p.yaml @@ -0,0 +1,6 @@ +items: +- include: + mode: link + path: ../../cluster/toc_p.yaml +- name: System views + href: system-views.md diff --git a/ydb/docs/en/core/devops/toc_p.yaml b/ydb/docs/en/core/devops/toc_p.yaml index 95bb5899576..aa8b686ce61 100644 --- a/ydb/docs/en/core/devops/toc_p.yaml +++ b/ydb/docs/en/core/devops/toc_p.yaml @@ -12,4 +12,4 @@ items: - name: Manual include: mode: link - path: ../cluster/toc_p.yaml
\ No newline at end of file + path: manual/toc_p.yaml
\ No newline at end of file diff --git a/ydb/docs/en/core/faq/_includes/common.md b/ydb/docs/en/core/faq/_includes/common.md index 83d46f1addc..13748000eae 100644 --- a/ydb/docs/en/core/faq/_includes/common.md +++ b/ydb/docs/en/core/faq/_includes/common.md @@ -29,7 +29,7 @@ To design a primary key properly, follow the rules below. * The fewer table partitions a query uses, the faster it runs. For greater performance, follow the one query — one partition rule. * Avoid situations where a small part of the DB is under much heavier load than the rest of the DB. -For more information, see [Schema design](../../best_practices/schema_design.md). +For more information, see [choosing a primary key](../../dba/primary-key/index.md). #### How do I evenly distribute load across table partitions? {#balance-shard-load} @@ -40,7 +40,7 @@ You can use the following techniques to distribute the load evenly across table * use a hash of the key column values as the primary key. * Reduce the number of partitions used in a single query. -For more information, see [Schema design](../../best_practices/schema_design.md#balance-shard-load). +For more information, see [choosing a primary key](../../dba/primary-key/index.md). #### Can I use NULL in a key column? {#null} @@ -64,7 +64,7 @@ For more information, see [Secondary indexes](../../concepts/secondary_indexes.m To print paginated results, we recommend selecting data sorted by primary key sequentially, limiting the number of rows with the `LIMIT` keyword. We do not recommend using the `OFFSET` keyword to solve this problem. -For more information, see [Paginated results](../../best_practices/paging.md). +For more information, see [Paginated results](../../dev/paging.md). #### How do I delete expired data? {#ttl} diff --git a/ydb/docs/en/core/faq/_includes/yql.md b/ydb/docs/en/core/faq/_includes/yql.md index 99da7090b05..95e4ffa990e 100644 --- a/ydb/docs/en/core/faq/_includes/yql.md +++ b/ydb/docs/en/core/faq/_includes/yql.md @@ -35,7 +35,7 @@ WHERE Key LIKE "some_prefix%"; #### Why does a query return only 1000 rows? {#result-rows-limit} -1000 rows is the response size limit per YQL query. If a response is shortened, it is flagged as `Truncated`. To output more table rows, you can use [paginated output](../../best_practices/paging.md) or the `ReadTable` operation. +1000 rows is the response size limit per YQL query. If a response is shortened, it is flagged as `Truncated`. To output more table rows, you can use [paginated output](../../dev/paging.md) or the `ReadTable` operation. #### How to escape quotes of JSON strings when adding them to a table? {#escaping-quotes} diff --git a/ydb/docs/en/core/index.yaml b/ydb/docs/en/core/index.yaml index 86fe3db6116..037d8cf9e39 100644 --- a/ydb/docs/en/core/index.yaml +++ b/ydb/docs/en/core/index.yaml @@ -8,14 +8,23 @@ meta: title: YDB Documentation links: - title: Getting started - description: Deploy your cluster and perform basic operations with data + description: Deploy your first YDB instance to experiment with href: quickstart - title: Concepts description: How YDB works, its features and available usage modes href: concepts/ - - title: Recommendations - description: A set of recommendations for practical service use - href: best_practices/ + - title: For DevOps + description: How to run production YDB clusters + href: devops/ + - title: For DBA + description: How to run manage YDB databases + href: dba/ + - title: For Developers + description: How to develop applications working with YDB + href: dev/ + - title: For Contributors + description: How to contribute to YDB core and satellite projects + href: contributor/ - title: YQL reference guide description: Description of YQL syntax and built-in functions href: yql/reference/ @@ -25,12 +34,6 @@ links: - title: Working with the SDK description: YDB SDK reference href: reference/ydb-sdk/ - - title: Working with PostgreSQL - description: Compatibility with PostgreSQL - href: postgresql/ - - title: Managing databases - description: Configuring, maintaining, monitoring, and performing diagnostics of YDB databases - href: db/ - - title: Managing a cluster - description: Configuring, maintaining, monitoring, and performing diagnostics of YDB clusters - href: cluster/ + - title: PostgreSQL compatibility + description: Integrate with PostgreSQL ecosystem + href: postgresql/intro/
\ No newline at end of file diff --git a/ydb/docs/en/core/operations/toc_i.yaml b/ydb/docs/en/core/operations/toc_i.yaml deleted file mode 100644 index e030da13fea..00000000000 --- a/ydb/docs/en/core/operations/toc_i.yaml +++ /dev/null @@ -1,8 +0,0 @@ -items: -- name: Reading and writing data - href: crud.md - hidden: true -- name: Custom attributes in tables - href: manage-users-attr.md -- name: Query plans optimization - href: query_plans_optimization.md
\ No newline at end of file diff --git a/ydb/docs/en/core/operations/toc_p.yaml b/ydb/docs/en/core/operations/toc_p.yaml deleted file mode 100644 index 5bfec4365de..00000000000 --- a/ydb/docs/en/core/operations/toc_p.yaml +++ /dev/null @@ -1,2 +0,0 @@ -items: -- include: { mode: link, path: toc_i.yaml }
\ No newline at end of file diff --git a/ydb/docs/en/core/quickstart.md b/ydb/docs/en/core/quickstart.md index 983a24031c8..d89ce13b033 100644 --- a/ydb/docs/en/core/quickstart.md +++ b/ydb/docs/en/core/quickstart.md @@ -143,7 +143,7 @@ As you can see, it is a simple key-value table. Let's walk through the query ste * Each SQL statement kind like `CREATE TABLE` has more detailed explanation in [YQL reference](yql/reference/index.md). * `example` is the table name identifier, while `key` and `value` are column name identifiers. It is recommended to use simple names for identifiers like these, but if you need one that contains non-trivial symbols, wrap the name in backticks. * `UInt64` and `String` are data type names. `String` represents a binary string, and `UInt64` is a 64-bit unsigned integer. Thus, our example table stores string values identified by unsigned integer keys. More details [about data types](yql/reference/types/index.md). -* `PRIMARY KEY` is one of the fundamental concepts of SQL that has a significant impact on both application logic and performance. Following the SQL standard, the primary key also implies an unique constraint, meaning the table cannot have multiple rows with equal primary keys. In this example table, it's quite straightforward which column should be chosen as the primary key, which we specify as `(key)` in round brackets after the respective keyword. In real-world scenarios, tables often have dozens of columns, and primary keys can be compound (consisting of multiple columns in a specified order), making choosing the right primary key more of an art. If you are interested in this topic, there's a [guide on choosing the primary key for maximizing performance](best_practices/pk_scalability.md). YDB tables are required to have a primary key. +* `PRIMARY KEY` is one of the fundamental concepts of SQL that has a significant impact on both application logic and performance. Following the SQL standard, the primary key also implies an unique constraint, meaning the table cannot have multiple rows with equal primary keys. In this example table, it's quite straightforward which column should be chosen as the primary key, which we specify as `(key)` in round brackets after the respective keyword. In real-world scenarios, tables often have dozens of columns, and primary keys can be compound (consisting of multiple columns in a specified order), making choosing the right primary key more of an art. If you are interested in this topic, there's a [guide on choosing the primary key for maximizing performance](dba/primary-key/row-oriented.md). YDB tables are required to have a primary key. ## Add sample data diff --git a/ydb/docs/en/core/troubleshooting/_includes/monitoring_sensors.md b/ydb/docs/en/core/reference/observability/metrics/index.md index 6c78d0b42a7..e99e4b54911 100644 --- a/ydb/docs/en/core/troubleshooting/_includes/monitoring_sensors.md +++ b/ydb/docs/en/core/reference/observability/metrics/index.md @@ -1,15 +1,13 @@ -<!-- This file is referenced as include from /ru/monitoring/metrics-ref/index.md --> +# Metrics reference -## {{ ydb-full-name }} {#ydb} - -### Resource usage metrics {#resources} +## Resource usage metrics {#resources} | Metric name<br/>Type, units of measurement | Description<br/>Labels | | ----- | ----- | -| `resources.storage.used_bytes`<br/>`IGAUGE`, bytes | The size of user and service data stored in distributed network storage. Housekeeping data include the data of the primary and [secondary indexes](../../concepts/secondary_indexes.md). | +| `resources.storage.used_bytes`<br/>`IGAUGE`, bytes | The size of user and service data stored in distributed network storage. Housekeeping data include the data of the primary and [secondary indexes](../../../concepts/secondary_indexes.md). | | `resources.storage.limit_bytes`<br/>`IGAUGE`, bytes | A limit on the size of user and service data that a database can store in distributed network storage. | -### API metrics {#api} +## API metrics {#api} | Metric name<br/>Type, units of measurement | Description<br/>Labels | | ----- | ----- | @@ -18,18 +16,18 @@ | `api.grpc.request.inflight_count`<br/>`IGAUGE`, pieces | The number of requests that a database is simultaneously handling in a certain period of time.<br/>Labels:<br/>- _api_service_: The name of the gRPC API service, such as `table`.<br/>- _method_: The name of a gRPC API service method, such as `ExecuteDataQuery`. | | `api.grpc.request.inflight_bytes`<br/>`IGAUGE`, bytes | The size of requests that a database is simultaneously handling in a certain period of time.<br/>Labels:<br/>- _api_service_: The name of the gRPC API service, such as `table`.<br/>- _method_: The name of a gRPC API service method, such as `ExecuteDataQuery`. | | `api.grpc.response.bytes`<br/>`RATE`, bytes | The size of responses sent by the database in a certain period of time.<br/>Labels:<br/>- _api_service_: The name of the gRPC API service, such as `table`.<br/>- _method_: The name of a gRPC API service method, such as `ExecuteDataQuery`. | -| `api.grpc.response.count`<br/>`RATE`, pieces | The number of responses sent by the database in a certain period of time.<br/>Labels:<br/>- _api_service_: The name of the gRPC API service, such as `table`.<br/>- _method_: The name of a gRPC API service method, such as `ExecuteDataQuery`.<br/>- _status_ is the request execution status. See a more detailed description of statuses under [Error Handling](../../reference/ydb-sdk/error_handling.md). | +| `api.grpc.response.count`<br/>`RATE`, pieces | The number of responses sent by the database in a certain period of time.<br/>Labels:<br/>- _api_service_: The name of the gRPC API service, such as `table`.<br/>- _method_: The name of a gRPC API service method, such as `ExecuteDataQuery`.<br/>- _status_ is the request execution status. See a more detailed description of statuses under [Error Handling](../../../reference/ydb-sdk/error_handling.md). | | `api.grpc.response.dropped_count`<br/>`RATE`, pieces | The number of responses dropped at the transport (gRPC) layer due to an error.<br/>Labels:<br/>- _api_service_: The name of the gRPC API service, such as `table`.<br/>- _method_: The name of a gRPC API service method, such as `ExecuteDataQuery`. | -| `api.grpc.response.issues`<br/>`RATE`, pieces | The number of errors of a certain type arising in the execution of a request over a certain period of time.<br/>Tags:<br/>- _issue_type_ is the error type wth the only value being `optimistic_locks_invalidation`. For more on lock invalidation, review [Transactions and requests to {{ ydb-short-name }}](../../concepts/transactions.md). | +| `api.grpc.response.issues`<br/>`RATE`, pieces | The number of errors of a certain type arising in the execution of a request over a certain period of time.<br/>Tags:<br/>- _issue_type_ is the error type wth the only value being `optimistic_locks_invalidation`. For more on lock invalidation, review [Transactions and requests to {{ ydb-short-name }}](../../../concepts/transactions.md). | -### Session metrics {#sessions} +## Session metrics {#sessions} | Metric name<br/>Type, units of measurement | Description<br/>Labels | | ----- | ----- | | `table.session.active_count`<br/>`IGAUGE`, pieces | The number of sessions started by clients and running at a given time. | | `table.session.closed_by_idle_count`<br/>`RATE`, pieces | The number of sessions closed by the DB server in a certain period of time due to exceeding the lifetime allowed for an idle session. | -### Transaction processing metrics {#transactions} +## Transaction processing metrics {#transactions} You can analyze a transaction's execution time using a histogram counter. The intervals are set in milliseconds. The chart shows the number of transactions whose duration falls within a certain time interval. @@ -39,7 +37,7 @@ You can analyze a transaction's execution time using a histogram counter. The in | `table.transaction.server_duration_milliseconds`<br/>`HIST_RATE`, pieces | The number of transactions with a certain duration on the server. The duration is the time of executing requests within a transaction on the server. Does not include the waiting time on the client between sending separate requests within a single transaction.<br/>Labels:<br/> -_tx_kind_: The transaction type, possible values are`read_only`, `read_write`, `write_only`, and `pure`. | | `table.transaction.client_duration_milliseconds`<br/>`HIST_RATE`, pieces | The number of transactions with a certain duration on the client. The duration is the waiting time on the client between sending individual requests within a single transaction. Does not include the time of executing requests on the server.<br/>Labels:<br/>- _tx_kind_: The transaction type, possible values are `read_only`, `read_write`, `write_only`, and `pure`. | -### Query processing metrics {#queries} +## Query processing metrics {#queries} | Metric name<br/>Type, units of measurement | Description<br/>Labels | | ----- | ----- | @@ -54,7 +52,7 @@ You can analyze a transaction's execution time using a histogram counter. The in | `table.query.compilation.cache_misses`<br/>`RATE`, pieces | The number of queries in a certain period of time that required query compilation. | | `table.query.execution.latency_milliseconds`<br/>`HIST_RATE`, pieces | Histogram counter. The intervals are set in milliseconds. Shows the number of queries whose execution time falls within a certain interval. | -### Table partition metrics {#datashards} +## Table partition metrics {#datashards} | Metric name<br/>Type, units of measurement | Description<br/>Labels | | ----- | ----- | @@ -72,7 +70,7 @@ You can analyze a transaction's execution time using a histogram counter. The in | `table.datashard.erase.rows`<br/>`RATE`, pieces | The number of rows deleted from the database in a certain period of time. | | `table.datashard.erase.bytes`<br/>`RATE`, bytes | The size of data deleted from the database in a certain period of time. | -### Resource usage metrics (for Dedicated mode only) {#ydb_dedicated_resources} +## Resource usage metrics (for Dedicated mode only) {#ydb_dedicated_resources} | Metric name<br/>Type<br/>units of measurement | Description<br/>Labels | | ----- | ----- | @@ -81,11 +79,11 @@ You can analyze a transaction's execution time using a histogram counter. The in | `resources.memory.used_bytes`<br/>`IGAUGE`, bytes | The amount of RAM used by the database nodes. | | `resources.memory.limit_bytes`<br/>`IGAUGE`, bytes | RAM available to the database nodes. | -### Query processing metrics (for Dedicated mode only) {#ydb_dedicated_queries} +## Query processing metrics (for Dedicated mode only) {#ydb_dedicated_queries} | Metric name<br/>Type<br/>units of measurement | Description<br/>Labels | | ----- | ----- | -| `table.query.compilation.cache_evictions`<br/>`RATE`, pieces | The number of queries evicted from the cache of [prepared queries](../../reference/ydb-sdk/example/index.md#param-queries) in a certain period of time. | -| `table.query.compilation.cache_size_bytes`<br/>`IGAUGE`, bytes | The size of the cache of [prepared queries](../../reference/ydb-sdk/example/index.md#param-queries). | -| `table.query.compilation.cached_query_count`<br/>`IGAUGE`, pieces | The size of the cache of [prepared queries](../../reference/ydb-sdk/example/index.md#param-queries). | +| `table.query.compilation.cache_evictions`<br/>`RATE`, pieces | The number of queries evicted from the cache of [prepared queries](../../../reference/ydb-sdk/example/index.md#param-queries) in a certain period of time. | +| `table.query.compilation.cache_size_bytes`<br/>`IGAUGE`, bytes | The size of the cache of [prepared queries](../../../reference/ydb-sdk/example/index.md#param-queries). | +| `table.query.compilation.cached_query_count`<br/>`IGAUGE`, pieces | The size of the cache of [prepared queries](../../../reference/ydb-sdk/example/index.md#param-queries). | diff --git a/ydb/docs/en/core/reference/observability/toc_p.yaml b/ydb/docs/en/core/reference/observability/toc_p.yaml new file mode 100644 index 00000000000..2175b824d83 --- /dev/null +++ b/ydb/docs/en/core/reference/observability/toc_p.yaml @@ -0,0 +1,3 @@ +items: +- name: Metrics reference + href: metrics/index.md diff --git a/ydb/docs/en/core/reference/toc_p.yaml b/ydb/docs/en/core/reference/toc_p.yaml index 9d3a47952ce..ab0514de244 100644 --- a/ydb/docs/en/core/reference/toc_p.yaml +++ b/ydb/docs/en/core/reference/toc_p.yaml @@ -26,4 +26,8 @@ items: - name: YDB DStool include: mode: link - path: ydb-dstool/toc_p.yaml
\ No newline at end of file + path: ydb-dstool/toc_p.yaml +- name: Observability + include: + mode: link + path: observability/toc_p.yaml
\ No newline at end of file diff --git a/ydb/docs/en/core/reference/ydb-cli/commands/_includes/secondary_index.md b/ydb/docs/en/core/reference/ydb-cli/commands/_includes/secondary_index.md index 809be3a496c..7c732383a5d 100644 --- a/ydb/docs/en/core/reference/ydb-cli/commands/_includes/secondary_index.md +++ b/ydb/docs/en/core/reference/ydb-cli/commands/_includes/secondary_index.md @@ -10,7 +10,7 @@ By using the `table index` command, you can create and delete [secondary indexes You can also add or delete a secondary index with the [ADD INDEX and DROP INDEX](../../../../yql/reference/syntax/alter_table.md#secondary-index) directives of YQL ALTER TABLE. -To learn about secondary indexes and their use in application development, see [Secondary indexes](../../../../best_practices/secondary_indexes.md) under "Recommendations". +To learn about secondary indexes and their use in application development, see [Secondary indexes](../../../../dba/secondary-indexes.md) under "Recommendations". ## Creating a secondary index {#add} diff --git a/ydb/docs/en/core/reference/ydb-cli/commands/workload/_includes/stock.md b/ydb/docs/en/core/reference/ydb-cli/commands/workload/_includes/stock.md index 3a8b6ac2aef..99f293e0376 100644 --- a/ydb/docs/en/core/reference/ydb-cli/commands/workload/_includes/stock.md +++ b/ydb/docs/en/core/reference/ydb-cli/commands/workload/_includes/stock.md @@ -83,9 +83,9 @@ See the description of the command to run the data load: | `--rate <value>` | - | Total rate for all threads, in transactions per second. Default: 0 (no rate limit). | | `--quiet` | - | Outputs only the total result. | | `--print-timestamp` | - | Print the time together with the statistics of each time window. | -| `--client-timeout` | - | [Transport timeout in milliseconds](../../../../../best_practices/timeouts.md). | -| `--operation-timeout` | - | [Operation timeout in milliseconds](../../../../../best_practices/timeouts.md). | -| `--cancel-after` | - | [Timeout for canceling an operation in milliseconds](../../../../../best_practices/timeouts.md). | +| `--client-timeout` | - | [Transport timeout in milliseconds](../../../../../dev/timeouts.md). | +| `--operation-timeout` | - | [Operation timeout in milliseconds](../../../../../dev/timeouts.md). | +| `--cancel-after` | - | [Timeout for canceling an operation in milliseconds](../../../../../dev/timeouts.md). | | `--window` | - | Statistics collection window in seconds. Default: 1. | diff --git a/ydb/docs/en/core/reference/ydb-cli/workload-kv.md b/ydb/docs/en/core/reference/ydb-cli/workload-kv.md index 93538a03d93..d13ee3fba8a 100644 --- a/ydb/docs/en/core/reference/ydb-cli/workload-kv.md +++ b/ydb/docs/en/core/reference/ydb-cli/workload-kv.md @@ -120,9 +120,9 @@ Parameter name | Short name | Parameter description `--rate <value>` | - | Total rate for all threads, in requests per second. Default: 0 (no rate limit). `--quiet` | - | Outputs only the total result. `--print-timestamp` | - | Print the time together with the statistics of each time window. -`--client-timeout` | - | [Transport timeout in milliseconds](../../best_practices/timeouts.md). -`--operation-timeout` | - | [Operation timeout in milliseconds](../../best_practices/timeouts.md). -`--cancel-after` | - | [Timeout for canceling an operation in milliseconds](../../best_practices/timeouts.md). +`--client-timeout` | - | [Transport timeout in milliseconds](../../dev/timeouts.md). +`--operation-timeout` | - | [Operation timeout in milliseconds](../../dev/timeouts.md). +`--cancel-after` | - | [Timeout for canceling an operation in milliseconds](../../dev/timeouts.md). `--window` | - | Statistics collection window in seconds. Default: 1. `--max-first-key` | - | Maximum value of the primary key of the table. Default: $2^{64} - 1$. `--cols` | - | Number of columns in the table. Default: 2 counting Key. diff --git a/ydb/docs/en/core/sre/ansible/_assets/terraform/AiC_scheme.png b/ydb/docs/en/core/sre/ansible/_assets/terraform/AiC_scheme.png Binary files differdeleted file mode 100644 index e01304fa935..00000000000 --- a/ydb/docs/en/core/sre/ansible/_assets/terraform/AiC_scheme.png +++ /dev/null diff --git a/ydb/docs/en/core/sre/ansible/_includes/ansible-install-steps.md b/ydb/docs/en/core/sre/ansible/_includes/ansible-install-steps.md deleted file mode 100644 index ada789bc5df..00000000000 --- a/ydb/docs/en/core/sre/ansible/_includes/ansible-install-steps.md +++ /dev/null @@ -1,89 +0,0 @@ -1. [Role `packages`](https://github.com/ydb-platform/ydb-ansible/blob/main/roles/packages/tasks/main.yaml). Tasks: - * `check dpkg audit` – Verifies the [dpkg](https://en.wikipedia.org/wiki/Dpkg) state using the `dpkg --audit` command and saves the command results in the `dpkg_audit_result` variable. The task will terminate with an error if the `dpkg_audit_result.rc` command returns a value other than 0 or 1. - * `run the equivalent of "apt-get clean" as a separate step` – Cleans the apt cache, similarly to the `apt-get clean` command. - * `run the equivalent of "apt-get update" as a separate step` – Updates the apt cache, akin to the `apt-get update` command. - * `fix unconfigured packages` – Fixes packages that are not configured using the `dpkg --configure --pending` command. - * `set vars_for_distribution_version variables` – Sets variables for a specific Linux distribution version. - * `setup apt repositories` – Configures apt repositories from a specified list. - * `setup apt preferences` – Configures apt preferences (variable contents are specified in `roles/packages/vars/distributions/<distributive name>/<version>/main.yaml`). - * `setup apt configs`– Configures apt settings. - * `flush handlers` – Forcibly runs all accumulated handlers. In this context, it triggers a handler that updates the apt cache. - * `install packages` – Installs apt packages considering specified parameters and cache validity. - -Links to the lists of packages that will be installed for Ubuntu 22.04 or Astra Linux 1.7: -* [List](https://github.com/ydb-platform/ydb-ansible/blob/main/roles/packages/vars/distributions/Ubuntu/22.04/main.yaml) of packages for Ubuntu 22.04; -* [List](https://github.com/ydb-platform/ydb-ansible/blob/main/roles/packages/vars/distributions/Astra%20Linux/1.7_x86-64/main.yaml) of packages for Astra Linux 1.7. - -2. [Role `system`](https://github.com/ydb-platform/ydb-ansible/blob/main/roles/system/tasks/main.yaml). Tasks: - * `configure clock` – A block of tasks for setting up system clocks: - + `assert required variables are defined` – Checks for the existence of the `system_timezone` variable. This check ensures that the necessary variable is available for the next task in the block. - + `set system timezone` – Sets the system timezone. The timezone is determined by the value of the `system_timezone` variable, and the hardware clock (`hwclock`) is set to UTC. After completing the task, a notification is sent to restart the `cron` service. - + `flush handlers` – Forces the execution of accumulated handlers using the `meta` directive. This will restart the following processes: `timesyncd`, `journald`, `cron`, `cpufrequtils`, and execute the `sysctl -p` command. - * `configure systemd-timesyncd` – A task block for configuring `systemd-timesyncd`: - + `assert required variables are defined` asserts that the number of NTP servers (`system_ntp_servers`) is more than one if the variable `system_ntp_servers` is defined. If the variable `system_ntp_servers` is not defined, the execution of the `configure systemd-timesyncd` task block will be skipped, including the check for the number of NTP servers and the configuration of `systemd-timesyncd`. - + `create conf.d directory for timesyncd` - Creates the `/etc/systemd/timesyncd.conf.d` directory if the `system_ntp_servers` variable is defined. - + `configure systemd-timesyncd` - Creates a configuration file `/etc/systemd/timesyncd.conf.d/ydb.conf` for the `systemd-timesyncd` service with primary and backup NTP servers. The task is executed if the `system_ntp_servers` variable is defined. After completing the task, a notification is sent to restart the `timesyncd` service. - + `flush handlers` - Calls accumulated handlers. Executes the handler `restart timesyncd`, which restarts the `systemd-timesyncd.service`. - + `start timesyncd` - Starts and enables the `systemd-timesyncd.service`. Subsequently, the service will start automatically at system boot. - * `configure systemd-journald` – A block of tasks for configuring the `systemd-journald` service: - + `create conf.d directory for journald` - Creates the `/etc/systemd/journald.conf.d` directory for storing `systemd-journald` configuration files. - + `configure systemd-journald` - Creates a configuration file `/etc/systemd/journald.conf.d/ydb.conf` for `systemd-journald`, specifying a `Journal` section with the option `ForwardToWall=no`. The `ForwardToWall=no` setting in the `systemd-journald` configuration means that system log messages will not be forwarded as "wall" messages to all logged-in users. After completing the task, a notification is sent to restart the `journald` service. - + `flush handlers` - Calls accumulated handlers. Executes the handler `restart journald`, which restarts the `systemd-journald` service. - + `start journald` - Starts and enables the `systemd-journald.service`. Subsequently, the service will start automatically at system boot. - * `configure kernel` – A block of tasks for kernel configuration: - + `configure /etc/modules-load.d dir` - Creates the `/etc/modules-load.d` directory with owner and group permissions for the root user and `0755` permissions. - + `setup conntrack module` - Copies the `nf_conntrack` line into the file `/etc/modules-load.d/conntrack.conf` to load the `nf_conntrack` module at system start. - + `load conntrack module` - Loads the `nf_conntrack` module in the current session. - + `setup sysctl files` - Applies templates to create configuration files in `/etc/sysctl.d/` for various system settings (such as security, network, and filesystem settings). The list of files includes `10-console-messages.conf`, `10-link-restrictions.conf`, and others. After completing this task, a notification is sent to apply the kernel settings changes. - + `flush handlers` - Calls accumulated handlers. Executes the handler `apply kernel settings`, which runs the `sysctl -p` command to apply the kernel parameters specified in `/etc/sysctl.conf` or in other files in the `/etc/sysctl.d/` directory. - * `configure cpu governor` – A block of tasks for configuring the CPU frequency management mode: - + `install cpufrequtils` - Installs the `cpufrequtils` package from apt. The task is set with cache check parameters and a task timeout of 300 seconds to expedite task execution and avoid an infinite loop waiting for apt package updates. - + `use performance cpu governor` - Creates the file `/etc/default/cpufrequtils` with content "GOVERNOR=performance", which sets the CPU governor mode to "performance" (disabling power-saving mode when CPU cores are idle). After completing the task, a notification is sent to restart the `cpufrequtils` service. - + `disable ondemand.service` - Disables the `ondemand.service` if it is present in the system. The service is stopped, its automatic start is disabled, and it is masked (preventing its start). After completing the task, a notification is sent to restart cpufrequtils. - + `flush handlers` - Calls accumulated handlers. Executes the handler `restart cpufrequtils`, which restarts the `cpufrequtils` service. - + `start cpufrequtils` - Starts and enables the `cpufrequtils.service`. Subsequently, the service will start automatically at system boot. - -3. [Role](https://github.com/ydb-platform/ydb-ansible/blob/main/roles/ydbd/tasks/main.yaml) `ydbd`. Tasks: - * `check if required variables are defined` – Checks that the variables `ydb_archive`, `ydb_config`, `ydb_tls_dir` are defined. If any of these are undefined, Ansible will display an appropriate error message and stop the playbook execution. - * `set vars_for_distribution variables` – Sets variables from the specified file in the `vars_for_distribution_file` variable during playbook execution. This task manages a set of variables dependent on the specific Linux distribution. - * `ensure libaio is installed` – Ensures that the `libaio` package is installed. - * `install custom libidn from archive` – Installs a custom version of the `libidn` library from an archive. - * `create certs group` – Creates a system group `certs`. - * `create ydb group` – Creates a system group `ydb`. - * `create ydb user` – Creates a system user `ydb` with a home directory. - * `install YDB server binary package from archive` – Installs {{ ydb-short-name }} from a downloaded archive. - * `create YDB audit directory` – Creates an `audit` subdirectory in the {{ ydb-short-name }} installation directory. - * `setup certificates` – A block of tasks for setting up security certificates: - + `create YDB certs directory` – Creates a `certs` subdirectory in the {{ ydb-short-name }} installation directory. - + `copy the TLS ca.crt` – Copies the root certificate `ca.crt` to the server. - + `copy the TLS node.crt` – Copies the TLS certificate `node.crt` from the generated certificates directory. - + `copy the TLS node.key` – Copies the TLS certificate `node.key` from the generated certificates directory. - + `copy the TLS web.pem` – Copies the TLS pem key `web.pem` from the generated certificates directory. - * `copy configuration file` – Copies the configuration file `config.yaml` to the server. - * `add configuration file updater script` – Copies the `update_config_file.sh` script to the server. - -4. [Role `ydbd_static`](https://github.com/ydb-platform/ydb-ansible/blob/main/roles/ydbd_static/tasks/main.yaml). Tasks: - * `check if required variables are defined` – Checks that the variables `ydb_cores_static`, `ydb_disks`, `ydb_domain`, `ydb_user` are defined. If any of these variables are undefined, the task will fail and an appropriate error message will be displayed for each undefined variable. - * `check if required secrets are defined` – Verifies that the secret variable `ydb_password` is defined. If this variable is undefined, the task will fail and an error message will be displayed. - * `create static node configuration file` – Creates a static node configuration file by running the copied `update_config_file.sh` script with `ydbd-config.yaml` and `ydbd-config-static.yaml` configurations. - * `create static node systemd unit` – Creates a `ydbd-storage.service` file for the static node based on a template. After completing the task, a notification is sent to restart the `systemd` service. - * `flush handlers` – Executes accumulated handlers. Restarts all `systemd` services. - * `format drives confirmation block` – A block of tasks for formatting disks and interrupting playbook execution in case the user declines confirmation. A confirmation request to format the connected disk will be displayed in the terminal. Response options: `yes` – to continue executing the playbook with disk formatting. Any other value will be interpreted as a refusal to format. By default, disks are formatted automatically without asking the user for permission, as the variables `ydb_allow_format_drives` and `ydb_skip_data_loss_confirmation_prompt` are set to `true`. If user confirmation is required, the value of the `ydb_skip_data_loss_confirmation_prompt` variable should be changed to `false` in the inventory file `50-inventory.yaml`. - * `prepare drives` – A task for formatting connected disks. Calls the `drive_prepare` plugin – a specially developed Ansible module for {{ ydb-short-name }} installation, which is part of the {{ ydb-short-name }} collection and is located in the directory `.../.ansible/collections/ansible_collections/ydb_platform/ydb/plugins/action/drive_prepare.py`. The module will format the connected disk specified in the `ydb_disks` variable if the `ydb_allow_format_drives` variable is set to `true`. - * `start storage node` – Starts the storage node process using `systemd`. If any errors occur during service startup, playbook execution will be interrupted. - * `get ydb token` – Requests a YDB token to perform the storage initialization command. The token is stored in the `ydb_credentials` variable. The task calls the `get_token` module from the directory `.../.ansible/collections/ansible_collections/ydb_platform/ydb/plugins/modules`. If any errors occur at this step, playbook execution will be interrupted. - * `wait for ydb discovery to start working locally` – Calls the `wait_discovery` module, which performs a `ListEndpoints` request to YDB to check the operability of the cluster's basic subsystems. If the subsystems are working properly, storage initialization commands and database creation can be executed. - * `init YDB storage if not initialized` – Initializes the storage if it has not already been created. The task calls the `init_storage` plugin, which performs the storage initialization command using a grpcs request to the static node on port 2135. The command result is stored in the `init_storage` variable. - * `wait for ydb healthcheck switch to "GOOD" status` – Waits for the YDB healthcheck system to switch to a `GOOD` status. The task calls the `wait_healthcheck` plugin, which performs a health check command on YDB. - * `set cluster root password` – Sets the password for the YDB root user. The task is executed by the `set_user_password` plugin, which performs a grpcs request to YDB and sets a pre-defined password for the YDB root user. The password is specified in the `ydb_password` variable in the inventory file `/examples/9-nodes-mirror-3-dc/inventory/99-inventory-vault.yaml` in an encrypted form. - - -5. [Role `ydbd_dynamic`](https://github.com/ydb-platform/ydb-ansible/blob/main/roles/ydbd_dynamic/tasks/main.yaml). Tasks: - * `check if required variables are defined` – Verifies the presence of required variables (`ydb_domain`, `ydb_pool_kind`, `ydb_cores_dynamic`, `ydb_brokers`, `ydb_dbname`, `ydb_dynnodes`) and displays an error if any variable is missing. - * `create dynamic node configuration file` – Creates a configuration file for dynamic nodes. - * `create dynamic node systemd unit` – Creates a systemd service for dynamic nodes. After completing the task, a notification is sent to restart the `systemd` service. - * `flush handlers` – Executes accumulated handlers. This will restart `systemd`. - * `start dynamic nodes` – Starts the process of dynamic nodes using `systemd`. - * `get ydb token` – Obtains a token for creating a database. - * `create YDB database` – Creates a database. The task is executed by the `create_database` plugin, which performs a request to 99-inventory-vault.yaml to create the database. - * `wait for ydb discovery to start working locally` – Calls the `wait_discovery` module again to check the operability of the cluster's basic subsystems.
\ No newline at end of file diff --git a/ydb/docs/en/core/sre/ansible/_includes/repo-tree.md b/ydb/docs/en/core/sre/ansible/_includes/repo-tree.md deleted file mode 100644 index aa1eab9c8dc..00000000000 --- a/ydb/docs/en/core/sre/ansible/_includes/repo-tree.md +++ /dev/null @@ -1,18 +0,0 @@ -```text -├── 8-nodes-block-4-2 / 9-nodes-mirror-3-dc -│ ├── ansible.cfg # An Ansible configuration file containing settings for connecting to servers and project structure options. It is essential for customizing Ansible's behavior and specifying default settings. -│ ├── ansible_vault_password_file # A file containing the password for decrypting encrypted data with Ansible Vault, such as sensitive variables or configuration details. This is crucial for securely managing secrets like the root user password. -│ ├── creds # A directory for environment variables that specify the username and password for YDB, facilitating secure access to the database. -│ ├── files -│ │ ├── config.yaml # A YDB configuration file, which contains settings for the database instances. -│ ├── inventory # A directory containing inventory files, which list and organize the servers Ansible will manage. -│ │ ├── 50-inventory.yaml # The main inventory file, specifying the hosts and groups for Ansible tasks. -│ │ └── 99-inventory-vault.yaml # An encrypted inventory file storing sensitive information, such as the root user's password for YDB, using Ansible Vault. -│ ├── setup_playbook.yaml # A playbook file that initiates the installation and configuration roles for setting up YDB on the cluster. -├── README.md # A markdown file providing a description of the repository, including how to use it, prerequisites, and any other relevant information. -├── requirements.txt # A file listing Python package dependencies required for the virtual environment, ensuring all necessary tools and libraries are installed. -├── requirements.yaml # Specifies the Ansible collections needed, pointing to the latest versions or specific versions required for the project. -├── TLS #A directory intended for storing TLS (Transport Layer Security) certificates and keys for secure communication. -│ ├── ydb-ca-nodes.txt # Contains a list of Fully Qualified Domain Names (FQDNs) of the servers for which TLS certificates will be generated, ensuring secure connections to each node. -│ └── ydb-ca-update.sh # A script for generating TLS certificates from the ydb-ca-nodes.txt list, automating the process of securing communication within the cluster. -```
\ No newline at end of file diff --git a/ydb/docs/en/core/sre/ansible/_includes/terraform/aws.md b/ydb/docs/en/core/sre/ansible/_includes/terraform/aws.md deleted file mode 100644 index 365f3f643c6..00000000000 --- a/ydb/docs/en/core/sre/ansible/_includes/terraform/aws.md +++ /dev/null @@ -1,26 +0,0 @@ -Create an [account](https://console.aws.amazon.com) in AWS and add enough balance to run 9 VMs. You can calculate the approximate cost of maintaining infrastructure depending on the region and other circumstances using the [AWS calculator](https://calculator.aws/#/createCalculator/ec2-enhancement). - -Create a user and connection key in AWS Cloud to run the AWS CLI: - -* The user is created in the Security credentials → Access management → [Users](https://console.aws.amazon.com/iam/home#/users) → Create User section. -* The next step is to assign rights to the user. Select `AmazonEC2FullAccess`. -* After creating a user, go to it, open the `Security credentials` tab and click the **Create access key** button in the **Access keys** section. -* From the proposed options for sets of options, select `Command Line Interface`. -* Next, come up with a tag for marking the key and click the **Create access key** button. -* Copy the values of the `Access key` and `Secret access key` fields. - -Install [AWS CLI](https://aws.amazon.com/cli/) and run the `aws configure` command. Enter the values of the `Access key` and `Secret access key` fields saved earlier. Edit the `~/.aws/credentials` and `~/.aws/config` files as follows: -* Add `[AWS_def_reg]` to `~/.aws/config` before `region = ...`. -* Add `[AWS]` before the connection key secret information. - -Go to the `aws` directory in the downloaded repository and edit the following variables in the `variable.tf` file: -* `aws_region` – the region in which the infrastructure will be deployed. -* `aws_profile` – security profile name from the file `~/.aws/credentials`. -* `availability_zones` – list of region availability zones. It is formed from the name of the region and the serial letter. For example, for the `us-west-2` region the list of availability zones will look like this: `["us-west-2a", "us-west-2b", "us-west-2c"]`. - -To create the infrastructure for the first time, you need to run the following commands: -* `terraform init` – installing the provider and initializing modules. -* `terraform plan` – creating a plan for future infrastructure. -* `terraform apply` (re-execute) - Create resources in the cloud. - -Next, the commands `terraform plan`, `terraform init` and `terraform destroy` (destruction of the created infrastructure) are used.
\ No newline at end of file diff --git a/ydb/docs/en/core/sre/ansible/_includes/terraform/azure.md b/ydb/docs/en/core/sre/ansible/_includes/terraform/azure.md deleted file mode 100644 index 854b17387b4..00000000000 --- a/ydb/docs/en/core/sre/ansible/_includes/terraform/azure.md +++ /dev/null @@ -1,10 +0,0 @@ -Create an [account](https://portal.azure.com/#home) in Azure and top up your [account](https://portal.azure.com/#view/Microsoft_Azure_GTM/ModernBillingMenuBlade/~/BillingAccounts) account with the amount , sufficient to operate nine VMs. You can calculate the approximate cost of maintaining infrastructure depending on the region and other circumstances using [calculator](https://azure.com/e/26977c150e854617a888fb3a7d1a399d). - -Authentication to the Azure Provider for Terraform is done through the CLI. You can download, install and configure the Azure CLI by following [this](https://learn.microsoft.com/ru-ru/cli/azure/install-azure-cli) instructions. You can log in to Azure using the Azure CLI interactively with the `az login` command, and the easiest way to create a pair of SSH keys (Linux, macOS) is to use the `ssh-keygen` command. - -After logging into Azure and generating SSH keys, you need to change the default value of the following variables in the root file `variables.tf`: - -* `auth_location` – name of the region where the infrastructure will be deployed. A list of available regions depending on the subscription can be obtained with the command `az account list-locations | grep "displayName"`. -* `ssh_key_path` – path to the public part of the generated SSH key. - -The values of the remaining variables can be left unchanged. While in the root directory of the Terraform script, run the `terraform init` command - the Terraform provider will be installed and the modules will be initialized. Then run the `terraform plan` command to create an infrastructure plan and then run the `terraform apply` command to create the infrastructure in the Azure cloud.
\ No newline at end of file diff --git a/ydb/docs/en/core/sre/ansible/_includes/terraform/gcp.md b/ydb/docs/en/core/sre/ansible/_includes/terraform/gcp.md deleted file mode 100644 index b4a43f2ab8e..00000000000 --- a/ydb/docs/en/core/sre/ansible/_includes/terraform/gcp.md +++ /dev/null @@ -1,18 +0,0 @@ -1. Register in the Google Cloud console and [create](https://console.cloud.google.com/projectselector2/home) a project. -3. Activate your [payment account](https://console.cloud.google.com/billing/manage) and top it up with funds to launch nine VMs. You can calculate the cost in [calculator](https://cloud.google.com/products/calculator). -4. Activate [Compute Engine API](https://console.cloud.google.com/apis/api/compute.googleapis.com/metrics) and [Cloud DNS API](https://console.cloud.google. com/apis/api/dns.googleapis.com/metrics). -5. Download and install GCP CLI by following [this](https://cloud.google.com/sdk/docs/install) instructions. -6. Go to the `.../google-cloud-sdk/bin` subdirectory and run the `./gcloud compute regions list` command to get a list of available regions. -7. Run the command `./gcloud auth application-default login` to configure the connection profile. -8. Download the repository using the `git clone https://github.com/ydb-platform/ydb-terraform` command. -9. Go to the `gcp` subdirectory (located in the downloaded repository) and in the `variables.tf` file set the current values for the following variables: - * `project` – the name of the project that was set in the Google Cloud cloud console. - * `region` – the region where the infrastructure will be deployed. - * `zones` – list of availability zones in which subnets and VMs will be created. - -Now, being in the `gcp` subdirectory, you can run the following sequence of commands to install the provider, initialize modules and create the infrastructure: -* `terraform init` – installing the provider and initializing modules. -* `terraform plan` – creating a plan for future infrastructure. -* `terraform init` (re-execute) – create resources in the cloud. - -Next, the commands `terraform plan`, `terraform init` and `terraform destroy` (destruction of the created infrastructure) are used.
\ No newline at end of file diff --git a/ydb/docs/en/core/sre/ansible/_includes/terraform/yc.md b/ydb/docs/en/core/sre/ansible/_includes/terraform/yc.md deleted file mode 100644 index 120abb759d0..00000000000 --- a/ydb/docs/en/core/sre/ansible/_includes/terraform/yc.md +++ /dev/null @@ -1,45 +0,0 @@ -To create infrastructure in Yandex Cloud using Terraform you need: - -1. Prepare the cloud for work: - * [Register](https://console.cloud.yandex.ru/) in Yandex Cloud. - * [Connect](https://cloud.yandex.com/ru/docs/billing/concepts/billing-account) payment account. - * [Make sure](https://console.cloud.yandex.ru/billing) that there are enough funds to create nine VMs. -2. Install and configure Yandex Cloud CLI: - * [Download](https://cloud.yandex.ru/ru/docs/cli/quickstart) Yandex Cloud CLI. - * [Create](https://cloud.yandex.ru/ru/docs/cli/quickstart#initialize) profile -3. [Create](https://cloud.yandex.com/ru/docs/tutorials/infrastructure-management/terraform-quickstart#get-credentials) service account using the CLI. -4. [Generate](https://cloud.yandex.ru/ru/docs/cli/operations/authentication/service-account#auth-as-sa) SA key in JSON format for connecting Terraform to the cloud using the CLI: `yc iam key create --service-account-name <acc name> --output <file name> --folder-id <cloud folder id>`. An SA key will be generated, and secret information will be output to the terminal: - ``` - access_key: - id: ajenhnhaqgd3vp... - service_account_id: aje90em65r6922... - created_at: "2024-03-05T20:10:50.0150..." - key_id: YCAJElaLsa0z3snzH4E... - secret: YCPKNJDVhRZgyywl4hQwVdcSRC... - ``` - Copy `access_key.id` and `secret`. The values of these fields will be needed later when working with AWS CLI. -5. [Download](https://aws.amazon.com/ru/cli/) AWS CLI. -6. Set up the AWS CLI environment: - * Run the `aws configure` command and sequentially enter the previously saved `access_key.id` and `secret`. For the region value use `ru-central1`: - ``` - aws configure - AWS Access Key ID [None]: AKIAIOSFODNN******** - AWS Secret Access Key [None]: wJalr********/*******/bPxRfiCYEX******** - Default region name [None]: ru-central1 - Default output format [None]: - ``` - The files `~/.aws/credentials` and `~/.aws/config` will be created. -7. Edit `~/.aws/credentials` and `~/.aws/config` as follows: - * Add `[Ya_def_reg]` to `~/.aws/config` before `region = ru-central1-a`. - * Add `[Yandex]` before the secret information about connection keys. -8. [Configure](https://cloud.yandex.com/ru/docs/tutorials/infrastructure-management/terraform-quickstart#configure-provider) Yandex Cloud Terraform provider. -9. Download this repository with the command `git clone https://github.com/ydb-platform/ydb-terraform.git`. -10. Go to the `yandex_cloud` directory (directory in the downloaded repository) and make changes to the following variables in the `variables.tf` file: - * `key_path` – path to the SA key generated using the CLI. - * `cloud_id` – cloud ID. You can get a list of available clouds with the command `yc resource-manager cloud list`. - * `profile` – profile name from the file `~/.aws/config`. - * `folder_id` – Cloud folder ID. Can be obtained with the command `yc resource-manager folder list`. - -Now, being in the `yandex_cloud` directory, you can run the `terraform init` command to install the provider and initialize the modules. Next you need to run a series of commands: -* `terraform plan` – creating a plan for future infrastructure. -* `terraform init` (re-call) – creating resources in the cloud.
\ No newline at end of file diff --git a/ydb/docs/en/core/sre/ansible/index.md b/ydb/docs/en/core/sre/ansible/index.md deleted file mode 100644 index 550d19d5725..00000000000 --- a/ydb/docs/en/core/sre/ansible/index.md +++ /dev/null @@ -1,8 +0,0 @@ -# Working with {{ ydb-short-name }} using Ansible - -This section of {{ ydb-short-name }} documentation contains a collection of articles intended for SRE's managin {{ ydb-short-name }} clusters using [Ansible](https://www.ansible.com/). This is the recommended approach to running production {{ ydb-short-name }} clusters unless your organization have already embraced [Kubernetes](../kubernetes/index.md). - -The key articles to get started with this section: - -* [Initial deployment](initial-deployment.md) -* [Preparing VMs with Terraform](preparing-vms-with-terraform.md)
\ No newline at end of file diff --git a/ydb/docs/en/core/sre/ansible/initial-deployment.md b/ydb/docs/en/core/sre/ansible/initial-deployment.md deleted file mode 100644 index e1f29c3601b..00000000000 --- a/ydb/docs/en/core/sre/ansible/initial-deployment.md +++ /dev/null @@ -1,281 +0,0 @@ -# Deploying {{ ydb-short-name }} cluster with Ansible - -This guide outlines the process of deploying a {{ ydb-short-name }} cluster on a group of servers using Ansible. {{ ydb-short-name }} can be deployed on any desired number of servers, but the minimum number of servers in the cluster should not be less than eight for the `block-4-2` redundancy model and nine servers for the `mirror-3-dc` redundancy model. You can learn about redundancy models from the article [{#T}](../../deploy/configuration/config.md#domains-blob). - -During operation, the cluster can be [expanded](../../maintenance/manual/cluster_expansion.md) without suspending access to the databases for users. - -{% note info %} - -**Recommended Server Requirements**: - -* 16 CPUs (calculated based on the utilization of 8 CPUs by the storage node and 8 CPUs by the dynamic node). -* 16 GB RAM (recommended minimum RAM). -* An additional 120 GB network SSD drive (cannot be smaller – installation requirements for {{ ydb-short-name }}). -* SSH access; -* Network connectivity between machines in the cluster. -* OS: Ubuntu 18+, Debian 9+. -* Internet access for updating repositories and downloading necessary packages. - -{% endnote %} - -You can download the repository with the playbook for installing {{ ydb-short-name }} on the cluster from GitHub – `git clone https://github.com/ydb-platform/ydb-ansible-examples.git`. This repository contains: installation templates for deploying {{ ydb-short-name }} on a cluster of eight servers – `8-nodes-block-4-2`, and nine servers – `9-nodes-mirror-3-dc`, as well as scripts for generating TLS certificates and requirement files for installing necessary Python packages. - -{% cut "Repository Structure" %} - -{% include [repo-tree](./_includes/repo-tree.md) %} - -{% endcut %} - - -To work with the project on a local (intermediate or installation) machine, you will need: Python 3 version 3.10+ and Ansible core version 2.15.2 or higher. Ansible can be installed and run globally (installed in the system) or in a virtual environment. If Ansible is already installed – you can move on to the step ["Configuring the Ansible project"](#ansible-project-setup), if Ansible is not yet installed, install it using one of the following methods: - -{% list tabs %} - -- Installing Ansible globally (in the system) - - * Update the apt package list – `sudo apt update`. - * Upgrade packages – `sudo apt upgrade`. - * Install the `software-properties-common` package to manage your distribution's software sources – `sudo apt install software-properties-common`. - * Add a new PPA to apt – `sudo add-apt-repository --yes --update ppa:ansible/ansible`. - * Install Ansible – `sudo apt install ansible-core`. - * Check the Ansible core version – `ansible --version` - -- Installing Ansible in a Python virtual environment - - * Update the apt package list – `sudo apt update`. - * Install the `venv` package for Python3 – `sudo apt install python3-venv` - * Create a directory where the virtual environment will be created and where the playbooks will be downloaded. For example, `mkdir ydb-install-ansible`. - * Go to the created directory and create a virtual environment – `python3 -m venv ydb-ansible`. - * Activate the virtual environment – `source venv/bin/activate`. All further actions with Ansible are performed inside the virtual environment. You can exit it with the command `deactivate`. - * Install the recommended version of Ansible using the command `pip install -r requirements.txt`, while in the root directory of the downloaded repository. - * Check the Ansible core version – `ansible --version` - -{% endlist %} - - -## Configuring the Ansible project {#ansible-project-setup} - -Navigate to the root directory of the downloaded repository and execute the command `ansible-galaxy install -r requirements.yaml` – this will download the Ansible collections `ydb_platform.ydb` and `community.general`, which contain roles and plugins for installing {{ ydb-short-name }}. - -[Download](../../downloads/index.md#ydb-server) the archive of the current version of {{ ydb-short-name }} into the project's root directory. For example, using wget: `wget https://binaries.ydb.tech/release/23.3.17/ydbd-23.3.17-linux-amd64.tar.gz` and also copy the private part of the SSH key for accessing the {{ ydb-short-name }} cluster servers to the same location. The SSH key should have the following permissions: -```text --rw------- (600) # Only the owner has read and write permission. -``` -You can set the required permissions with the command `sudo chmod 600 <ssh-key name>`. - -Next, you can go to the TLS directory and specify in the file ydb-ca-nodes.txt a list of FQDNs for which TLS certificates will be generated. By default, the list looks as follows: -```text -static-node-1 static-node-1.ydb-cluster.com -static-node-2 static-node-2.ydb-cluster.com -static-node-3 static-node-3.ydb-cluster.com -static-node-4 static-node-4.ydb-cluster.com -static-node-5 static-node-5.ydb-cluster.com -static-node-6 static-node-6.ydb-cluster.com -static-node-7 static-node-7.ydb-cluster.com -static-node-8 static-node-8.ydb-cluster.com -static-node-9 static-node-9.ydb-cluster.com -``` - -Generate a set of TLS certificates, which will be placed in the CA subdirectory (`TLS/CA/certs/<create date_crete time>`) using the script `ydb-ca-update.sh`. - -After generating the TLS certificates, installing the Ansible collections, uploading the private part of the SSH key, and downloading the current version of {{ ydb-short-name }}, you need to update the inventory files according to the chosen type of cluster for deployment. - -### Editing the project's inventory files {#inventory-edit} - -Regardless of the type of cluster being created (eight servers – `8-nodes-block-4-2` or nine servers – `9-nodes-mirror-3-dc`), the main parameters for installing and configuring {{ ydb-short-name }} are contained in the inventory file `50-inventory.yaml`, which is located in the `<cluster model>/inventory/` directory. - -In the inventory file `50-inventory.yaml`, you need to specify the current list of FQDNs of the servers where {{ ydb-short-name }} will be installed. By default, the list appears as follows: - ```yaml - all: - children: - ydb: - hosts: - static-node-1.ydb-cluster.com: - static-node-2.ydb-cluster.com: - static-node-3.ydb-cluster.com: - static-node-4.ydb-cluster.com: - static-node-5.ydb-cluster.com: - static-node-6.ydb-cluster.com: - static-node-7.ydb-cluster.com: - static-node-8.ydb-cluster.com: - static-node-9.ydb-cluster.com: - ``` - -Next, you need to make the following changes in the `vars` section of the inventory file: - * `ansible_user` – specify the user for Ansible to connect via SSH. - * `ansible_ssh_common_args: "-o ProxyJump=<ansible_user>@<static-node-1 IP>"` – option for connecting Ansible to a server by IP, from which {{ ydb-short-name }} will be installed (including ProxyJump server). It is used when installing {{ ydb-short-name }} from a local machine that is not included in the private DNS zone. - * `ansible_ssh_private_key_file` – change the default ssh-key name to the actual one: `"../<ssh-private-key-name>"`. - * `ydb_tls_dir` – specify the current path part (`/files/CA/certs/<date_time create certs>`) to the security certificates after they have been generated by the `ydb-ca-update.sh` script. - * `ydb_brokers` – list the FQDNs of the broker nodes. For example: - ```yaml - ydb_brokers: - - static-node-1.ydb-cluster.com - - static-node-2.ydb-cluster.com - - static-node-3.ydb-cluster.com - ``` - * `ydb_cores_static` – set the number of CPU cores consumed by the static node; - * `ydb_cores_dynamic` – set the number of CPU cores consumed by the dynamic node; - -The value of the `ydb_database_groups` variable in the `vars` section has a fixed value tied to the redundancy type and does not depend on the size of the cluster: -* For the redundancy type `block-4-2`, the value of `ydb_database_groups` is seven. -* For the redundancy type `mirror-3-dc`, the value of `ydb_database_groups` is eight. - -The values of the `system_timezone` and `system_ntp_servers` variables depend on the infrastructure properties where the YDB cluster is being deployed. By default, `system_ntp_servers` includes a set of NTP servers without considering the geographical location of the infrastructure on which the YDB cluster will be deployed. We strongly recommend using a local NTP server for on-premise infrastructure and the following NTP servers for cloud providers: - -{% list tabs %} - -- AWS - * `system_timezone`: USA/<region_name> - * `system_ntp_servers`: [169.254.169.123, time.aws.com] [Learn more](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/set-time.html#configure-time-sync) about AWS NTP server settings. - -- Azure - * You can read about how time synchronization is configured on Azure virtual machines in [this](https://learn.microsoft.com/en-us/azure/virtual-machines/linux/time-sync) article. - -- Alibaba - * The specifics of connecting to NTP servers in Alibaba are described in [this article](https://www.alibabacloud.com/help/en/ecs/user-guide/alibaba-cloud-ntp-server). - -- Yandex Cloud - * `system_timezone`: Europe/Moscow - * `system_ntp_servers`: [0.ru.pool.ntp.org, 1.ru.pool.ntp.org, ntp0.NL.net, ntp2.vniiftri.ru, ntp.ix.ru, ntps1-1.cs.tu-berlin.de] [Learn more](https://cloud.yandex.ru/en/docs/tutorials/infrastructure-management/ntp) about Yandex Cloud NTP server settings. - -{% endlist %} - -No changes to other sections of the `50-inventory.yaml` configuration file are required. Next, you can change the standard YDB root user password contained in the encrypted inventory file `99-inventory-vault.yaml` and in the file `ansible_vault_password_file.txt`. To change the password – specify the new password in the `ansible_vault_password_file.txt` file and duplicate it in the `99-inventory-vault.yaml` file in the format: - ```yaml - all: - children: - ydb: - vars: - ydb_password: <new password> - ``` - -To encrypt `99-inventory-vault.yaml`, execute the command `ansible-vault encrypt inventory/99-inventory-vault.yaml`. - -After modifying the inventory files, you can proceed to prepare the {{ ydb-short-name }} configuration file. - - -### Preparing the {{ ydb-short-name }} Configuration File {#ydb-config-prepare} - -The {{ ydb-short-name }} configuration file contains the settings for {{ ydb-short-name }} nodes and is located in the subdirectory `/files/config.yaml`. A detailed description of the configuration file settings for {{ ydb-short-name }} can be found in the article [{#T}](../../deploy/configuration/config.md). - -The default {{ ydb-short-name }} configuration file already includes almost all the necessary settings for deploying the cluster. You need to replace the standard FQDNs of hosts with the current FQDNs in the `hosts` and `blob_storage_config` sections: -* `hosts` section: - ```yaml - ... - hosts: - - host: static-node-1.ydb-cluster.com - host_config_id: 1 - walle_location: - body: 1 - data_center: 'zone-a' - rack: '1' - ... - ``` -* `blob_storage_config` section: - ```yaml - ... - - fail_domains: - - vdisk_locations: - - node_id: static-node-1.ydb-cluster.com - pdisk_category: SSD - path: /dev/disk/by-partlabel/ydb_disk_1 - ... - ``` - -The rest of the sections and settings in the configuration file can remain unchanged. - - -## Deploying the {{ ydb-short-name }} cluster {#erasure-setup} - -{% note info %} - -The minimum number of servers in a {{ ydb-short-name }} cluster is eight servers for the `block-4-2` redundancy model and nine servers for the `mirror-3-dc` redundancy model. - -In `mirror-3-dc` servers should be distributed across three availability zones or datacenters as evenly as possible. - -{% endnote %} - -The [repository](https://github.com/ydb-platform/ydb-ansible-examples) contains two ready sets of templates for deploying a {{ ydb-short-name }} cluster of eight (redundancy model `block-4-2`) and nine servers (`mirror-3-dc`). Either of the provided options can be scaled to any required number of servers, taking into account a number of technical requirements. - -To prepare your own template, you can follow the instructions below: -1. Create a copy of the directory with the ready example (`9-nodes-mirror-3-dc` or `8-nodes-block-4-2`). -2. Specify the FQDNs of the servers in the file `TLS/ydb-ca-nodes.txt` and execute the script `ydb-ca-update.sh` to generate sets of TLS certificates. -3. Make changes to the inventory files of the template according to the [instructions](#inventory-edit). -4. Make changes to the {{ ydb-short-name }} configuration file according to the [instructions](#ydb-config-prepare). -5. Execute the command `ansible-playbook setup_playbook.yaml`, while in the directory of the cloned template. - - -## Installation script execution plan for {{ ydb-short-name }} {#ydb-playbook-run} - -The sequence of role executions and their brief descriptions: -1. The `packages` role configures repositories, manages APT preferences and configurations, fixes unconfigured packages, and installs necessary software packages depending on the distribution version. -2. The `system` role sets up system settings, including clock and timezone configuration, time synchronization via NTP with `systemd-timesyncd`, configuring `systemd-journald` for log management, kernel module loading configuration, kernel parameter optimization through `sysctl`, and CPU performance tuning using `cpufrequtils`. -3. The `ydb` role performs tasks related to checking necessary variables, installing base components and dependencies, setting up system users and groups, deploying and configuring {{ ydb-short-name }}, including managing TLS certificates and updating configuration files. -4. The `ydb-static` role prepares and launches static nodes of {{ ydb-short-name }}, including checking necessary variables and secrets, formatting and preparing disks, creating and launching `systemd unit` for the storage node, as well as initializing the storage and managing database access. -5. The `ydb-dynamic` role configures and manages dynamic nodes of {{ ydb-short-name }}, including checking necessary variables, creating configuration and `systemd unit` files for each dynamic node, launching these nodes, obtaining a token for {{ ydb-short-name }} access, and creating a database in {{ ydb-short-name }}. - -{% cut "Detailed step-by-step installation process description" %} - -{% include [ansible-install-steps](./_includes/ansible-install-steps.md) %} - -{% endcut %} - -As a result of executing the playbook, a {{ ydb-short-name }} cluster will be created, with a test database named `database`, a `root` user with maximum access rights created, and [Embedded UI](../../maintenance/embedded_monitoring/index.md) running on port 8765. To connect to the Embedded UI, you can set up SSH tunneling. For this, execute the command `ssh -L 8765:localhost:8765 -i <ssh private key> <user>@<first-ydb-static-node-ip>` on your local machine. After successfully establishing the connection, you can navigate to the URL [localhost:8765](http://localhost:8765): - - - -## Monitoring the cluster state {#troubleshooting} - -After successfully creating the {{ ydb-short-name }} cluster, you can check its state using the Embedded UI – [http://localhost:8765/monitoring/cluster/tenants](http://localhost:8765/monitoring/cluster/tenants): - - - -This section displays the following parameters of the {{ ydb-short-name }} cluster, reflecting its state: -* `Tablets` – a list of running [tablets](../../concepts/cluster/common_scheme_ydb.md#tablets). All tablet state indicators should be green; -* `Nodes` – the number and state of static and dynamic nodes launched in the cluster. The node state indicator should be green, and the ratio of created to launched nodes should be equal. For example, 27/27 for a nine-node cluster. -The `Load` indicators (amount of RAM used) and `Storage` (amount of disk space used) should also be green. - -You can check the state of the storage group in the `storage` section – [http://localhost:8765/monitoring/cluster/storage](http://localhost:8765/monitoring/cluster/storage): - - - -The `VDisks` indicators should be green, and the `state` status (found in the tooltip when hovering over the Vdisk indicator) should be `Ok`. More about the cluster state indicators and monitoring can be read in the article [{#T}](../../maintenance/embedded_monitoring/ydb_monitoring.md). - -## Cluster Testing { #testing } - -You can test the cluster using the built-in load tests in YDB CLI. To do this, download YDB CLI version [2.5.0](https://storage.yandexcloud.net/yandexcloud-ydb/release/2.5.0/linux/amd64/ydb) to the machine where Ansible is installed. For example, using wget: `wget https://storage.yandexcloud.net/yandexcloud-ydb/release/2.5.0/linux/amd64/ydb`. - -Make the downloaded binary file executable – `chmod +x ydb` and execute the connection check command: -```shell -./ydb \ -config profile create <profile name> \ --d /Root/database \ --e grpcs://< FQDN node >:2135 \ ---ca-file <path to generated certs>/CA/certs/ca.crt \ ---user root \ ---password-file <path to vault password file>/ansible_vault_password_file -``` -Command parameters and their values: -* `config profile create` – This command is used to create a connection profile. You specify the profile name. More detailed information on how to create and modify profiles can be found in the article [{#T}](../../reference/ydb-cli/profile/create.md). -* `-e` – Endpoint, a string in the format `protocol://host:port`. You can specify the FQDN of any cluster node and omit the port. By default, port 2135 is used. -* `--ca-file` – Path to the root certificate for connections to the database using `grpcs`. The certificate is created by the `ydb-ca-update.sh` script in the `TLS` directory and is located at the path `TLS/CA/certs/` relative to the root of the ydb-ansible-examples repository. -* `--user` – The user for connecting to the database. By default, the user `root` is created when executing the `setup_playbook.yaml` playbook. -* `--password-file` – Path to the password file. In each folder with a YDB cluster deployment template, there is an `ansible_vault_password_file` that contains the password for the user `root`. - -You can check if the profile has been created using the command `./ydb config profile list`, which will display a list of profiles. After creating a profile, you need to activate it with the command `./ydb config profile activate <profile name>`. To verify that the profile has been activated, you can rerun the command `./ydb config profile list` – the active profile will have an (active) mark. - -To execute a YQL query, you can use the command `./ydb yql -s 'select 1;'`, which will return the result of the `select 1` command in table form to the terminal. After checking the connection, you can create a test table with the command: -`./ydb workload kv init --init-upserts 1000 --cols 4`. This will create a test table `kv_test` consisting of 4 columns and 1000 rows. You can verify that the `kv_test` table was created and filled with test data by using the command `./ydb yql -s 'select * from kv_test limit 10;'`. - -The terminal will display a table of 10 rows. Now you can perform cluster performance testing. The article [{#T}](../../reference/ydb-cli/workload-kv.md) describes 5 types of workloads (`upsert`, `insert`, `select`, `read-rows`, `mixed`) and the parameters for their execution. An example of executing the `upsert` test workload with the parameter to print the execution time `--print-timestamp` and standard execution parameters is: `./ydb workload kv run upsert --print-timestamp`. - -A report of the following type will be displayed in the terminal: -``` -Window Txs/Sec Retries Errors p50(ms) p95(ms) p99(ms) pMax(ms) Timestamp -1 727 0 0 11 27 71 116 2024-02-14T12:56:39Z -2 882 0 0 10 21 29 38 2024-02-14T12:56:40Z -3 848 0 0 10 22 30 105 2024-02-14T12:56:41Z -... -``` - -After completing the tests, the `kv_test` table can be deleted with the command: `./ydb workload kv clean`. More details on the options for creating a test table and tests can be read in the article [{#T}](../../reference/ydb-cli/workload-kv.md). diff --git a/ydb/docs/en/core/sre/ansible/preparing-vms-with-terraform.md b/ydb/docs/en/core/sre/ansible/preparing-vms-with-terraform.md deleted file mode 100644 index c533cb8d55c..00000000000 --- a/ydb/docs/en/core/sre/ansible/preparing-vms-with-terraform.md +++ /dev/null @@ -1,168 +0,0 @@ -# Deploying infrastructure for cluster {{ ydb-short-name }} using Terraform - -There are three recommended ways to deploy {{ ydb-short-name }} clusters for production use: using [Ansible](initial-deployment.md), [Kubernetes](../kubernetes/initial-deployment.md) or [manually](../../deploy/index.md). If the option with Kubernetes is practically self-sufficient, then for the options with Ansible and manually, you need ssh access to the required number of correctly configured servers or virtual machines to start. This article describes how you can create and configure the set of virtual machines required for the {{ ydb-short-name }} cluster on various cloud providers. - -**[Terraform](https://www.terraform.io/)** is open source infrastructure management software based on the Infrastructure as Code model. The same approach is used in Ansible, a configuration management system. Terraform and Ansible work at different levels: Terraform manages the infrastructure, and Ansible configures the environments on the VM: - - - -The configuration for setting up the VM environment is described in YAML format, and the infrastructure code is written in [HCL](https://github.com/hashicorp/hcl) (Terraform configuration language). The basic logical unit of recording in HCL is the "block". A block consists of a keyword identifying its type, a name, and curly braces indicating the body of the block. For example, this is what a virtual server control block in AWS might look like: -```hcl -resource "aws_instance" "ydb-vm" { - count = var.instance_count - ami = "ami-008fe2fc65df48dac" - instance_type = "t2.micro" - key_name = var.req_key_pair - vpc_security_group_ids = [var.input_security_group_id] - subnet_id = element(var.input_subnet_ids, count.index % length(var.input_subnet_ids)) - - tags = { - Name = "ydb-node-${count.index +1}" - Username = "ubuntu" - } - -} -``` - -Blocks can be located one after another in one file and be independent, they can refer to each other and be dependent, and they can also be nested inside each other. - -Main block types: -* `resource` – block for initializing an infrastructure resource (VM, network, subnet, disk, DNS zone, etc.); -* `provider` – block initialization of the provider, API version and authentication data; -* `variable` – a variable with both a default value and an empty one for storing data entered by the user or transmitted by other blocks; -* `output` – output data to the terminal and save it in a variable; -* `data` – variable for requesting data from external cloud resources that are not represented in the created infrastructure; -* `module` – logical grouping of resources that can be reused several times within the same or different projects; -* `terraform` – a block for setting the behavior of Terraform itself, including the version of Terraform and the providers used, as well as settings for the backend, which is used to store Terraform state. - -Blocks are written in files with a `.tf` extension and are logically grouped in directories, which in Terraform terminology are called modules. A module usually consists of the following files: -* `main.tf` – the main file that contains the infrastructure code. There may be multiple files containing infrastructure code. -* `variables.tf` – local module variables that receive data from other modules or have default values. -* `outputs.tf` – variables that contain the results of the resource (VM IP addresses, network/subnet IDs, etc.). - -Modules are connected to the project in the root file `main.tf` as follows: -``` -module "vpc" { - source = "./modules/vpc" - subnets_count = var.subnets_count - subnets_availability_zones = var.availability_zones -} -``` -In the example, the `vpc` module is connected (the module name is assigned when connecting). The required parameter is `source` - the path to the directory where the module is located. `subnets_count` and `subnets_availability_zones` are variables inside the `vpc` module that take values from the global level variables `var.subnets_count`, `var.availability_zones`. - -Modules, as well as blocks, are located one after another in the root `main.tf` of the project. The main advantage of the modular approach to project organization is the ability to easily manage logically related sets of resources. Therefore, our [repository](https://github.com/ydb-platform/ydb-terraform) with ready-made Terraform scripts is organized as follows: -```txt -. -├── README.md -├── README_RU.md -├── aws -│ ├── README.md -│ ├── README_RU.md -│ ├── main.tf -│ ├── modules -│ │ ├── dns -│ │ ├── eip -│ │ ├── instance -│ │ ├── key_pair -│ │ ├── security -│ │ └── vpc -│ └── variables.tf -├── azure -│ ├── README.md -│ ├── README_RU.md -│ ├── main.tf -│ ├── modules -│ │ ├── dns -│ │ ├── resource_group -│ │ ├── security -│ │ ├── vm -│ │ └── vpc -│ └── variables.tf -├── ... -``` - -Поддиректории содержат два `readme`, файл `variables.td` с локальными переменными модуля и основной файл `main.tf`, который подключает модули из поддиректории `modules`. Набор модулей зависит от облачного провайдера. Базовые модули, функционально одинаковые для всех провайдеров имеют одинаковые названия: -* `vpc` – модуль управления облачной сетью и подсетями. -* `dns` – модуль управления DNS-зоной и DNS-записями. -* `security` – модуль управления группами безопасности. -* `instance` – модуль управления ВМ. - -Для того, чтобы воспользоваться готовыми Terraform сценариями из репозитория, нужно скачать репозиторий командой `git clone https://github.com/ydb-platform/ydb-terraform.git`, внести изменения в конфигурационный файл Terraform `~/.terraformrc`, задать актуальные значения глобальных переменных сценария и скачать CLI того облачного провайдера, где будет создана инфраструктура. - -Если вы планируете использовать несколько провайдеров, можно добавить следующий код в `~/.terraformrc`, который установит пути скачивания для всех провайдеров описанных ниже: -``` -provider_installation { - network_mirror { - url = "https://terraform-mirror.yandexcloud.net/" - include = ["registry.terraform.io/*/*"] - } - direct { - exclude = ["registry.terraform.io/*/*"] - exclude = ["terraform.storage.ydb.tech/*/*"] - } - - filesystem_mirror { - path = "/Applications/ - } - } -``` - -The subdirectories contain two `readme`, a file `variables.td` with local module variables and a main file `main.tf`, which includes modules from the `modules` subdirectory. The set of modules depends on the cloud provider. Basic modules, functionally the same for all providers, have the same names: -* `vpc` – cloud network and subnet management module. -* `dns` – module for managing DNS zone and DNS records. -* `security` – security group management module. -* `instance` – VM control module. - -In order to use ready-made Terraform scripts from the repository, you need to download the repository with the command `git clone https://github.com/ydb-platform/ydb-terraform.git`, make changes to the Terraform configuration file `~/.terraformrc`, set the current values of global script variables and download the CLI of the cloud provider where the infrastructure will be created. - -If you plan to use multiple providers, you can add the following code to `~/.terraformrc`, which will set the download paths for all providers described below: -``` -provider_installation { - network_mirror { - url = "https://terraform-mirror.yandexcloud.net/" - include = ["registry.terraform.io/*/*"] - } - direct { - exclude = ["registry.terraform.io/*/*"] - exclude = ["terraform.storage.ydb.tech/*/*"] - } - - filesystem_mirror { - path = "/Applications/ - } - } -``` - -If you are already using Terraform providers provided in the [official repository](https://registry.terraform.io/browse/providers), they will continue to work. - -The following are step-by-step instructions for creating infrastructure in [AWS](#aws-cluster), [Azure](#aws-cluster), [GCP](#gcp-cluster), [Yandex Cloud](#gcp-cluster). The scenarios proposed by Terraform deploy the same type of infrastructure: - -The infrastructure includes: - -* Nine virtual VMs (16 CPU, 32 GB RAM, additional 200 GB disk). -* Cloud network and three subnets (one subnet per availability zone). -* Private DNS zone. -* Security groups allowing traffic on ports: 22, icmp, 8765. - -Most cluster parameters are adjustable (number of VMs, size and type of connected disk, number of networks, DNS zone domain, etc.), but please note that there are recommended values for cluster parameters that are already defined as default values. Changing them downward can render the cluster inoperable. These recommended values for cluster parameters are: -* Number of CPU cores. The minimum recommended number of CPU cores is 16 pieces. -* RAM size. The minimum recommended amount of RAM is 32 GB. -* Volume of the attached disk. The minimum recommended size of the attached disk is 200 GB. - -## Create infrastructure in AWS to deploy {{ ydb-short-name }} cluster {#aws-cluster} - -{% include [aws](./_includes/terraform/aws.md) %} - -## Create infrastructure in Azure to deploy {{ ydb-short-name }} cluster {#azure-cluster} - -{% include [azure](./_includes/terraform/azure.md) %} - -## Creating infrastructure in Google Cloud Platform to deploy {{ ydb-short-name }} cluster {#gcp-cluster} - -{% include [gcp](./_includes/terraform/gcp.md) %} - -## Creating an infrastructure in Yandex Cloud for deploying the {{ ydb-short-name }} cluster {#yc-cluster} - -{% include [yc](./_includes/terraform/yc.md) %} - -With the help of Yandex Cloud provider, you can not only create an infrastructure for further deployment of a YDB cluster on it using [Ansible](./initial-deployment.md), but also manage [serverless or dedicated](https://cloud.yandex.ru/ru /services/ydb) version of YDB directly from Terraform. Read about the possibilities of working with YDB in Yandex Cloud in the section [Working with YDB via Terraform](https://cloud.yandex.ru/ru/docs/ydb/terraform/intro) of the Yandex Cloud documentation.
\ No newline at end of file diff --git a/ydb/docs/en/core/sre/ansible/toc_p.yaml b/ydb/docs/en/core/sre/ansible/toc_p.yaml deleted file mode 100644 index 729ed7802c3..00000000000 --- a/ydb/docs/en/core/sre/ansible/toc_p.yaml +++ /dev/null @@ -1,7 +0,0 @@ -items: -- name: Overview - href: index.md -- name: Initial deployment - href: initial-deployment.md -- name: Preparing VMs with Terraform - href: preparing-vms-with-terraform.md
\ No newline at end of file diff --git a/ydb/docs/en/core/sre/index.md b/ydb/docs/en/core/sre/index.md deleted file mode 100644 index 19eed406896..00000000000 --- a/ydb/docs/en/core/sre/index.md +++ /dev/null @@ -1,7 +0,0 @@ -# {{ ydb-short-name }} for SRE - -This section of {{ ydb-short-name }} documentation covers everything you need to know to run a production-grade {{ ydb-short-name }} cluster. It is subdivided based on what's your preferred approach to managing infrastructure: - -* **[Ansible](ansible/index.md).** For deployments on bare metal and virtual machines. -* **[Kubernetes](kubernetes/index.md).** For containerized deployments. -* **[Manual](../cluster/index.md).** Generic instructions.
\ No newline at end of file diff --git a/ydb/docs/en/core/sre/kubernetes/index.md b/ydb/docs/en/core/sre/kubernetes/index.md deleted file mode 100644 index 18d1c36ffaf..00000000000 --- a/ydb/docs/en/core/sre/kubernetes/index.md +++ /dev/null @@ -1,7 +0,0 @@ -# Working with {{ ydb-short-name }} using Kubernetes - -This section of {{ ydb-short-name }} documentation contains a collection of articles intended for SRE's deploying {{ ydb-short-name }} clusters using [Kubernetes](https://kubernetes.io/). This is the recommended approach to running production {{ ydb-short-name }} clusters. If your organization is not comfortable with Kubernetes yet, we'd recommend [using Ansible instead](../ansible/index.md). - -The key articles to get started with this section: - -* [Initial deployment](initial-deployment.md)
\ No newline at end of file diff --git a/ydb/docs/en/core/sre/kubernetes/initial-deployment.md b/ydb/docs/en/core/sre/kubernetes/initial-deployment.md deleted file mode 100644 index c9f4fc26e09..00000000000 --- a/ydb/docs/en/core/sre/kubernetes/initial-deployment.md +++ /dev/null @@ -1,325 +0,0 @@ -# Getting started with {{ ydb-short-name }} in {{ k8s }} - -Deploying {{ ydb-short-name }} in {{ k8s }} is a simple way to set up and run a {{ ydb-short-name }} cluster. {{ k8s }} allows to use an universal approach to managing your application in any cloud service provider. This guide provides instructions on how to deploy {{ ydb-short-name }} in [AWS EKS](https://aws.amazon.com/eks/) or [{{ managed-k8s-full-name }}](https://cloud.yandex.com/services/managed-kubernetes). - -## Prerequisites - -{{ ydb-short-name }} is delivered as a [Helm](https://helm.sh/) chart that is a package with templates of {{ k8s }} structures. For more information about Helm, see the [documentation](https://helm.sh/docs/). The {{ ydb-short-name }} chart can be deployed in the following environment: - -1. A {{ k8s }} cluster with version 1.20 or higher. It needs to support [Dynamic Volume Provisioning](https://kubernetes.io/docs/concepts/storage/dynamic-provisioning/). Follow the instructions below if you don't have a suitable cluster yet. -2. The `kubectl` command line tool is [installed](https://kubernetes.io/docs/tasks/tools/install-kubectl) and {{ k8s }} cluster access is configured. -3. The Helm package manager with a version higher than 3.1.0 is [installed](https://helm.sh/docs/intro/install/). - -{% include [_includes/storage-device-requirements.md](../../_includes/storage-device-requirements.md) %} - -## Creating a {{ k8s }} cluster - -Skip this section if you have already configured a suitable {{ k8s }} cluster. - -{% list tabs %} - -- AWS EKS - - 1. Configure `awscli` and `eksctl` to work with AWS resources according to the [documentation](https://docs.aws.amazon.com/eks/latest/userguide/getting-started-eksctl.html). - - 2. Configure `kubectl` to work with a {{ k8s }} cluster. - - 3. Run the following command: - - ```bash - eksctl create cluster \ - --name ydb \ - --nodegroup-name standard-workers \ - --node-type c5a.2xlarge \ - --nodes 3 \ - --nodes-min 1 \ - --nodes-max 4 - ``` - - This command will create a {{ k8s }} cluster named `ydb`. The `--node-type` flag indicates that the cluster is deployed using `c5a.2xlarge` (8vCPUs, 16 GiB RAM) instances. This meets minimal guidelines for running {{ ydb-short-name }}. - - It takes 10 to 15 minutes on average to create a {{ k8s }} cluster. Wait for the process to complete before proceeding to the next step of {{ ydb-short-name }} deployment. The `kubectl` configuration will be automatically updated to work with the cluster after it is created. - - -- {{ managed-k8s-full-name }} - - Follow the instructions in the [{{ managed-k8s-full-name }} quick start guide](https://cloud.yandex.com/en/docs/managed-kubernetes/quickstart). - -{% endlist %} - -## Overview of {{ ydb-short-name }} Helm chart - -The Helm chart installs [YDB Kubernetes Operator](https://github.com/ydb-platform/ydb-kubernetes-operator) to the {{ k8s }} cluster. It is a controller that follows the [Operator](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/) design pattern. It implements the logic required for deploying and managing {{ ydb-short-name }} components. - -A {{ ydb-short-name }} cluster consists of two kinds of nodes: - -* **Storage nodes** ([Storage](https://github.com/ydb-platform/ydb-kubernetes-operator/tree/master/samples/storage-block-4-2.yaml) resource) provide the data persistence layer. -* **Dynamic nodes** ([Database](https://github.com/ydb-platform/ydb-kubernetes-operator/tree/master/samples/database.yaml) resource) implement data access and processing. - -Create both resources with the desired parameters to deploy a {{ ydb-short-name }} cluster in {{ k8s }}. We'll follow this process in more detail below. The schema for these resources is [hosted on GitHub](https://github.com/ydb-platform/ydb-kubernetes-operator/tree/master/deploy/ydb-operator/crds). - -After the chart data is processed by the controller, the following resources are created: - -* [StatefulSet](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/): A workload controller that assigns stable network IDs and disk resources to each container. -* [Service](https://kubernetes.io/docs/concepts/services-networking/service/): An object that is used to access the created databases from applications. -* [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/): An object that is used to store the cluster configuration. - -See the operator's source code [on GitHub](https://github.com/ydb-platform/ydb-kubernetes-operator). The Helm chart is in the [deploy](https://github.com/ydb-platform/ydb-kubernetes-operator/tree/master/deploy) folder. -{{ ydb-short-name }} containers are deployed using `cr.yandex/yc/ydb` images. Currently, they are only available as prebuilt artifacts. - -## Environment preparation - -1. Clone the [ydb-kubernetes-operator](https://github.com/ydb-platform/ydb-kubernetes-operator) repository: - - ```bash - git clone https://github.com/ydb-platform/ydb-kubernetes-operator && cd ydb-kubernetes-operator - ``` - -2. Add the {{ ydb-short-name }} repository to Helm: - - Run the command: - - ```bash - helm repo add ydb https://charts.ydb.tech/ - ``` - * `ydb`: The repository alias. - * `https://charts.ydb.tech/`: The {{ ydb-short-name }} repository URL. - - Output: - - ```text - "ydb" has been added to your repositories - ``` - -3. Update the Helm chart index: - - Run the command: - - ```bash - helm repo update - ``` - - Output: - - ```text - Hang tight while we grab the latest from your chart repositories... - ...Successfully got an update from the "ydb" chart repository - Update Complete. ⎈Happy Helming!⎈ - ``` - -## Deploying a {{ ydb-short-name }} cluster - -### Install the {{ ydb-short-name }} {{ k8s }} operator - -Use `helm` to deploy the {{ ydb-short-name }} {{ k8s }} operator to the cluster: - - Run the command: - - ```bash - helm install ydb-operator ydb/ydb-operator - ``` - - * `ydb-operator`: The installation name. - * `ydb/ydb-operator`: The name of the chart in the repository you have added earlier. - - Result: - - ```text - NAME: ydb-operator - LAST DEPLOYED: Thu Aug 12 19:32:28 2021 - NAMESPACE: default - STATUS: deployed - REVISION: 1 - TEST SUITE: None - ``` - -### Deploy storage nodes - -{{ ydb-short-name }} supports a number of [storage topologies](../../cluster/topology.md). {{ ydb-short-name }} {{ k8s }} operator comes with a few sample configuration files for the most common topologies. This guide uses them as-is, but feel free to adjust them as needed or implement a new configuration file from scratch. - -Apply the manifest for creating storage nodes: - -{% list tabs %} - -- block-4-2 - - ```bash - kubectl apply -f samples/storage-block-4-2.yaml - ``` - - This will create 8 {{ ydb-short-name }} storage nodes that persist data using erasure coding. This takes only 50% of additional storage space to provide fault-tolerance. - -- mirror-3-dc - - ```bash - kubectl apply -f samples/storage-mirror-3-dc.yaml - ``` - - This will create 9 {{ ydb-short-name }} storage nodes that store data with replication factor 3. - -{% endlist %} - -This command creates a `StatefulSet` object that describes a set of {{ ydb-short-name }} containers with stable network IDs and disks assigned to them, as well as `Service` and `ConfigMap` objects that are required for the cluster to work. - -{{ ydb-short-name }} storage nodes take a while to initialize. You can check the initialization progress with `kubectl get storages.ydb.tech` or `kubectl describe storages.ydb.tech`. Wait until the status of the Storage resource changes to `Ready`. - -{% note warning %} - -The cluster configuration is static. The controller won't process any changes when the manifest is reapplied. You can only update cluster parameters such as version or disk size by creating a new cluster. - -{% endnote %} - -### Create a database and dynamic nodes - -{{ ydb-short-name }} database is a logical entity that is served by a number of dynamic nodes. A sample manifest that comes with {{ ydb-short-name }} {{ k8s }} operator creates a database named `database-sample` with 3 dynamic nodes. As with storage nodes, feel free to adjust the configuration as needed. - -Apply the manifest for creating a database and dynamic nodes: - -```bash -kubectl apply -f samples/database.yaml -``` - -{% note info %} - -The value referenced by `.spec.storageClusterRef.name` key must match the name of the `Storage` resource with storage nodes. - -{% endnote %} - -A `StatefulSet` object that describes a set of dynamic nodes is created after processing the manifest. The created database will be accessible from inside the {{ k8s }} cluster by the `database-sample` hostname or the `database-sample.<namespace>.svc.cluster.local` FQDN, where `namespace` indicates the namespace that was used for the installation. You can connect the database via port 2135. - -View the status of the created resource: - -```bash -kubectl describe database.ydb.tech -``` - -Result: - -``` -Name: database-sample -Namespace: default -Labels: <none> -Annotations: <none> -API Version: ydb.tech/v1alpha1 -Kind: Database -... -Status: - State: Ready -Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Normal Provisioning 8m10s ydb-operator Resource sync is in progress - Normal Provisioning 8m9s ydb-operator Resource sync complete - Normal TenantInitialized 8m9s ydb-operator Tenant /root/database-sample created -``` - -`State: Ready` means that the database is ready to be used. - - -### Test cluster operation - -Check how {{ ydb-short-name }} works: - - - 1. Check that all nodes are in the `Running` status: - - ```bash - kubectl get pods - ``` - - Result: - - ``` - NAME READY STATUS RESTARTS AGE - database-sample-0 1/1 Running 0 1m - database-sample-1 1/1 Running 0 1m - database-sample-2 1/1 Running 0 1m - database-sample-3 1/1 Running 0 1m - database-sample-4 1/1 Running 0 1m - database-sample-5 1/1 Running 0 1m - storage-sample-0 1/1 Running 0 1m - storage-sample-1 1/1 Running 0 1m - storage-sample-2 1/1 Running 0 1m - storage-sample-3 1/1 Running 0 1m - storage-sample-4 1/1 Running 0 1m - storage-sample-5 1/1 Running 0 1m - storage-sample-6 1/1 Running 0 1m - storage-sample-7 1/1 Running 0 1m - storage-sample-8 1/1 Running 0 1m - ``` - - 2. Start a new pod with [{{ ydb-short-name }} CLI]((../reference/ydb-cli/index.md)): - - ```bash - kubectl run -it --image=cr.yandex/crptqonuodf51kdj7a7d/ydb:22.4.44 --rm ydb-cli bash - ``` - - 3. Query the {{ ydb-short-name }} database: - - ```bash - ydb \ - --endpoint grpc://database-sample-grpc:2135 \ - --database /root/database-sample \ - table query execute --query 'SELECT 2 + 2;' - ``` - - * `--endpoint`: The database endpoint. - * `--database`: The name of the created database. - * `--query`: The query text. - - Result: - - ```text - ┌─────────┐ - | column0 | - ├─────────┤ - | 4 | - └─────────┘ - ``` - - -## Further steps - -After you have tested that the created {{ ydb-short-name }} cluster operates fine you can continue using it as you see fit. For example, if you just want to continue experimenting, you can use it to follow the [YQL tutorial](../../yql/tutorial/index.md). - -Below are a few more things to consider. - -### Monitoring - -{{ ydb-short-name }} provides standard mechanisms for collecting logs and metrics. Logging is done to standard `stdout` and `stderr` streams and can be redirected using popular solutions. For example, you can use a combination of [Fluentd](https://www.fluentd.org/) and [Elastic Stack](https://www.elastic.co/elastic-stack/). - -To collect metrics, `ydb-controller` provides resources like `ServiceMonitor`. They can be handled using [kube-prometheus-stack](https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack). - - -### Tuning allocated resources {#resource-allocation} - -You can limit resource consumption for each {{ ydb-short-name }} pod. If you leave the limit values empty, a pod can use the entire CPU time and VM RAM. This may cause undesirable effects. We recommend that you always specify the resource limits explicitly. - -To learn more about resource allocation and limits, see the [{{ k8s }} documentation](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/). - - -### Release the resources you don't use {#cleanup} - -If you no longer need the created {{ ydb-short-name }} cluster, delete it by following these steps: - - -1. To delete a {{ ydb-short-name }} database and its dynamic nodes, just delete the respective `Database` resource: - - ```bash - kubectl delete database.ydb.tech database-sample - ``` - -2. To delete {{ ydb-short-name }} storage nodes, run the following commands: - - ```bash - kubectl delete storage.ydb.tech storage-sample - kubectl delete pvc -l app.kubernetes.io/name=ydb - ``` - -3. To remove the {{ ydb-short-name }} {{ k8s }} operator, delete it with Helm: - - ```bash - helm delete ydb-operator - ``` - - * `ydb-operator`: The name of the release that the controller was installed under.
\ No newline at end of file diff --git a/ydb/docs/en/core/sre/kubernetes/toc_p.yaml b/ydb/docs/en/core/sre/kubernetes/toc_p.yaml deleted file mode 100644 index b296a61c4a0..00000000000 --- a/ydb/docs/en/core/sre/kubernetes/toc_p.yaml +++ /dev/null @@ -1,5 +0,0 @@ -items: -- name: Overview - href: index.md -- name: Initial deployment - href: initial-deployment.md
\ No newline at end of file diff --git a/ydb/docs/en/core/sre/toc_p.yaml b/ydb/docs/en/core/sre/toc_p.yaml deleted file mode 100644 index 95bb5899576..00000000000 --- a/ydb/docs/en/core/sre/toc_p.yaml +++ /dev/null @@ -1,15 +0,0 @@ -items: -- name: Overview - href: index.md -- name: Ansible - include: - mode: link - path: ansible/toc_p.yaml -- name: Kubernetes - include: - mode: link - path: kubernetes/toc_p.yaml -- name: Manual - include: - mode: link - path: ../cluster/toc_p.yaml
\ No newline at end of file diff --git a/ydb/docs/en/core/toc_i.yaml b/ydb/docs/en/core/toc_i.yaml index 65f14dfa2f1..77e474af50b 100644 --- a/ydb/docs/en/core/toc_i.yaml +++ b/ydb/docs/en/core/toc_i.yaml @@ -11,28 +11,33 @@ items: include: mode: link path: devops/toc_p.yaml - - -- { name: Tutorials, include: { mode: link, path: operations/toc_p.yaml } } -- { name: Recommendations, include: { mode: link, path: best_practices/toc_p.yaml } } -- { name: Managing databases, include: { mode: link, path: db/toc_p.yaml } } -- { name: Managing a cluster, include: { mode: link, path: cluster/toc_p.yaml } } - +- name: For DBA + include: + mode: link + path: dba/toc_p.yaml +- name: For Developers + include: + mode: link + path: dev/toc_p.yaml +- name: For Contributors + include: + mode: link + path: contributor/toc_p.yaml - name: Reference include: mode: link path: reference/toc_p.yaml - - - name: Questions and answers include: mode: link path: faq/toc_p.yaml -- name: For contributors +- name: Downloads include: mode: link - path: development/toc_p.yaml -- include: { mode: link, path: downloads/toc_p.yaml } + path: downloads/toc_p.yaml - name: Public talks href: public-talks.md -- { name: Changelog, include: { mode: link, path: toc_changelog.yaml } } +- name: Changelog + include: + mode: link + path: toc_changelog.yaml diff --git a/ydb/docs/en/core/troubleshooting/_includes/system_views/intro_cluster.md b/ydb/docs/en/core/troubleshooting/_includes/system_views/intro_cluster.md deleted file mode 100644 index e678dc5ba81..00000000000 --- a/ydb/docs/en/core/troubleshooting/_includes/system_views/intro_cluster.md +++ /dev/null @@ -1,5 +0,0 @@ -To enable internal introspection of the cluster state, the user can make queries to special system views. These tables are accessible from the cluster's root directory and use the `.sys` system path prefix. - -Cloud database users usually don't have access to cluster system tables, as cluster support and timely diagnostics are the prerogative of the cloud team. - -Hereinafter, in the descriptions of available fields, the **Key** column contains the corresponding table's primary key field index. diff --git a/ydb/docs/en/core/troubleshooting/_includes/system_views/intro_db.md b/ydb/docs/en/core/troubleshooting/_includes/system_views/intro_db.md deleted file mode 100644 index eaf9f909305..00000000000 --- a/ydb/docs/en/core/troubleshooting/_includes/system_views/intro_db.md +++ /dev/null @@ -1,14 +0,0 @@ -# Database system views - -You can make queries to special service tables (system views) to monitor the DB status. These tables are accessible from the root of the database tree and use the `.sys` system path prefix. - -You can find the corresponding table's primary key field index in the descriptions of available fields below. - -DB system views contain: - -* [Details of individual DB table partitions](#partitions). -* [Top queries by certain characteristics](#top-queries). -* [Query details](#query-metrics). -* [History of overloaded partitions](#top-overload-partitions). - -{% include [notes](notes.md) %} diff --git a/ydb/docs/en/core/troubleshooting/_includes/system_views/notes.md b/ydb/docs/en/core/troubleshooting/_includes/system_views/notes.md deleted file mode 100644 index da3a535d0df..00000000000 --- a/ydb/docs/en/core/troubleshooting/_includes/system_views/notes.md +++ /dev/null @@ -1,5 +0,0 @@ -{% note info %} - -Loads caused by accessing system views are more analytical in nature. Making frequent queries to them in large DBs will consume a lot of system resources. The recommended load is no more than 1-2 RPS. - -{% endnote %} diff --git a/ydb/docs/en/core/troubleshooting/_includes/system_views/partitions.md b/ydb/docs/en/core/troubleshooting/_includes/system_views/partitions.md deleted file mode 100644 index df3c85f771c..00000000000 --- a/ydb/docs/en/core/troubleshooting/_includes/system_views/partitions.md +++ /dev/null @@ -1,6 +0,0 @@ -{% include [header.md](partitions_header.md) %} - -Examples: - -{% include [example_yql](partitions_example_yql.md) %} - diff --git a/ydb/docs/en/core/troubleshooting/_includes/system_views/partitions_example_yql.md b/ydb/docs/en/core/troubleshooting/_includes/system_views/partitions_example_yql.md deleted file mode 100644 index c703e8b226b..00000000000 --- a/ydb/docs/en/core/troubleshooting/_includes/system_views/partitions_example_yql.md +++ /dev/null @@ -1,24 +0,0 @@ -Top 5 of most loaded partitions among all DB tables: - -> ```sql -> SELECT -> Path, -> PartIdx, -> CPUCores -> FROM `.sys/partition_stats` -> ORDER BY CPUCores DESC -> LIMIT 5 -> ``` - -List of DB tables with in-flight sizes and loads: - -> ```sql -> SELECT -> Path, -> COUNT(*) as Partitions, -> SUM(RowCount) as Rows, -> SUM(DataSize) as Size, -> SUM(CPUCores) as CPU -> FROM `.sys/partition_stats` -> GROUP BY Path -> ``` diff --git a/ydb/docs/en/core/troubleshooting/_includes/system_views/partitions_header.md b/ydb/docs/en/core/troubleshooting/_includes/system_views/partitions_header.md deleted file mode 100644 index bc6d74116c0..00000000000 --- a/ydb/docs/en/core/troubleshooting/_includes/system_views/partitions_header.md +++ /dev/null @@ -1,37 +0,0 @@ -## Partitions {#partitions} - -The following system view stores detailed information about individual [partitions](../../../concepts/datamodel/table.md#partitioning) of all DB tables: - -* `partition_stats`: Contains information about instant metrics and cumulative operation counters. Instant metrics are, for example, CPU load or count of in-flight [transactions](../../../concepts/transactions.md). Cumulative counters, for example, count the total number of rows read. - -The system view is designed to detect various irregularities in the load on a table partition or show the size of table partition data. - -Cumulative fields (`RowReads`, `RowUpdates`, and so on) store the accumulated values since the last start of the tablet serving the partition. - -Table structure: - -| Field | Description | ---- | --- -| `OwnerId` | ID of the SchemeShard serving the table.<br>Type: `Uint64`.<br>Key: `0`. | -| `PathId` | ID of the SchemeShard path.<br>Type: `Uint64`.<br>Key: `1`. | -| `PartIdx` | Partition sequence number.<br>Type: `Uint64`.<br>Key: `2`. | -| `DataSize` | Approximate partition size in bytes.<br>Type: `Uint64`. | -| `RowCount` | Approximate number of rows.<br>Type: `Uint64`. | -| `IndexSize` | Partition index size in a tablet.<br>Type: `Uint64`. | -| `CPUCores` | Double Instant value of load per partition (CPU share) | -| `TabletId` | ID of the tablet serving the partition.<br>Type: `Uint64`. | -| `Path` | Full path to the table.<br>Type: `Utf8`. | -| `NodeId` | ID of the node that the partition is being served on.<br>Type: `Uint32`. | -| `StartTime` | Last time when the tablet serving the partition was started.<br>Type: `Timestamp`. | -| `AccessTime` | Last time when data from the partition was read.<br>Type: `Timestamp`. | -| `UpdateTime` | Last time when data was written to the partition.<br>Type: `Timestamp`. | -| `RowReads` | Number of point reads since the start of the partition tablet.<br>Type: `Uint64`. | -| `RowUpdates` | Number of rows written since the start.<br>Type: `Uint64`. | -| `RowDeletes` | Number of rows deleted since the start.<br>Type: `Uint64`. | -| `RangeReads` | Number of row range reads since the start.<br>Type: `Uint64`. | -| `RangeReadRows` | Number of rows read in the ranges since the start.<br>Type: `Uint64`. | -| `InFlightTxCount` | Number of in-flight transactions.<br>Type: `Uint64`. | -| `ImmediateTxCompleted` | Number of one-shard transactions completed since the start.<br>Type: `Uint64`. | -| `CoordinatedTxCompleted` | Number of coordinated transactions completed since the start.<br>Type: `Uint64`. | -| `TxRejectedByOverload` | Number of transactions rejected due to overload (since the start).<br>Type: `Uint64`. | -| `TxRejectedByOutOfStorage` | Number of transactions rejected due to lack of storage space (since the start).<br>Type: `Uint64`. | diff --git a/ydb/docs/en/core/troubleshooting/_includes/system_views/query_metrics.md b/ydb/docs/en/core/troubleshooting/_includes/system_views/query_metrics.md deleted file mode 100644 index e2fc18f7158..00000000000 --- a/ydb/docs/en/core/troubleshooting/_includes/system_views/query_metrics.md +++ /dev/null @@ -1,6 +0,0 @@ -{% include [header.md](query_metrics_header.md) %} - -Examples: - -{% include [example_yql](query_metrics_example_yql.md) %} - diff --git a/ydb/docs/en/core/troubleshooting/_includes/system_views/query_metrics_example_yql.md b/ydb/docs/en/core/troubleshooting/_includes/system_views/query_metrics_example_yql.md deleted file mode 100644 index af2330e85f4..00000000000 --- a/ydb/docs/en/core/troubleshooting/_includes/system_views/query_metrics_example_yql.md +++ /dev/null @@ -1,27 +0,0 @@ -Top 10 queries for the last 6 hours by the total number of rows updated per minute: - -> ```sql -> SELECT -> SumUpdateRows, -> Count, -> QueryText, -> IntervalEnd -> FROM `.sys/query_metrics_one_minute` -> ORDER BY SumUpdateRows DESC LIMIT 10 -> ``` - -Recent queries that read the most bytes per minute: - -> ```sql -> SELECT -> IntervalEnd, -> SumReadBytes, -> MinReadBytes, -> SumReadBytes / Count as AvgReadBytes, -> MaxReadBytes, -> QueryText -> FROM `.sys/query_metrics_one_minute` -> WHERE SumReadBytes > 0 -> ORDER BY IntervalEnd DESC, SumReadBytes DESC -> LIMIT 100 -> ``` diff --git a/ydb/docs/en/core/troubleshooting/_includes/system_views/query_metrics_header.md b/ydb/docs/en/core/troubleshooting/_includes/system_views/query_metrics_header.md deleted file mode 100644 index 58b0fac2248..00000000000 --- a/ydb/docs/en/core/troubleshooting/_includes/system_views/query_metrics_header.md +++ /dev/null @@ -1,44 +0,0 @@ -## Query details {#query-metrics} - -The following system view stores detailed information about queries: - -* `query_metrics_one_minute`: Data is split into one-minute intervals, contains up to 256 queries for the last 6 hours. - -Each table row contains information about a set of queries with identical text that were made during one minute. The table fields provide the minimum, maximum, and total values for each query metric tracked. Within the interval, queries are sorted in descending order of the total CPU time used. - -Restrictions: - -* Query text limit is 4 KB. -* Statistics may be incomplete if the database is under heavy load. - -Table structure: - -| Field | Description | ----|--- -| `IntervalEnd` | The end of a one-minute interval.<br>Type: `Timestamp`.<br>Key: `0`. | -| `Rank` | Query rank within an interval (by the SumCPUTime field).<br>Type: `Uint32`.<br>Key: `1`. | -| `QueryText` | Query text.<br>Type: `Utf8`. | -| `Count` | Number of query runs.<br>Type: `Uint64`. | -| `SumDuration` | Total duration of queries.<br>Type: `Interval`. | -| `Count` | Number of query runs.<br>Type: `Uint64`. | -| `SumDuration` | Total duration of queries.<br>Type: `Interval`. | -| `MinDuration` | Minimum query duration.<br>Type: `Interval`. | -| `MaxDuration` | Maximum query duration.<br>Type: `Interval`. | -| `SumCPUTime` | Total CPU time used.<br>Type: `Uint64`. | -| `MinCPUTime` | Minimum CPU time used.<br>Type: `Uint64`. | -| `MaxCPUTime` | Maximum CPU time used.<br>Type: `Uint64`. | -| `SumReadRows` | Total number of rows read.<br>Type: `Uint64`. | -| `MinReadRows` | Minimum number of rows read.<br>Type: `Uint64`. | -| `MaxReadRows` | Maximum number of rows read.<br>Type: `Uint64`. | -| `SumReadBytes` | Total number of bytes read.<br>Type: `Uint64`. | -| `MinReadBytes` | Minimum number of bytes read.<br>Type: `Uint64`. | -| `MaxReadBytes` | Maximum number of bytes read.<br>Type: `Uint64`. | -| `SumUpdateRows` | Total number of rows written.<br>Type: `Uint64`. | -| `MinUpdateRows` | Minimum number of rows written.<br>Type: `Uint64`. | -| `MaxUpdateRows` | Maximum number of rows written.<br>Type: `Uint64`. | -| `SumUpdateBytes` | Total number of bytes written.<br>Type: `Uint64`. | -| `MinUpdateBytes` | Minimum number of bytes written.<br>Type: `Uint64`. | -| `MaxUpdateBytes` | Maximum number of bytes written.<br>Type: `Uint64`. | -| `SumDeleteRows` | Total number of rows deleted.<br>Type: `Uint64`. | -| `MinDeleteRows` | Minimum number of rows deleted.<br>Type: `Uint64`. | -| `MaxDeleteRows` | Maximum number of rows deleted.<br>Type: `Uint64`. | diff --git a/ydb/docs/en/core/troubleshooting/_includes/system_views/top-overload-partitions.md b/ydb/docs/en/core/troubleshooting/_includes/system_views/top-overload-partitions.md deleted file mode 100644 index d553386fe3b..00000000000 --- a/ydb/docs/en/core/troubleshooting/_includes/system_views/top-overload-partitions.md +++ /dev/null @@ -1,60 +0,0 @@ -## History of overloaded partitions {#top-overload-partitions} - -The following system views (tables) store the history of points in time when the load on individual DB table partitions was high: - -* `top_partitions_one_minute`: The data is split into one-minute intervals, contains the history for the last 6 hours. -* `top_partitions_one_hour`: The data is split into one-hour intervals, contains the history for the last 2 weeks. - -These tables contain partitions with peak loads of more than 70% (`CPUCores` > 0.7). Partitions within a single interval are ranked by peak load value. - -Both tables have the same set of fields: - -| Field | Description | ---- | --- -| `IntervalEnd` | The end of a one-minute or one-hour interval.<br>Type: `Timestamp`.<br>Key: `0`. | -| `Rank` | Partition rank within an interval (by CPUCores).<br>Type: `Uint32`.<br>Key: `1`. | -| `TabletId` | ID of the tablet serving the partition.<br>Type: `Uint64`. | -| `Path` | Full path to the table.<br>Type: `Utf8`. | -| `PeakTime` | Peak time within an interval.<br>Type: `Timestamp`. | -| `CPUCores` | Peak load per partition (CPU share).<br>Type: `Double`. | -| `NodeId` | ID of the node where the partition was located during the peak load.<br>Type: `Uint32`. | -| `DataSize` | Approximate partition size, in bytes, during the peak load.<br>Type: `Uint64`. | -| `RowCount` | Approximate row count during the peak load.<br>Type: `Uint64`. | -| `IndexSize` | Partition index size per tablet during the peak load.<br>Type: `Uint64`. | -| `InFlightTxCount` | The number of in-flight transactions during the peak load.<br>Type: `Uint32`. | - -Examples: - -The following query returns partitions with CPU usage of more than 70% in the specified interval, with tablet IDs and sizes as of the time when the percentage was exceeded. The query is made to the `.sys/top_partitions_one_minute` table with data over the last six hours split into one-minute intervals: - -> ```yql -> SELECT -> IntervalEnd, -> CPUCores, -> Path, -> TabletId, -> DataSize -> FROM `.sys/top_partitions_one_minute` -> WHERE CPUCores > 0.7 -> AND IntervalEnd BETWEEN Timestamp("YYYY-MM-DDThh:mm:ss.uuuuuuZ") AND Timestamp("YYYY-MM-DDThh:mm:ss.uuuuuuZ") -> ORDER BY IntervalEnd desc, CPUCores desc -> ``` - -* `"YYYY-MM-DDTHH:MM:SS.UUUUUUZ"`: Time in the UTC 0 zone (`YYYY` stands for year, `MM`, for month, `DD`, for date, `hh`, for hours, `mm`, for minutes, `ss`, for seconds, and `uuuuuu`, for microseconds). For example, `"2023-01-26T13:00:00.000000Z"`. - -The following query returns partitions with CPU usage of over 90% in the specified interval, with tablet IDs and sizes as of the time when the percentage was exceeded. The query is made to the `.sys/top_partitions_one_hour` table with data over the last two weeks split into one-hour intervals: - -> ```yql -> SELECT -> IntervalEnd, -> CPUCores, -> Path, -> TabletId, -> DataSize -> FROM `.sys/top_partitions_one_hour` -> WHERE CPUCores > 0.9 -> AND IntervalEnd BETWEEN Timestamp("YYYY-MM-DDThh:mm:ss.uuuuuuZ") AND Timestamp("YYYY-MM-DDThh:mm:ss.uuuuuuZ") -> ORDER BY IntervalEnd desc, CPUCores desc -> ``` - -* `"YYYY-MM-DDTHH:MM:SS.UUUUUUZ"`: Time in the UTC 0 zone (`YYYY` stands for year, `MM`, for month, `DD`, for date, `hh`, for hours, `mm`, for minutes, `ss`, for seconds, and `uuuuuu`, for microseconds). For example, `"2023-01-26T13:00:00.000000Z"`. diff --git a/ydb/docs/en/core/troubleshooting/_includes/system_views/tops.md b/ydb/docs/en/core/troubleshooting/_includes/system_views/tops.md deleted file mode 100644 index acb4488ba7d..00000000000 --- a/ydb/docs/en/core/troubleshooting/_includes/system_views/tops.md +++ /dev/null @@ -1,6 +0,0 @@ -{% include [header.md](tops_header.md) %} - -Examples: - -{% include [example_yql.md](tops_example_yql.md) %} - diff --git a/ydb/docs/en/core/troubleshooting/_includes/system_views/tops_example_yql.md b/ydb/docs/en/core/troubleshooting/_includes/system_views/tops_example_yql.md deleted file mode 100644 index 91134b6ab9a..00000000000 --- a/ydb/docs/en/core/troubleshooting/_includes/system_views/tops_example_yql.md +++ /dev/null @@ -1,30 +0,0 @@ -Top queries by execution time for the last minute when queries were made: - -> ```sql -> PRAGMA AnsiInForEmptyOrNullableItemsCollections; -> $last = ( -> SELECT -> MAX(IntervalEnd) -> FROM `.sys/top_queries_by_duration_one_minute` -> ); -> SELECT -> IntervalEnd, -> Rank, -> QueryText, -> Duration -> FROM `.sys/top_queries_by_duration_one_minute` -> WHERE IntervalEnd IN $last -> ``` - -Queries that read the most bytes, broken down by minute: - -> ```sql -> SELECT -> IntervalEnd, -> QueryText, -> ReadBytes, -> ReadRows, -> Partitions -> FROM `.sys/top_queries_by_read_bytes_one_minute` -> WHERE Rank = 1 -> ``` diff --git a/ydb/docs/en/core/troubleshooting/_includes/system_views/tops_header.md b/ydb/docs/en/core/troubleshooting/_includes/system_views/tops_header.md deleted file mode 100644 index 5bc627f7d64..00000000000 --- a/ydb/docs/en/core/troubleshooting/_includes/system_views/tops_header.md +++ /dev/null @@ -1,49 +0,0 @@ -## Top queries {#top-queries} - -The following system views store data for analyzing the flow of user queries: - -* `top_queries_by_duration_one_minute`: Data is split into one-minute intervals, contains Top 5 queries with the maximum total execution time for the last 6 hours. -* `top_queries_by_duration_one_hour`: Data is split into one-hour intervals, contains Top 5 queries with the maximum total execution time for the last 2 weeks. -* `top_queries_by_read_bytes_one_minute`: Data is split into one-minute intervals, contains Top 5 queries with the maximum number of bytes read from the table for the last 6 hours. -* `top_queries_by_read_bytes_one_hour`: Data is split into one-hour intervals, contains Top 5 queries with the maximum number of bytes read from the table for the last 2 weeks. -* `top_queries_by_cpu_time_one_minute`: Data is split into one-minute intervals, contains Top 5 queries with the maximum CPU time used for the last 6 hours. -* ` top_queries_by_cpu_time_one_hour`: Data is split into one-hour intervals, contains Top 5 queries with the maximum CPU time used for the last 2 weeks. - -Different runs of a query with the same text are deduplicated. The top list contains information about a specific run with the maximum value of the corresponding query metric within a single interval. - -Fields that provide information about the used CPU time (...`CPUTime`) are expressed in microseconds. - -Query text limit is 4 KB. - -All tables have the same set of fields: - -| Field | Description | ---- | --- -| `IntervalEnd` | The end of a one-minute or one-hour interval.<br>Type: `Timestamp`.<br>Key: `0`. | -| `Rank` | Rank of a top query.<br>Type: `Uint32`.<br>Key: `1`. | -| `QueryText` | Query text.<br>Type: `Utf8`. | -| `Duration` | Total query execution time.<br>Type: `Interval`. | -| `EndTime` | Query execution end time. <br>Type: `Timestamp`. | -| `Type` | Query type (data, scan, or script).<br>Type: `String`. | -| `ReadRows` | Number of rows read.<br>Type: `Uint64`. | -| `ReadBytes` | Number of bytes read.<br>Type: `Uint64`. | -| `UpdateRows` | Number of rows written.<br>Type: `Uint64`. | -| `UpdateBytes` | Number of bytes written.<br>Type: `Uint64`. | -| `DeleteRows` | Number of rows deleted.<br>Type: `Uint64`. | -| `DeleteBytes` | Number of bytes deleted.<br>Type: `Uint64`. | -| `Partitions` | Number of table partitions used during query execution.<br>Type: `Uint64`. | -| `UserSID` | User Security ID.<br>Type: `String`. | -| `ParametersSize` | Size of query parameters in bytes.<br>Type: `Uint64`. | -| `CompileDuration` | Duration of query compilation.<br>Type: `Interval`. | -| `FromQueryCache` | Shows whether the cache of prepared queries was used.<br>Type: `Bool`. | -| `CPUTime` | Total CPU time used to execute the query (microseconds).<br>Type: `Uint64`. | -| `ShardCount` | Number of shards used during query execution.<br>Type: `Uint64`. | -| `SumShardCPUTime` | Total CPU time used in shards.<br>Type: `Uint64`. | -| `MinShardCPUTime` | Minimum CPU time used in shards.<br>Type: `Uint64`. | -| `MaxShardCPUTime` | Maximum CPU time used in shards.<br>Type: `Uint64`. | -| `ComputeNodesCount` | Number of compute nodes used during query execution.<br>Type: `Uint64`. | -| `SumComputeCPUTime` | Total CPU time used in compute nodes.<br>Type: `Uint64`. | -| `MinComputeCPUTime` | Minimum CPU time used in compute nodes.<br>Type: `Uint64`. | -| `MaxComputeCPUTime` | Maximum CPU time used in compute nodes.<br>Type: `Uint64`. | -| `CompileCPUTime` | CPU time used to compile a query.<br>Type: `Uint64`. | -| `ProcessCPUTime` | CPU time used for overall query handling.<br>Type: `Uint64`. | diff --git a/ydb/docs/en/core/troubleshooting/index.md b/ydb/docs/en/core/troubleshooting/index.md deleted file mode 100644 index 38f4912563e..00000000000 --- a/ydb/docs/en/core/troubleshooting/index.md +++ /dev/null @@ -1,7 +0,0 @@ -# Diagnostics - -This section contains articles about YDB database diagnostics tools. - -- [System views](system_views_db.md) -- [Metrics](monitoring.md) -- [Grafana dashboards](../administration/grafana-dashboards.md) diff --git a/ydb/docs/en/core/troubleshooting/monitoring.md b/ydb/docs/en/core/troubleshooting/monitoring.md deleted file mode 100644 index 598b0fed128..00000000000 --- a/ydb/docs/en/core/troubleshooting/monitoring.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -editable: false ---- -# Metric reference - -{% include notitle [ydb_monitoring_sensors.md](_includes/monitoring_sensors.md) %} - diff --git a/ydb/docs/en/core/troubleshooting/system_views.md b/ydb/docs/en/core/troubleshooting/system_views.md deleted file mode 100644 index a07410916b3..00000000000 --- a/ydb/docs/en/core/troubleshooting/system_views.md +++ /dev/null @@ -1,7 +0,0 @@ -# System views - -You can find information about system views in the following articles: - -- [Database system tables](system_views_db.md) -- [Cluster system tables](system_views_cluster.md) - diff --git a/ydb/docs/en/core/troubleshooting/system_views_cluster.md b/ydb/docs/en/core/troubleshooting/system_views_cluster.md deleted file mode 100644 index 5f3045eda0b..00000000000 --- a/ydb/docs/en/core/troubleshooting/system_views_cluster.md +++ /dev/null @@ -1,7 +0,0 @@ -# Cluster system views - -{% include [intro.md](_includes/system_views/intro_cluster.md) %} - -{% include [distributed_storage.md](_includes/system_views/distributed_storage.md) %} - -{% include [notes.md](_includes/system_views/notes.md) %} diff --git a/ydb/docs/en/core/troubleshooting/system_views_db.md b/ydb/docs/en/core/troubleshooting/system_views_db.md deleted file mode 100644 index 0c8c26a7590..00000000000 --- a/ydb/docs/en/core/troubleshooting/system_views_db.md +++ /dev/null @@ -1,9 +0,0 @@ -{% include [intro.md](_includes/system_views/intro_db.md) %} - -{% include [partitions.md](_includes/system_views/partitions.md) %} - -{% include [tops.md](_includes/system_views/tops.md) %} - -{% include [query_metrics.md](_includes/system_views/query_metrics.md) %} - -{% include [top-overload-partitions.md](_includes/system_views/top-overload-partitions.md) %} diff --git a/ydb/docs/en/core/troubleshooting/toc_i.yaml b/ydb/docs/en/core/troubleshooting/toc_i.yaml deleted file mode 100644 index 2639d6c0a58..00000000000 --- a/ydb/docs/en/core/troubleshooting/toc_i.yaml +++ /dev/null @@ -1,8 +0,0 @@ -items: -- name: System views - href: system_views_db.md -- name: Monitoring - href: monitoring.md -- name: System views (deprecated) - href: system_views.md - hidden: true
\ No newline at end of file diff --git a/ydb/docs/en/core/troubleshooting/toc_p.yaml b/ydb/docs/en/core/troubleshooting/toc_p.yaml deleted file mode 100644 index 94ce1108684..00000000000 --- a/ydb/docs/en/core/troubleshooting/toc_p.yaml +++ /dev/null @@ -1,4 +0,0 @@ -items: -- name: Overview - href: index.md -- include: { mode: link, path: toc_i.yaml }
\ No newline at end of file diff --git a/ydb/docs/redirects.yaml b/ydb/docs/redirects.yaml index 402c4a3b9b4..8fa20d7081b 100644 --- a/ydb/docs/redirects.yaml +++ b/ydb/docs/redirects.yaml @@ -37,8 +37,80 @@ common: to: /devops/ansible/initial-deployment.md - from: /getting_started/yql.md to: /yql/reference/index.md + - from: /troubleshooting/system_views_cluster.md + to: /devops/manual/system-views.md + - from: /concepts/datatypes.md + to: /yql/reference/types/index.md -# Redirects for ydb-dstoo +# DBA-related redirects + - from: /db/index.md + to: /dba/index.md + - from: /maintenance/backup_and_recovery.md + to: /dba/backup-and-recovery.md + - from: /troubleshooting/system_views.md + to: /dba/system-views.md + - from: /troubleshooting/system_views_db.md + to: /dba/system-views.md + - from: /operations/manage-users-attr.md + to: /dba/custom-attributes.md + - from: /operations/query_plans_optimization.md + to: /dba/query-plans-optimization.md + - from: /best_practices/cdc.md + to: /dba/cdc.md + - from: /best_practices/pk-olap-scalability.md + to: /dba/primary-key/row-oriented.md + - from: /best_practices/pk-olap-scalability.md + to: /dba/primary-key/column-oriented.md + - from: /best_practices/schema_design.md + to: /dba/primary-key/index.md + - from: /best_practices/secondary_indexes.md + to: /dba/secondary-indexes.md + - from: /best_practices/table_sharding.md + to: /dba/primary-key/index.md + +# Dev-related redirects + - from: /best_practices/batch_upload.md + to: /dev/batch-upload.md + - from: /best_practices/paging.md + to: /dev/paging.md + - from: /best_practices/timeouts.md + to: /dev/timeouts.md + +# Contributors-related redirects + - from: /development/build-ya.md + to: /contributor/build-ya.md + - from: /development/datashard-locks-and-change-visibility.md + to: /contributor/datashard-locks-and-change-visibility.md + - from: /development/index.md + to: /contributor/index.md + - from: /development/load-actors-key-value.md + to: /contributor/load-actors-key-value.md + - from: /development/load-actors-kqp.md + to: /contributor/load-actors-kqp.md + - from: /development/load-actors-memory.md + to: /contributor/load-actors-memory.md + - from: /development/load-actors-overview.md + to: /contributor/load-actors-overview.md + - from: /development/load-actors-pdisk-log.md + to: /contributor/load-actors-pdisk-log.md + - from: /development/load-actors-pdisk-read.md + to: /contributor/load-actors-pdisk-read.md + - from: /development/load-actors-pdisk-write.md + to: /contributor/load-actors-pdisk-write.md + - from: /development/load-actors-stop.md + to: /contributor/load-actors-stop.md + - from: /development/load-actors-storage.md + to: /contributor/load-actors-storage.md + - from: /development/load-actors-vdisk.md + to: /contributor/load-actors-vdisk.md + - from: /development/localdb-uncommitted-txs.md + to: /contributor/localdb-uncommitted-txs.md + - from: /development/manage-releases.md + to: /contributor/manage-releases.md + - from: /development/suggest-change.md + to: /contributor/suggest-change.md + +# Redirects for ydb-dstool - from: /administration/ydb-dstool-device-list.md to: /reference/ydb-dstool/device-list.md - from: /administration/ydb-dstool-global-options.md @@ -48,7 +120,7 @@ common: - from: /administration/ydb-dstool-setup.md to: /reference/ydb-dstool/install.md -# Redirect from export_import to export-import +# Redirects from export_import to export-import - from: /reference/ydb-cli/export_import/s3_conn.md to: /reference/ydb-cli/export-import/auth-s3.md - from: /reference/ydb-cli/export_import/s3_export.md @@ -71,3 +143,5 @@ ru: to: /concepts/datamodel/table.md - from: /postgresql/index.md to: /postgresql/intro.md + - from: /db/terraform.md + to: /dba/terraform.md
\ No newline at end of file diff --git a/ydb/docs/ru/core/administration/upgrade.md b/ydb/docs/ru/core/administration/upgrade.md index 0e8d2abe882..e7625656c60 100644 --- a/ydb/docs/ru/core/administration/upgrade.md +++ b/ydb/docs/ru/core/administration/upgrade.md @@ -29,7 +29,7 @@ {% endnote %} -Список доступных версий можно получить на [странице загрузки](https://ydb.tech/ru/docs/downloads/). Релизная политика YDB описана более детально в статье [Управление релизами](../development/manage-releases.md) в разделе документации для разработчиков YDB. +Список доступных версий можно получить на [странице загрузки](https://ydb.tech/ru/docs/downloads/). Релизная политика YDB описана более детально в статье [Управление релизами](../contributor/manage-releases.md) в разделе документации для разработчиков YDB. ### Примеры совместимости версий diff --git a/ydb/docs/ru/core/best_practices/_includes/index.md b/ydb/docs/ru/core/best_practices/_includes/index.md deleted file mode 100644 index 316a4decc87..00000000000 --- a/ydb/docs/ru/core/best_practices/_includes/index.md +++ /dev/null @@ -1,10 +0,0 @@ -# Рекомендации - -В данном разделе собраны статьи, рассказывающие про назначение, особенности и лучшие практики применения инструментов YDB при разработке приложений. - -- [Выбор первичного ключа для максимальной производительности](../pk_scalability.md) -- [Вторичные индексы](../secondary_indexes.md) -- [Постраничный вывод](../paging.md) -- [Загрузка больших объемов данных](../batch_upload.md) -- [Использование таймаутов](../timeouts.md) -
\ No newline at end of file diff --git a/ydb/docs/ru/core/best_practices/_includes/schema_design.md b/ydb/docs/ru/core/best_practices/_includes/schema_design.md deleted file mode 100644 index f47c3a0ae40..00000000000 --- a/ydb/docs/ru/core/best_practices/_includes/schema_design.md +++ /dev/null @@ -1 +0,0 @@ -Данная статья удалена, материал перемещен в статью [Влияние первичного ключа на производительность](../pk_scalability.md).
\ No newline at end of file diff --git a/ydb/docs/ru/core/best_practices/_includes/table_sharding.md b/ydb/docs/ru/core/best_practices/_includes/table_sharding.md deleted file mode 100644 index a8f8442d8a6..00000000000 --- a/ydb/docs/ru/core/best_practices/_includes/table_sharding.md +++ /dev/null @@ -1 +0,0 @@ -Данная статья удалена, материал перемещен в пункт [Партиционирование таблиц](../../concepts/datamodel/table.md#partitioning) статьи об объектах схемы данных в разделе "Концепции".
\ No newline at end of file diff --git a/ydb/docs/ru/core/best_practices/batch_upload.md b/ydb/docs/ru/core/best_practices/batch_upload.md deleted file mode 100644 index e2e399826c4..00000000000 --- a/ydb/docs/ru/core/best_practices/batch_upload.md +++ /dev/null @@ -1,2 +0,0 @@ -{% include [batch_upload.md](_includes/batch_upload.md) %} - diff --git a/ydb/docs/ru/core/best_practices/index.md b/ydb/docs/ru/core/best_practices/index.md deleted file mode 100644 index eb2590567da..00000000000 --- a/ydb/docs/ru/core/best_practices/index.md +++ /dev/null @@ -1 +0,0 @@ -{% include [_includes/index.md](_includes/index.md) %}
\ No newline at end of file diff --git a/ydb/docs/ru/core/best_practices/paging.md b/ydb/docs/ru/core/best_practices/paging.md deleted file mode 100644 index 93d9375281d..00000000000 --- a/ydb/docs/ru/core/best_practices/paging.md +++ /dev/null @@ -1,3 +0,0 @@ - -{% include [paging.md](_includes/paging.md) %} - diff --git a/ydb/docs/ru/core/best_practices/pk_scalability.md b/ydb/docs/ru/core/best_practices/pk_scalability.md deleted file mode 100644 index 4b13db54fc4..00000000000 --- a/ydb/docs/ru/core/best_practices/pk_scalability.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: "Инструкция по выбору первичного ключа для максимальной производительности в {{ ydb-short-name }}" -description: "В статье описываем общие рекомендации по выбору первичного ключа в {{ ydb-short-name }}. Рассматриваем приемы равномерного распределения нагрузки по партициям таблицы." ---- - -{% include [pk_scalability.md](_includes/pk_scalability.md) %} diff --git a/ydb/docs/ru/core/best_practices/schema_design.md b/ydb/docs/ru/core/best_practices/schema_design.md deleted file mode 100644 index 18ab3a34ac4..00000000000 --- a/ydb/docs/ru/core/best_practices/schema_design.md +++ /dev/null @@ -1,2 +0,0 @@ - -{% include [timeouts.md](_includes/schema_design.md) %} diff --git a/ydb/docs/ru/core/best_practices/secondary_indexes.md b/ydb/docs/ru/core/best_practices/secondary_indexes.md deleted file mode 100644 index 7a4630af675..00000000000 --- a/ydb/docs/ru/core/best_practices/secondary_indexes.md +++ /dev/null @@ -1,3 +0,0 @@ - -{% include [secondary_indexes.md](_includes/secondary_indexes.md) %} - diff --git a/ydb/docs/ru/core/best_practices/table_sharding.md b/ydb/docs/ru/core/best_practices/table_sharding.md deleted file mode 100644 index 05274ea2892..00000000000 --- a/ydb/docs/ru/core/best_practices/table_sharding.md +++ /dev/null @@ -1,2 +0,0 @@ - -{% include [timeouts.md](_includes/table_sharding.md) %} diff --git a/ydb/docs/ru/core/best_practices/timeouts.md b/ydb/docs/ru/core/best_practices/timeouts.md deleted file mode 100644 index 48cb4d6cf33..00000000000 --- a/ydb/docs/ru/core/best_practices/timeouts.md +++ /dev/null @@ -1,2 +0,0 @@ - -{% include [timeouts.md](_includes/timeouts.md) %} diff --git a/ydb/docs/ru/core/best_practices/toc_i.yaml b/ydb/docs/ru/core/best_practices/toc_i.yaml deleted file mode 100644 index 57ce8346f50..00000000000 --- a/ydb/docs/ru/core/best_practices/toc_i.yaml +++ /dev/null @@ -1,24 +0,0 @@ -items: -- name: Обзор - href: index.md -- name: Выбор первичного ключа для максимальной производительности - href: pk_scalability.md -- name: Выбор первичного ключа для максимальной производительности аналитических таблиц - href: pk-olap-scalability.md -- name: Проектирование схемы - href: schema_design.md - hidden: true -- name: Партиционирование таблиц - href: table_sharding.md - hidden: true -- name: Вторичные индексы - href: secondary_indexes.md -- name: Change Data Capture - href: cdc.md - when: feature_changefeed -- name: Постраничный вывод - href: paging.md -- name: Загрузка больших объемов данных - href: batch_upload.md -- name: Использование таймаутов - href: timeouts.md diff --git a/ydb/docs/ru/core/best_practices/toc_p.yaml b/ydb/docs/ru/core/best_practices/toc_p.yaml deleted file mode 100644 index 5bfec4365de..00000000000 --- a/ydb/docs/ru/core/best_practices/toc_p.yaml +++ /dev/null @@ -1,2 +0,0 @@ -items: -- include: { mode: link, path: toc_i.yaml }
\ No newline at end of file diff --git a/ydb/docs/ru/core/changelog-cli.md b/ydb/docs/ru/core/changelog-cli.md index 2c983fc6413..d4ec61c0657 100644 --- a/ydb/docs/ru/core/changelog-cli.md +++ b/ydb/docs/ru/core/changelog-cli.md @@ -10,9 +10,9 @@ * Добавлены команды управления конфигурациями кластера [ydb admin config](reference/ydb-cli/configs.md) и [ydb admin volatile-config](reference/ydb-cli/configs.md). -* Добавлена поддержка загрузки PostgreSQL-совместимых типов командой [ydb import file csv|tsv|json](reference/ydb-cli/export_import/import-file.md). Только для строковых таблиц. +* Добавлена поддержка загрузки PostgreSQL-совместимых типов командой [ydb import file csv|tsv|json](reference/ydb-cli/export-import/import-file.md). Только для строковых таблиц. -* Добавлена поддержка загрузки директории из S3-совместимого хранилища в команде [ydb import s3](reference/ydb-cli/export_import/s3_import.md). Пока доступна только под Linux и Mac OS. +* Добавлена поддержка загрузки директории из S3-совместимого хранилища в команде [ydb import s3](reference/ydb-cli/export-import/import-s3.md). Пока доступна только под Linux и Mac OS. * Добавлена поддержка вывода результата выполнения команд [ydb table query execute](reference/ydb-cli/table-query-execute.md), [ydb yql](reference/ydb-cli/yql.md) и [ydb scripting yql](reference/ydb-cli/scripting-yql.md) в формате [Apache Parquet](https://parquet.apache.org/docs/). @@ -90,17 +90,17 @@ **Исправления ошибок:** -* Исправлена потеря строк при загрузке командой [ydb import file json](reference/ydb-cli/export_import/import-file.md). +* Исправлена потеря строк при загрузке командой [ydb import file json](reference/ydb-cli/export-import/import-file.md). * Исправлен неучет статистики во время прогрева команд [ydb workload topic run write|read|full](reference/ydb-cli/workload-topic.md#run-write). * Исправлен неполный вывод статистики в командах [ydb scripting yql](reference/ydb-cli/scripting-yql.md) и [ydb yql](reference/ydb-cli/yql.md). -* Исправлен неправильный вывод progress bar'a в командах [ydb tools dump](reference/ydb-cli/export_import/tools_dump.md) и [ydb tools restore](reference/ydb-cli/export_import/tools_restore.md). +* Исправлен неправильный вывод progress bar'a в командах [ydb tools dump](reference/ydb-cli/export-import/tools-dump.md) и [ydb tools restore](reference/ydb-cli/export-import/tools-restore.md). -* Исправлена ошибка загрузки больших файлов с заголовком в команде [ydb import file csv|tsv](reference/ydb-cli/export_import/import-file.md). +* Исправлена ошибка загрузки больших файлов с заголовком в команде [ydb import file csv|tsv](reference/ydb-cli/export-import/import-file.md). -* Исправлено зависание команды [ydb tools restore --import-data](reference/ydb-cli/export_import/tools_restore.md#optional). +* Исправлено зависание команды [ydb tools restore --import-data](reference/ydb-cli/export-import/tools-restore.md#optional). * Исправлена ошибка `Unknown value Rejected` при выполнении команды [ydb operation list buildindex](reference/ydb-cli/operation-list.md). @@ -110,17 +110,17 @@ **Функциональность:** -* Для команды `ydb import file` добавлен параметр [--timeout](reference/ydb-cli/export_import/import-file.md#optional), задающий время, в течение которого должна быть выполнена операция на сервере. -* Добавлен индикатор прогресса в командах [ydb scheme rmdir --recursive](reference/ydb-cli/commands/dir.md#rmdir) и [ydb import file](reference/ydb-cli/export_import/import-file.md). +* Для команды `ydb import file` добавлен параметр [--timeout](reference/ydb-cli/export-import/import-file.md#optional), задающий время, в течение которого должна быть выполнена операция на сервере. +* Добавлен индикатор прогресса в командах [ydb scheme rmdir --recursive](reference/ydb-cli/commands/dir.md#rmdir) и [ydb import file](reference/ydb-cli/export-import/import-file.md). * Добавлена команда [ydb workload kv run read-rows](reference/ydb-cli/workload-kv.md#read-rows-kv), которая нагружает базу запросами на чтение строк, используя новый экспериментальный API вызов ReadRows (реализован только в ветке [main](https://github.com/ydb-platform/ydb)), выполняющий более быстрое чтение по ключу, чем [select](reference/ydb-cli/workload-kv.md#select-kv). * В [ydb workload topic](reference/ydb-cli/workload-topic.md) добавлены новые параметры `--warmup-time`, `--percentile`, `--topic`, задающие время прогрева теста, процентиль в выводе статистики и имя топика соответственно. * Добавлена команда [ydb workload tpch](reference/ydb-cli/workload-tpch.md) для запуска нагрузочного теста TPC-H. -* Добавлен флаг `--ordered` в команде [ydb tools dump](reference/ydb-cli/export_import/tools_dump.md), сохраняющий порядок по первичному ключу в таблицах. +* Добавлен флаг `--ordered` в команде [ydb tools dump](reference/ydb-cli/export-import/tools-dump.md), сохраняющий порядок по первичному ключу в таблицах. **Производительность:** -* Увеличена скорость загрузки данных в команде `ydb import file` за счет добавления параллельной загрузки. Число потоков задается новым параметром [--threads](reference/ydb-cli/export_import/import-file.md#optional). -* Увеличена производительность команды [ydb import file json](reference/ydb-cli/export_import/import-file.md), за счет уменьшения числа копирований данных. +* Увеличена скорость загрузки данных в команде `ydb import file` за счет добавления параллельной загрузки. Число потоков задается новым параметром [--threads](reference/ydb-cli/export-import/import-file.md#optional). +* Увеличена производительность команды [ydb import file json](reference/ydb-cli/export-import/import-file.md), за счет уменьшения числа копирований данных. ## Версия 2.4.0 {#2-4-0} @@ -128,7 +128,7 @@ **Функциональность:** -* Добавлена возможность загрузки нескольких файлов командой [ydb import file](reference/ydb-cli/export_import/import-file.md). +* Добавлена возможность загрузки нескольких файлов командой [ydb import file](reference/ydb-cli/export-import/import-file.md). * Добавлена поддержка удаления колоночных таблиц для команды [ydb scheme rmdir --recursive](reference/ydb-cli/commands/dir.md#rmdir). * Повышена стабильность работы команды [ydb workload topic](reference/ydb-cli/workload-topic.md). @@ -139,13 +139,13 @@ **Функциональность:** * Добавлен интерактивный режим выполнения запросов. Для перехода в интерактивный режим выполните команду [ydb yql](reference/ydb-cli/yql.md) без аргументов. Режим экспериментальный, обратная совместимость пока не гарантируется. -* Добавлена команда [ydb index rename](reference/ydb-cli/commands/secondary_index.md#rename) для [атомарной замены](best_practices/secondary_indexes.md#atomic-index-replacement) или переименования вторичного индекса. +* Добавлена команда [ydb index rename](reference/ydb-cli/commands/secondary_index.md#rename) для [атомарной замены](dba/secondary-indexes.md#atomic-index-replacement) или переименования вторичного индекса. * Добавлена команда `ydb workload topic` для запуска нагрузки, которая читает и записывает сообщения в топики. * Для команды `ydb scheme rmdir` добавлен параметр [--recursive](reference/ydb-cli/commands/dir.md#rmdir-options), который позволяет рекурсивно удалить директорию вместе со всем содержимым. * Для команды [ydb scheme describe](reference/ydb-cli/commands/scheme-describe.md) добавлена поддержка типов `topic` и `coordination node`. * Для команды `ydb topic consumer` добавлен параметр [--commit](reference/ydb-cli/topic-read.md#osnovnye-opcionalnye-parametry) для подтверждения прочитанных сообщений. -* Для команды `ydb import file csv|tsv` добавлен параметр [--columns](reference/ydb-cli/export_import/import-file.md#optional), с помощью которого можно указать список колонок вместо заголовка в файле. -* Для команды `ydb import file csv|tsv` добавлен параметр [--newline-delimited](reference/ydb-cli/export_import/import-file.md#optional), который подтверждает отсутствие символа переноса строки в данных. Использование этого параметра ускоряет импорт за счет параллельного чтения из нескольких секций файла. +* Для команды `ydb import file csv|tsv` добавлен параметр [--columns](reference/ydb-cli/export-import/import-file.md#optional), с помощью которого можно указать список колонок вместо заголовка в файле. +* Для команды `ydb import file csv|tsv` добавлен параметр [--newline-delimited](reference/ydb-cli/export-import/import-file.md#optional), который подтверждает отсутствие символа переноса строки в данных. Использование этого параметра ускоряет импорт за счет параллельного чтения из нескольких секций файла. **Исправления ошибок:** @@ -172,8 +172,8 @@ **Улучшения:** * Добавлена поддержка параметра `--stats` команды [ydb scheme describe](reference/ydb-cli/commands/scheme-describe.md) для колоночных таблиц. -* Добавлена поддержка файлов в формате Parquet для импорта командой [ydb import](reference/ydb-cli/export_import/import-file.md). -* Поддержаны дополнительное логирование и ретраи для команды [ydb import](reference/ydb-cli/export_import/import-file.md). +* Добавлена поддержка файлов в формате Parquet для импорта командой [ydb import](reference/ydb-cli/export-import/import-file.md). +* Поддержаны дополнительное логирование и ретраи для команды [ydb import](reference/ydb-cli/export-import/import-file.md). ## Версия 2.1.0 {#2-1-0} @@ -186,7 +186,7 @@ * Для команды [ydb scheme ls](reference/ydb-cli/commands/scheme-ls.md) добавлен параметр `-1`, включающая режим вывода по одному объекту на строку. * URL сервиса IAM теперь можно сохранять в профиле. * Добавлена возможность использовать аутентификацию по логину и паролю без указания пароля. -* Добавлена поддержка профилей AWS в команде [ydb export s3](reference/ydb-cli/export_import/s3_conn.md#auth). +* Добавлена поддержка профилей AWS в команде [ydb export s3](reference/ydb-cli/export-import/auth-s3.md#auth). * Добавлена возможность создания профиля используя `stdin`. Например, можно передать вывод команды [YC CLI](https://cloud.yandex.ru/docs/cli/) `yc ydb database get information` на вход команде `ydb config profile create`. **Исправления ошибок:** @@ -230,5 +230,5 @@ **Функциональность:** -* Добавлена возможность сжатия данных при экспорте в S3-совместимое хранилище (см. параметр `--compression` команды [ydb export s3](reference/ydb-cli/export_import/s3_export.md)). +* Добавлена возможность сжатия данных при экспорте в S3-совместимое хранилище (см. параметр `--compression` команды [ydb export s3](reference/ydb-cli/export-import/export-s3.md)). * Добавлена возможность управления автоматической проверкой доступности новой версии {{ ydb-short-name }} CLI (см. параметры `--disable-checks` и `--enable-checks` команды [ydb version](reference/ydb-cli/version.md)). diff --git a/ydb/docs/ru/core/changelog-server.md b/ydb/docs/ru/core/changelog-server.md index d5c49b89581..3d276a60eec 100644 --- a/ydb/docs/ru/core/changelog-server.md +++ b/ydb/docs/ru/core/changelog-server.md @@ -154,7 +154,7 @@ **Функциональность:** * Добавлено [первоначальное сканирование таблицы](concepts/cdc.md#initial-scan) при создании потока изменений CDC. Теперь можно выгрузить все данные, которые существуют на момент создания потока. -* Добавлена возможность [атомарной замены индекса](best_practices/secondary_indexes.md#atomic-index-replacement). Теперь можно атомарно и прозрачно для приложения подменить один индекс другим заранее созданным индексом. Замена выполняется без простоя. +* Добавлена возможность [атомарной замены индекса](dba/secondary-indexes.md#atomic-index-replacement). Теперь можно атомарно и прозрачно для приложения подменить один индекс другим заранее созданным индексом. Замена выполняется без простоя. * Добавлен [аудитный лог](cluster/audit-log.md) — поток событий, который содержит информацию обо всех операциях над объектами {{ ydb-short-name }}. **Производительность:** diff --git a/ydb/docs/ru/core/cluster/index.md b/ydb/docs/ru/core/cluster/index.md index 7b8cf0c0f2c..82996d7958f 100644 --- a/ydb/docs/ru/core/cluster/index.md +++ b/ydb/docs/ru/core/cluster/index.md @@ -5,7 +5,6 @@ * [{#T}](../deploy/index.md). * [{#T}](../maintenance/embedded_monitoring/index.md). * [{#T}](../maintenance/manual/index.md). -* [{#T}](../troubleshooting/system_views_cluster.md). +* [{#T}](../devops/manual/system-views.md). * [{#T}](../administration/monitoring.md). * [{#T}](../administration/upgrade.md). -<!-- * [{#T}](../administration/rolling-restart.md). --> diff --git a/ydb/docs/ru/core/cluster/toc_i.yaml b/ydb/docs/ru/core/cluster/toc_i.yaml index ef074ff587d..15c356fcd3c 100644 --- a/ydb/docs/ru/core/cluster/toc_i.yaml +++ b/ydb/docs/ru/core/cluster/toc_i.yaml @@ -7,8 +7,6 @@ items: include: { mode: link, path: ../maintenance/manual/toc_p.yaml } - name: Встроенный UI include: { mode: link, path: ../maintenance/embedded_monitoring/toc_p.yaml } -- name: Системные таблицы кластера - href: ../troubleshooting/system_views_cluster.md - name: Аудитный лог href: audit-log.md - name: Краткая запись управления доступом @@ -20,7 +18,7 @@ items: - name: Дашборды Grafana href: ../administration/grafana-dashboards.md - name: Справочник метрик - href: ../troubleshooting/monitoring.md + href: ../reference/observability/metrics/index.md - name: Обновление href: ../administration/upgrade.md - name: Изменение конфигурации актор-системы diff --git a/ydb/docs/ru/core/concepts/_includes/scan_query.md b/ydb/docs/ru/core/concepts/_includes/scan_query.md index 2c245e2709c..b11069d1748 100644 --- a/ydb/docs/ru/core/concepts/_includes/scan_query.md +++ b/ydb/docs/ru/core/concepts/_includes/scan_query.md @@ -11,7 +11,7 @@ {% node info %} -Через интерфейс *Scan Queries* можно выполнять запросы к [системным таблицам](../../troubleshooting/system_views_db.md). +Через интерфейс *Scan Queries* можно выполнять запросы к [системным таблицам](../../dba/system-views.md). {% endnote %} diff --git a/ydb/docs/ru/core/concepts/_includes/secondary_indexes.md b/ydb/docs/ru/core/concepts/_includes/secondary_indexes.md index ae03b53bcab..692317a996c 100644 --- a/ydb/docs/ru/core/concepts/_includes/secondary_indexes.md +++ b/ydb/docs/ru/core/concepts/_includes/secondary_indexes.md @@ -57,4 +57,4 @@ ## Назначение и применение вторичных индексов {#best_practices} -О назначении и применении вторичных индексов при разработке приложений смотрите в [рекомендациях](../../best_practices/secondary_indexes.md). +О назначении и применении вторичных индексов при разработке приложений смотрите в [рекомендациях](../../dba/secondary-indexes.md). diff --git a/ydb/docs/ru/core/concepts/cdc.md b/ydb/docs/ru/core/concepts/cdc.md index 4d7d458b2fe..316d2d87c01 100644 --- a/ydb/docs/ru/core/concepts/cdc.md +++ b/ydb/docs/ru/core/concepts/cdc.md @@ -243,4 +243,4 @@ Change Data Capture (CDC) обеспечивает захват изменени ## Назначение и применение CDC {#best_practices} -Об использовании CDC при разработке приложений смотрите в [рекомендациях](../best_practices/cdc.md). +Об использовании CDC при разработке приложений смотрите в [рекомендациях](../dba/cdc.md). diff --git a/ydb/docs/ru/core/concepts/datamodel/_includes/table.md b/ydb/docs/ru/core/concepts/datamodel/_includes/table.md index 65d27d43c10..21d0812813e 100644 --- a/ydb/docs/ru/core/concepts/datamodel/_includes/table.md +++ b/ydb/docs/ru/core/concepts/datamodel/_includes/table.md @@ -22,7 +22,7 @@ YDB поддерживает создание строковых и колоно Создать строковую таблицу можно через web-интерфейс YDB, с помощью CLI или SDK. Вне зависимости от способа взаимодействия с YDB стоит помнить об общем правиле создания строковой таблицы: таблица должна иметь минимум одну ключевую колонку, при этом допускается создание таблицы, состоящий только из ключевых колонок. -По умолчанию при создании строковой таблицы все столбцы опциональны и могут иметь значения `NULL`, такое поведение можно изменить и задать условия `NOT NULL` для ключевых колонок, которые входят в состав первичного ключа. Первичные ключи уникальны, и строковые таблицы всегда упорядочена по ключу. Это означает, что точечное чтение по ключу, а также диапазонные запросы по ключу или префиксу ключа выполняются эффективно (фактически используя индекс). Допускается создание таблицы, состоящей только из ключевых столбцов. К выбору ключа нужно подходить аккуратно, поэтому рекомендуем ознакомиться со статьей: ["Выбор первичного ключа для максимальной производительности"](../../../best_practices/pk_scalability.md). +По умолчанию при создании строковой таблицы все столбцы опциональны и могут иметь значения `NULL`, такое поведение можно изменить и задать условия `NOT NULL` для ключевых колонок, которые входят в состав первичного ключа. Первичные ключи уникальны, и строковые таблицы всегда упорядочена по ключу. Это означает, что точечное чтение по ключу, а также диапазонные запросы по ключу или префиксу ключа выполняются эффективно (фактически используя индекс). Допускается создание таблицы, состоящей только из ключевых столбцов. К выбору ключа нужно подходить аккуратно, поэтому рекомендуем ознакомиться со статьей: ["Выбор первичного ключа для максимальной производительности"](../../../dba/primary-key/row-oriented.md). ### Партиционирование строковой таблицы {#partitioning_row_table} @@ -188,7 +188,7 @@ YDB поддерживает создание строковых и колоно * длина значения — 1–4096 байт; * максимальный общий размер атрибутов (сумма длин всех ключей и значений) — 10240 байт. -О том, как добавить, изменить, получить текущие значения или удалить атрибуты читайте в статье [{#T}](../../../operations/manage-users-attr.md). +О том, как добавить, изменить, получить текущие значения или удалить атрибуты читайте в статье [{#T}](../../../dba/custom-attributes.md). @@ -202,7 +202,7 @@ YDB поддерживает создание строковых и колоно Колоночные таблицы YDB хранят данные каждого столбца отдельно (независимо) от других столбцов. Такой принцип хранения данных оптимизирован для работы с Online Analytical Processing-нагрузками (OLAP), так как при выполнении запроса считываются только те столбцы, которые непосредственно участвуют в запросе. Еще один плюс такого подхода — высокая степень сжатия данных, так как в столбцах зачастую хранятся повторяющиеся или близкие данные. Минусом является то, что выполнение операций над строками становится более затратным. -На данный момент основной сценарий использования колоночных таблиц YDB — запись данных с возрастающим первичным ключом (например, время события), анализ этих данных и удаление устаревших данных по TTL. Оптимальным способом добавления данных в колоночные таблицы YDB является [пакетная запись](../../../best_practices/batch_upload.md), выполняемая блоками в единицы МБ. Вставка пакетов данных производится атомарно: данные будут записаны или во все партиции, или ни в одну. +На данный момент основной сценарий использования колоночных таблиц YDB — запись данных с возрастающим первичным ключом (например, время события), анализ этих данных и удаление устаревших данных по TTL. Оптимальным способом добавления данных в колоночные таблицы YDB является [пакетная запись](../../../dev/batch-upload.md), выполняемая блоками в единицы МБ. Вставка пакетов данных производится атомарно: данные будут записаны или во все партиции, или ни в одну. В большинстве случаев работа с колоночными таблицами YDB аналогична работе со строковыми, но есть и отличия: @@ -243,7 +243,7 @@ WITH (STORE = COLUMN); В отличие от партицирования данных в строковых таблицах YDB, партицирование данных для колоночных таблиц выполняется не по значениям ключей, а по hash-значениям от ключей, что позволяет равномерно распределить данные во все существующие партиции. Такое партицирование позволяет избежать хотспотов при вставке и ускоряет аналитические запросы, обрабатывающие (считывающие) большие объемы данных. -Выбор ключей партицирования существенно влияет на производительность колоночных таблиц. Подробнее смотрите: ["Выбор первичного ключа для максимальной производительности колоночных таблиц"](../../../best_practices/pk-olap-scalability.md). +Выбор ключей партицирования существенно влияет на производительность колоночных таблиц. Подробнее смотрите: ["Выбор первичного ключа для максимальной производительности колоночных таблиц"](../../../dba/primary-key/column-oriented.md). Для управления партицированием данных используется дополнительный параметр партиционирования: AUTO_PARTITIONING_MIN_PARTITIONS_COUNT. Остальные параметры партицирования для колоночных таблиц игнорируются. diff --git a/ydb/docs/ru/core/concepts/datatypes.md b/ydb/docs/ru/core/concepts/datatypes.md deleted file mode 100644 index e46c8263050..00000000000 --- a/ydb/docs/ru/core/concepts/datatypes.md +++ /dev/null @@ -1 +0,0 @@ -Данная страница удалена, информация по типам данных находится в статье [Типы данных YQL](../yql/reference/types/index.md).
\ No newline at end of file diff --git a/ydb/docs/ru/core/concepts/toc_i.yaml b/ydb/docs/ru/core/concepts/toc_i.yaml index f5fe7fbb84b..1dcebe64549 100644 --- a/ydb/docs/ru/core/concepts/toc_i.yaml +++ b/ydb/docs/ru/core/concepts/toc_i.yaml @@ -6,7 +6,6 @@ items: href: auth.md - name: Модель данных и схема include: { path: datamodel/toc_p.yaml, mode: link } -- { name: Типы данных, href: datatypes.md, hidden: true } # Deprecated - { name: Транзакции, href: transactions.md } - { name: Вторичные индексы, href: secondary_indexes.md } - { name: Change Data Capture (CDC), href: cdc.md, when: feature_changefeed } diff --git a/ydb/docs/ru/core/development/_includes/corp_cli_tags.md b/ydb/docs/ru/core/contributor/_includes/corp_cli_tags.md index e69de29bb2d..e69de29bb2d 100644 --- a/ydb/docs/ru/core/development/_includes/corp_cli_tags.md +++ b/ydb/docs/ru/core/contributor/_includes/corp_cli_tags.md diff --git a/ydb/docs/ru/core/development/_includes/corp_release_stable.md b/ydb/docs/ru/core/contributor/_includes/corp_release_stable.md index e69de29bb2d..e69de29bb2d 100644 --- a/ydb/docs/ru/core/development/_includes/corp_release_stable.md +++ b/ydb/docs/ru/core/contributor/_includes/corp_release_stable.md diff --git a/ydb/docs/ru/core/development/_includes/corp_release_testing.md b/ydb/docs/ru/core/contributor/_includes/corp_release_testing.md index e69de29bb2d..e69de29bb2d 100644 --- a/ydb/docs/ru/core/development/_includes/corp_release_testing.md +++ b/ydb/docs/ru/core/contributor/_includes/corp_release_testing.md diff --git a/ydb/docs/ru/core/development/_includes/index.md b/ydb/docs/ru/core/contributor/_includes/index.md index f931806f14e..f931806f14e 100644 --- a/ydb/docs/ru/core/development/_includes/index.md +++ b/ydb/docs/ru/core/contributor/_includes/index.md diff --git a/ydb/docs/ru/core/development/build-ya.md b/ydb/docs/ru/core/contributor/build-ya.md index ea2422860fd..ea2422860fd 100644 --- a/ydb/docs/ru/core/development/build-ya.md +++ b/ydb/docs/ru/core/contributor/build-ya.md diff --git a/ydb/docs/ru/core/development/datashard-locks-and-change-visibility.md b/ydb/docs/ru/core/contributor/datashard-locks-and-change-visibility.md index 020fdeb9afe..020fdeb9afe 100644 --- a/ydb/docs/ru/core/development/datashard-locks-and-change-visibility.md +++ b/ydb/docs/ru/core/contributor/datashard-locks-and-change-visibility.md diff --git a/ydb/docs/ru/core/development/index.md b/ydb/docs/ru/core/contributor/index.md index ec9e1499823..ec9e1499823 100644 --- a/ydb/docs/ru/core/development/index.md +++ b/ydb/docs/ru/core/contributor/index.md diff --git a/ydb/docs/ru/core/development/load-actors-key-value.md b/ydb/docs/ru/core/contributor/load-actors-key-value.md index 925c36340dd..925c36340dd 100644 --- a/ydb/docs/ru/core/development/load-actors-key-value.md +++ b/ydb/docs/ru/core/contributor/load-actors-key-value.md diff --git a/ydb/docs/ru/core/development/load-actors-kqp.md b/ydb/docs/ru/core/contributor/load-actors-kqp.md index e9e12b673b7..e9e12b673b7 100644 --- a/ydb/docs/ru/core/development/load-actors-kqp.md +++ b/ydb/docs/ru/core/contributor/load-actors-kqp.md diff --git a/ydb/docs/ru/core/development/load-actors-memory.md b/ydb/docs/ru/core/contributor/load-actors-memory.md index 81b1f0bd66d..81b1f0bd66d 100644 --- a/ydb/docs/ru/core/development/load-actors-memory.md +++ b/ydb/docs/ru/core/contributor/load-actors-memory.md diff --git a/ydb/docs/ru/core/development/load-actors-overview.md b/ydb/docs/ru/core/contributor/load-actors-overview.md index e562e1f7c9c..e562e1f7c9c 100644 --- a/ydb/docs/ru/core/development/load-actors-overview.md +++ b/ydb/docs/ru/core/contributor/load-actors-overview.md diff --git a/ydb/docs/ru/core/development/load-actors-pdisk-log.md b/ydb/docs/ru/core/contributor/load-actors-pdisk-log.md index a2af5e25471..a2af5e25471 100644 --- a/ydb/docs/ru/core/development/load-actors-pdisk-log.md +++ b/ydb/docs/ru/core/contributor/load-actors-pdisk-log.md diff --git a/ydb/docs/ru/core/development/load-actors-pdisk-read.md b/ydb/docs/ru/core/contributor/load-actors-pdisk-read.md index 849859dd461..849859dd461 100644 --- a/ydb/docs/ru/core/development/load-actors-pdisk-read.md +++ b/ydb/docs/ru/core/contributor/load-actors-pdisk-read.md diff --git a/ydb/docs/ru/core/development/load-actors-pdisk-write.md b/ydb/docs/ru/core/contributor/load-actors-pdisk-write.md index 34e9e659311..34e9e659311 100644 --- a/ydb/docs/ru/core/development/load-actors-pdisk-write.md +++ b/ydb/docs/ru/core/contributor/load-actors-pdisk-write.md diff --git a/ydb/docs/ru/core/development/load-actors-stop.md b/ydb/docs/ru/core/contributor/load-actors-stop.md index ad1e5bbf97a..ad1e5bbf97a 100644 --- a/ydb/docs/ru/core/development/load-actors-stop.md +++ b/ydb/docs/ru/core/contributor/load-actors-stop.md diff --git a/ydb/docs/ru/core/development/load-actors-storage.md b/ydb/docs/ru/core/contributor/load-actors-storage.md index 54a94d696bb..54a94d696bb 100644 --- a/ydb/docs/ru/core/development/load-actors-storage.md +++ b/ydb/docs/ru/core/contributor/load-actors-storage.md diff --git a/ydb/docs/ru/core/development/load-actors-vdisk.md b/ydb/docs/ru/core/contributor/load-actors-vdisk.md index f8c44118ed2..f8c44118ed2 100644 --- a/ydb/docs/ru/core/development/load-actors-vdisk.md +++ b/ydb/docs/ru/core/contributor/load-actors-vdisk.md diff --git a/ydb/docs/ru/core/development/localdb-uncommitted-txs.md b/ydb/docs/ru/core/contributor/localdb-uncommitted-txs.md index b3ea570e5b9..b3ea570e5b9 100644 --- a/ydb/docs/ru/core/development/localdb-uncommitted-txs.md +++ b/ydb/docs/ru/core/contributor/localdb-uncommitted-txs.md diff --git a/ydb/docs/ru/core/development/manage-releases.md b/ydb/docs/ru/core/contributor/manage-releases.md index b38bd7fe918..b38bd7fe918 100644 --- a/ydb/docs/ru/core/development/manage-releases.md +++ b/ydb/docs/ru/core/contributor/manage-releases.md diff --git a/ydb/docs/ru/core/development/suggest-change.md b/ydb/docs/ru/core/contributor/suggest-change.md index 387baa4b94c..387baa4b94c 100644 --- a/ydb/docs/ru/core/development/suggest-change.md +++ b/ydb/docs/ru/core/contributor/suggest-change.md diff --git a/ydb/docs/ru/core/development/toc_i.yaml b/ydb/docs/ru/core/contributor/toc_i.yaml index 94a4d1613bf..94a4d1613bf 100644 --- a/ydb/docs/ru/core/development/toc_i.yaml +++ b/ydb/docs/ru/core/contributor/toc_i.yaml diff --git a/ydb/docs/ru/core/db/toc_p.yaml b/ydb/docs/ru/core/contributor/toc_p.yaml index 3e62ad228bc..3e62ad228bc 100644 --- a/ydb/docs/ru/core/db/toc_p.yaml +++ b/ydb/docs/ru/core/contributor/toc_p.yaml diff --git a/ydb/docs/ru/core/db/_includes/cloud_remark.md b/ydb/docs/ru/core/db/_includes/cloud_remark.md deleted file mode 100644 index 173c7ae74ed..00000000000 --- a/ydb/docs/ru/core/db/_includes/cloud_remark.md +++ /dev/null @@ -1 +0,0 @@ -Облачные сервисы YDB предоставляют инструменты самообслуживания, позволяющие создавать, изменять и удалять базы данных. Документация по этим функциям доступна в составе документации таких облачных сервисов. diff --git a/ydb/docs/ru/core/db/index.md b/ydb/docs/ru/core/db/index.md deleted file mode 100644 index 1228210d398..00000000000 --- a/ydb/docs/ru/core/db/index.md +++ /dev/null @@ -1,7 +0,0 @@ -# Управление базами данных - -В данном разделе находятся статьи для разработчиков приложений, SRE и администраторов приложений, описывающие инструменты YDB по управлению базами данных и их обслуживанию. - -{% include [cloud_remark.md](_includes/cloud_remark.md) %} - -В необлачных конфигурациях YDB операции создания, модификации и удаления баз данных выполняются администраторами кластеров и описаны в разделе [Управление кластером](../cluster/index.md). diff --git a/ydb/docs/ru/core/db/toc_i.yaml b/ydb/docs/ru/core/db/toc_i.yaml deleted file mode 100644 index ba73e7c9b35..00000000000 --- a/ydb/docs/ru/core/db/toc_i.yaml +++ /dev/null @@ -1,10 +0,0 @@ -items: -- name: Резервное копирование и восстановление - href: ../maintenance/backup_and_recovery.md -- name: Диагностика - hidden: true - include: { mode: link, path: ../troubleshooting/toc_p.yaml } -- name: Системные таблицы БД - href: ../troubleshooting/system_views_db.md -- name: Terraform - href: terraform.md diff --git a/ydb/docs/ru/core/maintenance/_includes/backup_and_recovery/cli_overlay.md b/ydb/docs/ru/core/dba/_includes/backup_and_recovery/cli_overlay.md index e69de29bb2d..e69de29bb2d 100644 --- a/ydb/docs/ru/core/maintenance/_includes/backup_and_recovery/cli_overlay.md +++ b/ydb/docs/ru/core/dba/_includes/backup_and_recovery/cli_overlay.md diff --git a/ydb/docs/ru/core/maintenance/_includes/backup_and_recovery/options_overlay.md b/ydb/docs/ru/core/dba/_includes/backup_and_recovery/options_overlay.md index eeaa4f6ebe0..eeaa4f6ebe0 100644 --- a/ydb/docs/ru/core/maintenance/_includes/backup_and_recovery/options_overlay.md +++ b/ydb/docs/ru/core/dba/_includes/backup_and_recovery/options_overlay.md diff --git a/ydb/docs/ru/core/maintenance/_includes/backup_and_recovery/others_overlay.md b/ydb/docs/ru/core/dba/_includes/backup_and_recovery/others_overlay.md index e69de29bb2d..e69de29bb2d 100644 --- a/ydb/docs/ru/core/maintenance/_includes/backup_and_recovery/others_overlay.md +++ b/ydb/docs/ru/core/dba/_includes/backup_and_recovery/others_overlay.md diff --git a/ydb/docs/ru/core/maintenance/backup_and_recovery.md b/ydb/docs/ru/core/dba/backup-and-recovery.md index d7a5fbe86c0..d7a5fbe86c0 100644 --- a/ydb/docs/ru/core/maintenance/backup_and_recovery.md +++ b/ydb/docs/ru/core/dba/backup-and-recovery.md diff --git a/ydb/docs/ru/core/best_practices/cdc.md b/ydb/docs/ru/core/dba/cdc.md index 6364ccc7714..6364ccc7714 100644 --- a/ydb/docs/ru/core/best_practices/cdc.md +++ b/ydb/docs/ru/core/dba/cdc.md diff --git a/ydb/docs/ru/core/operations/manage-users-attr.md b/ydb/docs/ru/core/dba/custom-attributes.md index 7f00df335ba..7f00df335ba 100644 --- a/ydb/docs/ru/core/operations/manage-users-attr.md +++ b/ydb/docs/ru/core/dba/custom-attributes.md diff --git a/ydb/docs/ru/core/dba/index.md b/ydb/docs/ru/core/dba/index.md new file mode 100644 index 00000000000..41bb2752d62 --- /dev/null +++ b/ydb/docs/ru/core/dba/index.md @@ -0,0 +1,10 @@ +# {{ ydb-short-name }} для администраторов баз данных (DBA) + +Этот раздел документации {{ ydb-short-name }} содержит всё, что вам нужно знать для управления содержимым баз данных {{ ydb-short-name}}: [таблицами](../concepts/datamodel/table.md), [топиками](../concepts/topic.md) и других сущностями. + +Создание самих баз данных и управление ими выходит за рамки данного раздела, поскольку в кластерах {{ ydb-short-name }} эти операции либо [выполняются DevOps-инженерами] (../devops/index.md), либо автоматизированы извне, если вы используете управляемый сервис. + +- [Резервное копирование и восстановление](backup-and-recovery.md) +- [Системные таблицы базы данных](system-views.md) +- [Управление {{ ydb-short-name }} с помощью Terraform](terraform.md) +- [Пользовательские атрибуты таблиц](custom-attributes.md)
\ No newline at end of file diff --git a/ydb/docs/ru/core/best_practices/pk-olap-scalability.md b/ydb/docs/ru/core/dba/primary-key/column-oriented.md index 181a9e777c1..181a9e777c1 100644 --- a/ydb/docs/ru/core/best_practices/pk-olap-scalability.md +++ b/ydb/docs/ru/core/dba/primary-key/column-oriented.md diff --git a/ydb/docs/ru/core/dba/primary-key/index.md b/ydb/docs/ru/core/dba/primary-key/index.md new file mode 100644 index 00000000000..f11c5c525d8 --- /dev/null +++ b/ydb/docs/ru/core/dba/primary-key/index.md @@ -0,0 +1,6 @@ +# Выбор первичного ключа + +Рекомендации по выбору правильного первичного ключа для таблицы зависят от ее типа: + +- [Строковые таблицы](row-oriented.md) +- [Колоночные таблицы](column-oriented.md)
\ No newline at end of file diff --git a/ydb/docs/ru/core/best_practices/_includes/pk_scalability.md b/ydb/docs/ru/core/dba/primary-key/row-oriented.md index ec47b8d8311..ec47b8d8311 100644 --- a/ydb/docs/ru/core/best_practices/_includes/pk_scalability.md +++ b/ydb/docs/ru/core/dba/primary-key/row-oriented.md diff --git a/ydb/docs/ru/core/dba/primary-key/toc_p.yaml b/ydb/docs/ru/core/dba/primary-key/toc_p.yaml new file mode 100644 index 00000000000..1c93af5f098 --- /dev/null +++ b/ydb/docs/ru/core/dba/primary-key/toc_p.yaml @@ -0,0 +1,7 @@ +items: +- name: Обзор + href: index.md +- name: Строковые + href: row-oriented.md +- name: Колоночные + href: column-oriented.md
\ No newline at end of file diff --git a/ydb/docs/ru/core/operations/query_plans_optimization.md b/ydb/docs/ru/core/dba/query-plans-optimization.md index 7bba702ea5a..60d668afc74 100644 --- a/ydb/docs/ru/core/operations/query_plans_optimization.md +++ b/ydb/docs/ru/core/dba/query-plans-optimization.md @@ -54,7 +54,7 @@ SELECT season_id, episode_id И в визуальном и в текстовом представлении видно, что в корне этого плана возвращение данных на клиент, в листьях работа с таблицами, а на промежуточных узлах — преобразования данных. Важно обратить внимание на узел, показывающий обращение к таблице `episodes`. В данном случае это `TableFullScan`, который означает выполнение полного сканирования таблицы. А полное сканирование таблицы потребляет времени и ресурсов пропорционально её размеру, из-за чего по возможности их стараются избегать в таблицах, которые имеют тенденцию расти с течением времени или просто большие. -Одним из типовых способов избежать полного сканирования таблицы является добавление [вторичного индекса](../best_practices/_includes/secondary_indexes.md). В данном случае имеет смысл добавить вторичный индекс для колонки `title`, для этого воспользуемся запросом: +Одним из типовых способов избежать полного сканирования таблицы является добавление [вторичного индекса](secondary-indexes.md). В данном случае имеет смысл добавить вторичный индекс для колонки `title`, для этого воспользуемся запросом: ``` sql ALTER TABLE episodes diff --git a/ydb/docs/ru/core/best_practices/_includes/secondary_indexes.md b/ydb/docs/ru/core/dba/secondary-indexes.md index 6c5c482d510..757b8816c04 100644 --- a/ydb/docs/ru/core/best_practices/_includes/secondary_indexes.md +++ b/ydb/docs/ru/core/dba/secondary-indexes.md @@ -8,13 +8,13 @@ В транзакционных системах использование индексов позволяет сократить или исключить деградацию производительности и повышение стоимости выполнения запросов при росте объема хранимых данных. -В данной статье описаны основные операции по работе со вторичными индексами и даны ссылки на подробные материалы по каждой операции. Информация о разных типах вторичных индексов и особенностях их устройства находится в статье [Вторичные индексы](../../concepts/secondary_indexes.md) раздела "Концепции". +В данной статье описаны основные операции по работе со вторичными индексами и даны ссылки на подробные материалы по каждой операции. Информация о разных типах вторичных индексов и особенностях их устройства находится в статье [Вторичные индексы](../concepts/secondary_indexes.md) раздела "Концепции". ## Создание вторичных индексов {#create} -Вторичный индекс является объектом схемы данных и может быть определен при создании таблицы [командой YQL `CREATE TABLE`](../../yql/reference/syntax/create_table.md), или добавлен к ней позднее [командой YQL `ALTER TABLE`](../../yql/reference/syntax/alter_table.md). +Вторичный индекс является объектом схемы данных и может быть определен при создании таблицы [командой YQL `CREATE TABLE`](../yql/reference/syntax/create_table.md), или добавлен к ней позднее [командой YQL `ALTER TABLE`](../yql/reference/syntax/alter_table.md). -Команда [создания индекса `table index add`](../../reference/ydb-cli/commands/secondary_index.md#add) поддерживается в YDB CLI. +Команда [создания индекса `table index add`](../reference/ydb-cli/commands/secondary_index.md#add) поддерживается в YDB CLI. Так как индекс содержит собственные данные, являющиеся производными от данных в таблице, то при создании индекса на существующей таблице с данными будет выполнена операция начального построения индекса, которая может занимать продолжительное время. Данная операция выполняется в фоновом режиме, не блокирует работу с таблицей, но до окончания построения новым индексом воспользоваться будет невозможно. @@ -33,7 +33,7 @@ ## Применение вторичных индексов при выборке данных {#use} -Для обращения к таблице по вторичному индексу его имя должно быть явно указано в секции `VIEW` после имени таблицы, как описано в статье про [команду `SELECT`](../../yql/reference/syntax/select#secondary_index) YQL. Например, для получения из таблицы Заказов (`orders`) выборки заказов клиента с заданным ID (`id_customer`) запрос будет выглядеть следующим образом: +Для обращения к таблице по вторичному индексу его имя должно быть явно указано в секции `VIEW` после имени таблицы, как описано в статье про [команду `SELECT`](../yql/reference/syntax/select#secondary_index) YQL. Например, для получения из таблицы Заказов (`orders`) выборки заказов клиента с заданным ID (`id_customer`) запрос будет выглядеть следующим образом: ```sql DECLARE $customer_id AS Uint64; @@ -46,7 +46,7 @@ WHERE o.id_customer = $customer_id Без указания секции `VIEW` для выполнения такого запроса будет полностью просканирована таблица `orders`. -В транзакционных приложениях подобные информационные запросы выполняются с использованием поcтраничного вывода данных, что исключает рост стоимости и времени исполнения при увеличении количества записей, подходящих под условия фильтрации. Описанный на примере первичного ключа подход к написанию [постраничных запросов](../paging.md) применим также и к колонкам, включенным во вторичный индекс. +В транзакционных приложениях подобные информационные запросы выполняются с использованием поcтраничного вывода данных, что исключает рост стоимости и времени исполнения при увеличении количества записей, подходящих под условия фильтрации. Описанный на примере первичного ключа подход к написанию [постраничных запросов](../dev/paging.md) применим также и к колонкам, включенным во вторичный индекс. ## Проверка стоимости запроса {#cost} @@ -56,7 +56,7 @@ WHERE o.id_customer = $customer_id ## Обновление данных с использованием вторичного индекса {#update} -Команды YQL изменения записей ([`UPDATE`](../../yql/reference/syntax/update.md), [`UPSERT`](../../yql/reference/syntax/upsert_into.md), [`REPLACE`](../../yql/reference/syntax/replace_into.md)) не позволяют указать на использование вторичного индекса для поиска данных, поэтому попытка выполнить `UPDATE ... WHERE indexed_field = $value` приведет к полному сканированию таблицы. Чтобы избежать этого, можно предварительно выполнить `SELECT` по индексу с получением значения первичного ключа, а затем выполнить `UPDATE` по первичному ключу. Также можно воспользоваться инструкцией `UPDATE ON`. +Команды YQL изменения записей ([`UPDATE`](../yql/reference/syntax/update.md), [`UPSERT`](../yql/reference/syntax/upsert_into.md), [`REPLACE`](../yql/reference/syntax/replace_into.md)) не позволяют указать на использование вторичного индекса для поиска данных, поэтому попытка выполнить `UPDATE ... WHERE indexed_field = $value` приведет к полному сканированию таблицы. Чтобы избежать этого, можно предварительно выполнить `SELECT` по индексу с получением значения первичного ключа, а затем выполнить `UPDATE` по первичному ключу. Также можно воспользоваться инструкцией `UPDATE ON`. Чтобы обновить данные в таблице `table1`, выполните запрос: @@ -84,14 +84,14 @@ WHERE views = 0; ## Атомарная замена вторичного индекса {#atomic-index-replacement} -Существующий вторичный индекс можно заменить атомарно. Это может быть полезно, например, для замены индекса на [покрывающий](../../concepts/secondary_indexes.md#covering). Для работающих приложений эта операция прозрачна — в момент замены индекса произойдет инвалидация скомпилированных запросов. +Существующий вторичный индекс можно заменить атомарно. Это может быть полезно, например, для замены индекса на [покрывающий](../concepts/secondary_indexes.md#covering). Для работающих приложений эта операция прозрачна — в момент замены индекса произойдет инвалидация скомпилированных запросов. -Атомарно заменить существующий индекс можно с помощью команды YDB CLI [{{ ydb-cli }} table index rename](../../reference/ydb-cli/commands/secondary_index.md#rename) с параметром `--replace`. +Атомарно заменить существующий индекс можно с помощью команды YDB CLI [{{ ydb-cli }} table index rename](../reference/ydb-cli/commands/secondary_index.md#rename) с параметром `--replace`. ## Производительность записи в таблицы со вторичными индексами {#write_performance} Для работы вторичных индексов необходимы дополнительные структуры данных. Поддержка этих структур приводит к повышению стоимости операций изменения данных в таблицах. -При синхронном обновлении индексов транзакция подтверждается только после записи всех необходимых данных, как в таблице, так и в синхронных индексах. Это приводит как к увеличению времени исполнения, так и к необходимости применения [распределенных транзакций](../../concepts/transactions#distributed-tx) даже при добавлении или изменении записей в единственной партиции. +При синхронном обновлении индексов транзакция подтверждается только после записи всех необходимых данных, как в таблице, так и в синхронных индексах. Это приводит как к увеличению времени исполнения, так и к необходимости применения [распределенных транзакций](../concepts/transactions#distributed-tx) даже при добавлении или изменении записей в единственной партиции. Асинхронно обновляемые индексы сохраняют возможность применения одношардовых транзакций, однако гарантируют только консистентность "в конечном счете", и все равно создают нагрузку на базу данных. diff --git a/ydb/docs/ru/core/dba/system-views.md b/ydb/docs/ru/core/dba/system-views.md new file mode 100644 index 00000000000..396bad1737e --- /dev/null +++ b/ydb/docs/ru/core/dba/system-views.md @@ -0,0 +1,303 @@ +# Системные таблицы базы данных + +Вы можете отправлять запросы в специальные служебные таблицы (system views), чтобы следить за состоянием базы данных. Эти таблицы доступны из корня дерева базы данных и используют системный префикс пути `.sys`. + +Индекс поля первичного ключа соответствующей таблицы содержится в описаниях доступных полей далее по тексту. + +Системные таблицы содержат: + +* [Детальные данные об отдельных партициях таблиц БД](#partitions). +* [Топы запросов по определенным характеристикам](#top-queries). +* [Подробная информация о запросах](#query-metrics). +* [История перегруженных партиций](#top-overload-partitions). + +{% note info %} + +Обращение к системным таблицам имеет скорее аналитический характер нагрузки. Частое обращение к ним в больших базах будет существенно расходовать системные ресурсы. Рекомендуемая нагрузка не более 1-2 RPS. + +{% endnote %} + +## Партиции {#partitions} + +Следующая системная таблица хранит детализированную информацию об отдельных [партициях](../concepts/datamodel/table.md#partitioning) всех таблиц базы данных: + +* `partition_stats` — cодержит информацию о моментальных метриках и кумулятивные счетчики операций. К первым относятся, например, данные о нагрузке на CPU или количестве выполняемых [транзакций](../concepts/transactions.md). Ко вторым — общее количество прочитанных строк. + +Предназначена для выявления различных неравномерностей в нагрузке на партицию или отображения размера данных в ней. + +Кумулятивные поля (`RowReads`, `RowUpdates` и т.д.) хранят накопленные значения с момента последнего старта таблетки, обслуживающей партицию. + +Структура таблицы: + +Поле | Описание +--- | --- +`OwnerId` | Идентификатор SchemeShard, обслуживающего таблицу.<br>Тип: `Uint64`.<br>Ключ: `0`. +`PathId` | Идентификатор пути в SchemeShard.<br>Тип: `Uint64`.<br>Ключ: `1`. +`PartIdx` | Порядковый номер партиции.<br>Тип: `Uint64`.<br>Ключ: `2`. +`DataSize` | Приблизительный размер партиции в байтах.<br>Тип: `Uint64`. +`RowCount` | Приблизительное количество строк.<br>Тип: `Uint64`. +`IndexSize` | Размер индекса партиции в таблетке.<br>Тип: `Uint64`. +`CPUCores` | Double Моментальное значение нагрузки на партицию (доля ядра) +`TabletId` | Идентификатор таблетки, обслуживающей партицию.<br>Тип: `Uint64`. +`Path` | Полный путь к таблице.<br>Тип: `Utf8`. +`NodeId` | Идентификатор ноды, на которой в данный момент обслуживается партиция.<br>Тип: `Uint32`. +`StartTime` | Последний момент запуска таблетки, обслуживающей партицию.<br>Тип: `Timestamp`. +`AccessTime` | Последний момент чтения из партиции.<br>Тип: `Timestamp`. +`UpdateTime` | Последний момент записи в партицию.<br>Тип: `Timestamp`. +`RowReads` | Количество точечных чтений с момента старта таблетки партиции.<br>Тип: `Uint64`. +`RowUpdates` | Количество записанных строк с момента старта.<br>Тип: `Uint64`. +`RowDeletes` | Количество удалённых строк с момента старта.<br>Тип: `Uint64`. +`RangeReads` | Количество чтений диапазонов строк с момента старта.<br>Тип: `Uint64`. +`RangeReadRows` | Количество строк, прочитанных в диапазонах с момента старта.<br>Тип: `Uint64`. +`InFlightTxCount` | Количество транзакций, находящихся в процессе исполнения.<br>Тип: `Uint64`. +`ImmediateTxCompleted` | Количество завершившихся одношардовых транзакций с момента старта.<br>Тип: `Uint64`. +`CoordinatedTxCompleted` | Количество завершившихся координируемых транзакций с момента старта.<br>Тип: `Uint64`. +`TxRejectedByOverload` | Количество транзакций, отменённых по причине слишком высокой нагрузки (с момента старта).<br>Тип: `Uint64`. +`TxRejectedByOutOfStorage` | Количество транзакций, отменённых из-за нехватки места (с момента старта).<br>Тип: `Uint64`. + +### Примеры запросов + +Топ-5 самых загруженных партиций среди всех таблиц базы данных: + +```sql +SELECT + Path, + PartIdx, + CPUCores +FROM `.sys/partition_stats` +ORDER BY CPUCores DESC +LIMIT 5 +``` + +Список таблиц базы с размерами и нагрузкой в моменте: + +```sql +SELECT + Path, + COUNT(*) as Partitions, + SUM(RowCount) as Rows, + SUM(DataSize) as Size, + SUM(CPUCores) as CPU +FROM `.sys/partition_stats` +GROUP BY Path +``` +## Топы запросов {#top-queries} + +Следующие системные таблицы хранят данные для анализа потока пользовательских запросов: + +* `top_queries_by_duration_one_minute` — данные разбиты на минутные интервалы, содержит топ-5 запросов с наибольшим полным временем исполнения за последние 6 часов; +* `top_queries_by_duration_one_hour` — данные разбиты на часовые интервалы, содержит топ-5 запросов с наибольшим полным временем исполнения за последние 2 недели; +* `top_queries_by_read_bytes_one_minute` — данные разбиты на минутные интервалы, содержит топ-5 запросов с наибольшим количеством прочитанных из таблицы байт за последние 6 часов; +* `top_queries_by_read_bytes_one_hour` — данные разбиты на часовые интервалы, содержит топ-5 запросов с наибольшим количеством прочитанных из таблицы байт за последние 2 недели; +* `top_queries_by_cpu_time_one_minute` — данные разбиты на минутные интервалы, содержит топ-5 запросов с наибольшим затраченным процессорным временем за последние 6 часов; +* ` top_queries_by_cpu_time_one_hour` — данные разбиты на часовые интервалы, содержит топ-5 запросов с наибольшим затраченным процессорным временем за последние 2 недели. + +Различные запуски запроса с одним и тем же текстом дедуплицируются. Топ содержит информацию о конкретном запуске с максимальным значением соответствующей характеристики запроса в пределах одного временного интервала. + +Поля, предоставляющие информацию о затраченном процессорном времени (...`CPUTime`), выражены в микросекундах. + +Текст запроса ограничен 4 килобайтами. + +Все таблицы содержат одинаковый набор полей: + +Поле | Описание +--- | --- +`IntervalEnd` | Момент закрытия минутного или часового интервала.<br>Тип: `Timestamp`.<br>Ключ: `0`. +`Rank` | Ранг запроса в топе.<br>Тип: `Uint32`.<br>Ключ: `1`. +`QueryText` | Текст запроса.<br>Тип: `Utf8`. +`Duration` | Полное время исполнения запроса.<br>Тип: `Interval`. +`EndTime` | Момент окончания исполнения запроса. <br>Тип: `Timestamp`. +`Type` | Тип запроса ("data", "scan", "script").<br>Тип: `String`. +`ReadRows` | Количество прочитанных строк.<br>Тип: `Uint64`. +`ReadBytes` | Количество прочитанных байт.<br>Тип: `Uint64`. +`UpdateRows` | Количество записанных строк.<br>Тип: `Uint64`. +`UpdateBytes` | Количество записанных байт.<br>Тип: `Uint64`. +`DeleteRows` | Количество удалённых строк.<br>Тип: `Uint64`. +`DeleteBytes` | Количество удалённых байт.<br>Тип: `Uint64`. +`Partitions` | Количество партиций таблиц, участвовавших в исполнении запроса.<br>Тип: `Uint64`. +`UserSID` | Security ID пользователя.<br>Тип: `String`. +`ParametersSize` | Размер параметров запроса в байтах.<br>Тип: `Uint64`. +`CompileDuration` | Длительность компиляции запроса.<br>Тип: `Interval`. +`FromQueryCache` | Использовался ли кэш подготовленных запросов.<br>Тип: `Bool`. +`CPUTime` | Общее процессорное время, использованное для исполнения запроса (микросекунды).<br>Тип: `Uint64`. +`ShardCount` | Количество шардов, участвующих в исполнении запроса.<br>Тип: `Uint64`. +`SumShardCPUTime` | Общее процессорное время, затраченное в шардах.<br>Тип: `Uint64`. +`MinShardCPUTime` | Минимальное процесорное время, затраченное в шардах.<br>Тип: `Uint64`. +`MaxShardCPUTime` | Максимальное процессорное время, затраченное в шардах.<br>Тип: `Uint64`. +`ComputeNodesCount` | Количество вычислительных нод, задействованных в исполнении запроса.<br>Тип: `Uint64`. +`SumComputeCPUTime` | Общее процессорное время, затраченное в вычислительных нодах.<br>Тип: `Uint64`. +`MinComputeCPUTime` | Минимальное процессорное время, затраченное в вычислительных нодах.<br>Тип: `Uint64`. +`MaxComputeCPUTime` | Максимальное процессорное время, затраченное в вычислительных нодах.<br>Тип: `Uint64`. +`CompileCPUTime` | Процессорное время, затраченное на компиляцию запроса.<br>Тип: `Uint64`. +`ProcessCPUTime` | Процессорное время, затраченное на общую обработку запроса.<br>Тип: `Uint64`. + + +### Примеры запросов + +Топ запросов по времени выполнения за последнюю минуту их отправки: + +```sql +PRAGMA AnsiInForEmptyOrNullableItemsCollections; +$last = ( + SELECT + MAX(IntervalEnd) + FROM `.sys/top_queries_by_duration_one_minute` +); +SELECT + IntervalEnd, + Rank, + QueryText, + Duration +FROM `.sys/top_queries_by_duration_one_minute` +WHERE IntervalEnd IN $last +``` + +Запросы, прочитавшие больше всего байт, в разбивке по минутам: + +```sql +SELECT + IntervalEnd, + QueryText, + ReadBytes, + ReadRows, + Partitions +FROM `.sys/top_queries_by_read_bytes_one_minute` +WHERE Rank = 1 +``` + +## Подробная информация о запросах {#query-metrics} + +Следующая системная таблица хранит подробную информацию о запросах: + +* `query_metrics_one_minute` — данные разбиты по минутным интервалам, содержит до 256 запросов за последние 6 часов. + +Каждая строка таблицы содержит информацию о множестве случившихся за интервал запросов с одинаковым текстом. Поля таблицы предоставляют минимальное, максимальное и суммарное значение по каждой отслеживаемой характеристике запроса. В пределах интервала запросы отсортированы по убыванию суммарного потраченного процессорного времени. + +Ограничения: + +* текст запроса ограничен 4 килобайтами; +* статистика может быть неполной, если база испытывает сильную нагрузку. + +Структура таблицы: + +Поле | Описание +---|--- +`IntervalEnd` | Момент закрытия минутного интервала.<br>Тип: `Timestamp`.<br>Ключ: `0`. +`Rank` | Ранг запроса в пределах интервала (по полю SumCPUTime).<br>Тип: `Uint32`.<br>Ключ: `1`. +`QueryText` | Текст запроса.<br>Тип: `Utf8`. +`Count` | Количество запусков запроса.<br>Тип: `Uint64`. +`SumDuration` | Общая длительность запросов.<br>Тип: `Interval`. +`Count` | Количество запусков запроса.<br>Тип: `Uint64`. +`SumDuration` | Общая длительность запросов.<br>Тип: `Interval`. +`MinDuration` | Минимальная длительность запроса.<br>Тип: `Interval`. +`MaxDuration` | Максимальная длительность запроса.<br>Тип: `Interval`. +`SumCPUTime` | Общее затраченное процессорное время.<br>Тип: `Uint64`. +`MinCPUTime` | Минимальное затраченное процессорное время.<br>Тип: `Uint64`. +`MaxCPUTime` | Максимальное затраченное процессорное время.<br>Тип: `Uint64`. +`SumReadRows` | Общее количество прочитанных строк.<br>Тип: `Uint64`. +`MinReadRows` | Минимальное количество прочитанных строк.<br>Тип: `Uint64`. +`MaxReadRows` | Максимальное количество прочитанных строк.<br>Тип: `Uint64`. +`SumReadBytes` | Общее количество прочитанных байт.<br>Тип: `Uint64`. +`MinReadBytes` | Минимальное количество прочитанных байт.<br>Тип: `Uint64`. +`MaxReadBytes` | Максимальное количество прочитанных байт.<br>Тип: `Uint64`. +`SumUpdateRows` | Общее количество записанных строк.<br>Тип: `Uint64`. +`MinUpdateRows` | Минимальное количество записанных строк.<br>Тип: `Uint64`. +`MaxUpdateRows` | Максимальное количество записанных строк.<br>Тип: `Uint64`. +`SumUpdateBytes` | Общее количество записанных байт.<br>Тип: `Uint64`. +`MinUpdateBytes` | Минимальное количество записанных байт.<br>Тип: `Uint64`. +`MaxUpdateBytes` | Максимальное количество записанных байт.<br>Тип: `Uint64`. +`SumDeleteRows` | Общее количество удалённых строк.<br>Тип: `Uint64`. +`MinDeleteRows` | Минимальное количество удалённых строк.<br>Тип: `Uint64`. +`MaxDeleteRows` | Максимальное количество удалённых строк.<br>Тип: `Uint64`. + +### Примеры запросов + +Топ-10 запросов за последние 6 часов по общему количеству записанных строк в минутном интервале: + +```sql +SELECT + SumUpdateRows, + Count, + QueryText, + IntervalEnd +FROM `.sys/query_metrics_one_minute` +ORDER BY SumUpdateRows DESC LIMIT 10 +``` + +Недавние запросы, прочитавшие больше всего байт за минуту: + +```sql +SELECT + IntervalEnd, + SumReadBytes, + MinReadBytes, + SumReadBytes / Count as AvgReadBytes, + MaxReadBytes, + QueryText +FROM `.sys/query_metrics_one_minute` +WHERE SumReadBytes > 0 +ORDER BY IntervalEnd DESC, SumReadBytes DESC +LIMIT 100 + +``` +## История перегруженных партиций {#top-overload-partitions} + +Следующие системные таблицы хранят историю моментов высокой нагрузки на отдельные партиции таблиц БД: + +* `top_partitions_one_minute` — данные разбиты на минутные интервалы, содержит историю за последние 6 часов; +* `top_partitions_one_hour` — данные разбиты на часовые интервалы, содержит историю за последние 2 недели. + +В таблицы попадают партиции с пиковой нагрузкой более 70 % (`CPUCores` > 0,7). В пределах одного интервала партиции ранжированы по пиковому значению нагрузки. + +Обе таблицы содержат одинаковый набор полей: + +Поле | Описание +--- | --- +`IntervalEnd` | Момент закрытия минутного или часового интервала.<br>Тип: `Timestamp`.<br>Ключ: `0`. +`Rank` | Ранг партиции в пределах интервала (по CPUCores).<br>Тип: `Uint32`.<br>Ключ: `1`. +`TabletId` | Идентификатор таблетки, обслуживающей партицию.<br>Тип: `Uint64`. +`Path` | Полный путь к таблице.<br>Тип: `Utf8`. +`PeakTime` | Момент пикового значения в пределах интервала.<br>Тип: `Timestamp`. +`CPUCores` | Пиковое значение нагрузки на партицию (доля ядра).<br>Тип: `Double`. +`NodeId` | Идентификатор ноды, на которой находилась партиция в момент пика.<br>Тип: `Uint32`. +`DataSize` | Приблизительный размер партиции в байтах в момент пика.<br>Тип: `Uint64`. +`RowCount` | Приблизительное количество строк в момент пика.<br>Тип: `Uint64`. +`IndexSize` | Размер индекса партиции в таблетке в момент пика.<br>Тип: `Uint64`. +`InFlightTxCount` | Количество транзакций, находящихся в процессе исполнения в момент пика.<br>Тип: `Uint32`. + +### Примеры запросов + +Следующий запрос выводит партиции с потреблением CPU более 70% в указанном интервале времени, с идентификаторами таблеток и их размерами на момент превышения. Запрос выполняется к таблице `.sys/top_partitions_one_minute`, которая содержит данные за последние 6 часов с разбиением по часовым интервалам: + +```yql +SELECT + IntervalEnd, + CPUCores, + Path, + TabletId, + DataSize +FROM `.sys/top_partitions_one_minute` +WHERE CPUCores > 0.7 +AND IntervalEnd BETWEEN Timestamp("YYYY-MM-DDThh:mm:ss.uuuuuuZ") AND Timestamp("YYYY-MM-DDThh:mm:ss.uuuuuuZ") +ORDER BY IntervalEnd desc, CPUCores desc +``` + +* `"YYYY-MM-DDTHH:MM:SS.UUUUUUZ"` — время в зоне UTC 0 (`YYYY` — год, `MM` — месяц, `DD` — число, `hh` — часы, `mm` — минуты, `ss` — секунды, `uuuuuu` — микросекунды). Например, `"2023-01-26T13:00:00.000000Z"`. + +Следующий запрос выводит партиции с потреблением CPU более 90% в указанном интервале времени, с идентификаторами таблеток и их размерами на момент превышения. Запрос выполняется к таблице `.sys/top_partitions_one_hour`, которая содержит данные за последние 2 недели с разбиением по минутным интервалам: + +```yql +SELECT + IntervalEnd, + CPUCores, + Path, + TabletId, + DataSize +FROM `.sys/top_partitions_one_hour` +WHERE CPUCores > 0.9 +AND IntervalEnd BETWEEN Timestamp("YYYY-MM-DDThh:mm:ss.uuuuuuZ") AND Timestamp("YYYY-MM-DDThh:mm:ss.uuuuuuZ") +ORDER BY IntervalEnd desc, CPUCores desc +``` + +* `"YYYY-MM-DDTHH:MM:SS.UUUUUUZ"` — время в зоне UTC 0 (`YYYY` — год, `MM` — месяц, `DD` — число, `hh` — часы, `mm` — минуты, `ss` — секунды, `uuuuuu` — микросекунды). Например, `"2023-01-26T13:00:00.000000Z"`. + diff --git a/ydb/docs/ru/core/db/terraform.md b/ydb/docs/ru/core/dba/terraform.md index 00e885b4f1b..feb81d641f2 100644 --- a/ydb/docs/ru/core/db/terraform.md +++ b/ydb/docs/ru/core/dba/terraform.md @@ -402,7 +402,7 @@ resource "ydb_table_changefeed" "ydb_table_changefeed" { #### consumer {#consumer} -Аргумент `consumer` описывает [читателя](../best_practices/cdc.md#read) потока изменений. +Аргумент `consumer` описывает [читателя](cdc.md#read) потока изменений. * `name` — (обязательный) имя читателя. * `supported_codecs` — (необязательный) поддерживаемые кодек данных. diff --git a/ydb/docs/ru/core/dba/toc_i.yaml b/ydb/docs/ru/core/dba/toc_i.yaml new file mode 100644 index 00000000000..8171a950af6 --- /dev/null +++ b/ydb/docs/ru/core/dba/toc_i.yaml @@ -0,0 +1,19 @@ +items: +- name: Резервное копирование и восстановление + href: backup-and-recovery.md +- name: Первичный ключ + include: + mode: link + path: primary-key/toc_p.yaml +- name: Вторичные индексы + href: secondary-indexes.md +- name: Оптимизация планов запросов + href: query-plans-optimization.md +- name: Системные таблицы + href: system-views.md +- name: Пользовательские атрибуты + href: custom-attributes.md +- name: Change Data Capture + href: cdc.md +- name: Terraform + href: terraform.md
\ No newline at end of file diff --git a/ydb/docs/ru/core/development/toc_p.yaml b/ydb/docs/ru/core/dba/toc_p.yaml index 3e62ad228bc..3e62ad228bc 100644 --- a/ydb/docs/ru/core/development/toc_p.yaml +++ b/ydb/docs/ru/core/dba/toc_p.yaml diff --git a/ydb/docs/ru/core/best_practices/_includes/batch_upload.md b/ydb/docs/ru/core/dev/batch-upload.md index b1c903c7300..b1c903c7300 100644 --- a/ydb/docs/ru/core/best_practices/_includes/batch_upload.md +++ b/ydb/docs/ru/core/dev/batch-upload.md diff --git a/ydb/docs/ru/core/dev/index.md b/ydb/docs/ru/core/dev/index.md new file mode 100644 index 00000000000..c7024fd656d --- /dev/null +++ b/ydb/docs/ru/core/dev/index.md @@ -0,0 +1,5 @@ +# {{ ydb-short-name }} для разработчиков приложений + +В этом разделе документации {{ ydb-short-name }} описано всё, что нужно знать для разработки приложений, взаимодействующих с {{ ydb-short-name }}. + +Если же вам интересная разработка ядра {{ ydb-short-name }} или сопутствующих проектов, обратитесь к [документации для контрибьюторов](../contributor/index.md).
\ No newline at end of file diff --git a/ydb/docs/ru/core/best_practices/_includes/paging.md b/ydb/docs/ru/core/dev/paging.md index 10576f8f23e..10576f8f23e 100644 --- a/ydb/docs/ru/core/best_practices/_includes/paging.md +++ b/ydb/docs/ru/core/dev/paging.md diff --git a/ydb/docs/ru/core/best_practices/_includes/timeouts.md b/ydb/docs/ru/core/dev/timeouts.md index feff8c55a1f..638a328cea6 100644 --- a/ydb/docs/ru/core/best_practices/_includes/timeouts.md +++ b/ydb/docs/ru/core/dev/timeouts.md @@ -1,7 +1,3 @@ ---- -title: Использование таймаутов в YDB -description: 'Значение operation_timeout определяет время, в течение которого результат запроса интересен пользователю. Если за данное время операция не выполнилась, сервер возвращает ошибку c кодом Timeout и попытается прекратить выполнение запроса, однако отмена запроса не гарантируется. Всегда рекомендуется устанавливать и таймаут на операцию, и транспортный таймаут. ' ---- # Использование таймаутов В разделе приведено описание доступных таймаутов и представлены примеры использования на различных языках программирования. @@ -98,4 +94,4 @@ description: 'Значение operation_timeout определяет время } ``` -{% endlist %} +{% endlist %}
\ No newline at end of file diff --git a/ydb/docs/ru/core/dev/toc_p.yaml b/ydb/docs/ru/core/dev/toc_p.yaml new file mode 100644 index 00000000000..6437e1f2326 --- /dev/null +++ b/ydb/docs/ru/core/dev/toc_p.yaml @@ -0,0 +1,9 @@ +items: +- name: Overview + href: index.md +- name: Пакетная загрузка + href: batch-upload.md +- name: Постраничный вывод + href: paging.md +- name: Таймауты + href: timeouts.md
\ No newline at end of file diff --git a/ydb/docs/ru/core/troubleshooting/_includes/system_views/distributed_storage.md b/ydb/docs/ru/core/devops/manual/system-views.md index 0e319abe8a9..7583852da94 100644 --- a/ydb/docs/ru/core/troubleshooting/_includes/system_views/distributed_storage.md +++ b/ydb/docs/ru/core/devops/manual/system-views.md @@ -1,3 +1,17 @@ +# Системные таблицы кластера + +Для возможности внутренней интроспекции состояния кластера пользователю предоставляется возможность осуществлять запросы в специальные служебные таблицы (system views). Эти таблицы доступны из корневой директории кластера и используют системный префикс пути `.sys`. + +Пользователи облачных баз данных обычно не имеют доступа к системным таблицам кластера, так как за его поддержку и своевременную диагностику отвечает команда облака. + +В описаниях доступных полей далее по тексту колонка **Ключ** содержит индекс поля первичного ключа соответствующей таблицы. + +{% note info %} + +Аналогичные системные таблицы существуют и для происходящего внутри конкретной базы данных, они описаны в [отдельной статье для DBA](../../dba/system-views.md). + +{% endnote %} + ## Distributed Storage Информация о работе распределённого хранилища содержится в нескольких взаимосвязанных таблицах, каждая из которых отвечает за описание своей сущности, а именно: @@ -98,4 +112,10 @@ | AvailableGroupsToCreate | Uint32 | | Число групп с указанными характеристиками, которое можно создать с учётом необходимости резерва | | AvailableSizeToCreate | Uint64 | | Число доступных байт, которое получится при создании всех групп из AvailableGroupsToCreate | -Здесь стоит заметить, что AvailableGroupsToCreate показывают максимальное количество групп, которое можно создать, если не создавать другие виды групп. Таким образом, при расширении одного пула хранения могут поменяться числа AvailableGroupsToCreate в нескольких строках статистики.
\ No newline at end of file +Здесь стоит заметить, что AvailableGroupsToCreate показывают максимальное количество групп, которое можно создать, если не создавать другие виды групп. Таким образом, при расширении одного пула хранения могут поменяться числа AvailableGroupsToCreate в нескольких строках статистики. + +{% note info %} + +Обращение к системным таблицам имеет скорее аналитический характер нагрузки. Частое обращение к ним в больших базах будет существенно расходовать системные ресурсы. Рекомендуемая нагрузка не более 1-2 RPS. + +{% endnote %} diff --git a/ydb/docs/ru/core/devops/manual/toc_p.yaml b/ydb/docs/ru/core/devops/manual/toc_p.yaml new file mode 100644 index 00000000000..df0e4d41e09 --- /dev/null +++ b/ydb/docs/ru/core/devops/manual/toc_p.yaml @@ -0,0 +1,6 @@ +items: +- include: + mode: link + path: ../../cluster/toc_p.yaml +- name: Системные таблицы + href: system-views.md diff --git a/ydb/docs/ru/core/devops/toc_p.yaml b/ydb/docs/ru/core/devops/toc_p.yaml index ac66f9ead86..c226875d797 100644 --- a/ydb/docs/ru/core/devops/toc_p.yaml +++ b/ydb/docs/ru/core/devops/toc_p.yaml @@ -12,4 +12,4 @@ items: - name: Вручную include: mode: link - path: ../cluster/toc_p.yaml
\ No newline at end of file + path: manual/toc_p.yaml
\ No newline at end of file diff --git a/ydb/docs/ru/core/faq/_includes/common.md b/ydb/docs/ru/core/faq/_includes/common.md index 1c8f7cb3180..f10bc05001c 100644 --- a/ydb/docs/ru/core/faq/_includes/common.md +++ b/ydb/docs/ru/core/faq/_includes/common.md @@ -29,7 +29,7 @@ description: "Что такое YDB? Для каких задач стоит и * Чем меньше партиций таблиц будет задействовано во время исполнения запроса, тем быстрее он будет исполнен. Чтобы достичь большей производительности стоит руководствоваться правилом: один запрос — одна партиция. * Необходимо избегать ситуаций, при которых какая-то малая часть БД нагружена существенно больше, чем остальные части БД. -Подробнее читайте в разделе [Проектирование схемы](../../best_practices/schema_design.md). +Подробнее читайте в разделе [{#T}](../../dba/primary-key/index.md). #### Как равномерно распределить нагрузку по партициям таблицы? {#balance-shard-load} @@ -40,7 +40,7 @@ description: "Что такое YDB? Для каких задач стоит и * использовать хеш от значений ключевых колонок в качестве первичного ключа. * Необходимо уменьшать количество партиций таблиц, задействованных в одном запросе. -Подробнее читайте в разделе [Проектирование схемы](../../best_practices/schema_design.md#balance-shard-load). +Подробнее читайте в разделе [{#T}](../../dba/primary-key/index.md). #### Можно ли использовать NULL в ключевой колонке? {#null} @@ -64,7 +64,7 @@ description: "Что такое YDB? Для каких задач стоит и Для организации постраничного вывода рекомендуется последовательно выбирать данные, отсортированные по первичному ключу, ограничивая количество строк ключевым словом `LIMIT`. Использование ключевого слова `OFFSET` для решения этой задачи крайне не желательно. -Подробнее читайте в разделе [Постраничный вывод](../../best_practices/paging.md). +Подробнее читайте в разделе [Постраничный вывод](../../dev/paging.md). #### Как удалять устаревшие данные? {#ttl} diff --git a/ydb/docs/ru/core/faq/_includes/yql.md b/ydb/docs/ru/core/faq/_includes/yql.md index 1efe5230796..d964a980164 100644 --- a/ydb/docs/ru/core/faq/_includes/yql.md +++ b/ydb/docs/ru/core/faq/_includes/yql.md @@ -35,7 +35,7 @@ WHERE Key LIKE "some_prefix%"; #### Почему в результате запроса выводится только 1000 строк? {#result-rows-limit} -1000 строк — ограничение на размер одного результата для YQL запроса. В случае если результат запроса был обрезан, он будет помечен флагом `Truncated`. Чтобы получить большее количество строк из таблицы, можно воспользоваться [постраничным выводом](../../best_practices/paging.md) или операцией `ReadTable`. +1000 строк — ограничение на размер одного результата для YQL запроса. В случае если результат запроса был обрезан, он будет помечен флагом `Truncated`. Чтобы получить большее количество строк из таблицы, можно воспользоваться [постраничным выводом](../../dev/paging.md) или операцией `ReadTable`. #### Как экранировать кавычки JSON-строк при добавлении их в таблицу? {#escaping-quotes} diff --git a/ydb/docs/ru/core/index.yaml b/ydb/docs/ru/core/index.yaml index 28e98c2f165..8920f93e11e 100644 --- a/ydb/docs/ru/core/index.yaml +++ b/ydb/docs/ru/core/index.yaml @@ -16,9 +16,18 @@ links: - title: Концепции description: Как устроена YDB, возможности и доступные режимы использования href: concepts/ - - title: Рекомендации - description: Набор рекомендаций по практическому использованию сервиса - href: best_practices/ + - title: For DevOps + description: How to run production YDB clusters + href: devops/ + - title: For DBA + description: How to run manage YDB databases + href: dba/ + - title: For Developers + description: How to develop applications working with YDB + href: dev/ + - title: For Contributors + description: How to contribute to YDB core and satellite projects + href: contributor/ - title: Справочник YQL description: Описание синтаксиса и встроенных функций YQL href: yql/reference/ @@ -28,9 +37,6 @@ links: - title: Работа с SDK description: Справочник по YDB Software Development Kits href: reference/ydb-sdk/ - - title: Управление базами данных - description: Конфигурация, обслуживание, мониторинг и диагностика баз данных YDB - href: db/ - - title: Управление кластером - description: Конфигурация, обслуживание, мониторинг и диагностика кластеров YDB - href: cluster/ + - title: Совместимость с PostgreSQL + description: Интеграция с экосистемой PostgreSQL + href: postgresql/intro/
\ No newline at end of file diff --git a/ydb/docs/ru/core/operations/crud.md b/ydb/docs/ru/core/operations/crud.md deleted file mode 100644 index e69de29bb2d..00000000000 --- a/ydb/docs/ru/core/operations/crud.md +++ /dev/null diff --git a/ydb/docs/ru/core/operations/toc_i.yaml b/ydb/docs/ru/core/operations/toc_i.yaml deleted file mode 100644 index 1d5ad668c08..00000000000 --- a/ydb/docs/ru/core/operations/toc_i.yaml +++ /dev/null @@ -1,8 +0,0 @@ -items: -- name: Чтение и запись данных - href: crud.md - hidden: true -- name: Пользовательские атрибуты таблицы - href: manage-users-attr.md -- name: Использование планов при оптимизации запросов - href: query_plans_optimization.md diff --git a/ydb/docs/ru/core/operations/toc_p.yaml b/ydb/docs/ru/core/operations/toc_p.yaml deleted file mode 100644 index 5bfec4365de..00000000000 --- a/ydb/docs/ru/core/operations/toc_p.yaml +++ /dev/null @@ -1,2 +0,0 @@ -items: -- include: { mode: link, path: toc_i.yaml }
\ No newline at end of file diff --git a/ydb/docs/ru/core/quickstart.md b/ydb/docs/ru/core/quickstart.md index 8c7c49ea753..906938359ac 100644 --- a/ydb/docs/ru/core/quickstart.md +++ b/ydb/docs/ru/core/quickstart.md @@ -142,7 +142,7 @@ CREATE TABLE example * Каждый тип оператора SQL вроде `CREATE TABLE` имеет подробное описание в [справке по YQL](yql/reference/index.md). * `example` - это идентификатор имени таблицы, а `key` и `value` - идентификаторы имен столбцов. Рекомендуется использовать простые имена для таких идентификаторов, но если вам нужно использовать имя с необычными символами, оберните его в обратные кавычки. * `UInt64` и `String` - это названия типов данных. `String` представляет собой двоичную строку, а `UInt64` - 64-разрядное беззнаковое целое число. Таким образом, наша таблица-пример хранит строковые значения, идентифицируемые беззнаковыми целочисленными ключами. Подробнее [о типах данных](yql/reference/types/index.md). -* `PRIMARY KEY` - одно из основных понятий SQL, которое оказывает огромное влияние на логику приложения и производительность. В соответствии со стандартом SQL, первичный ключ также подразумевает ограничение уникальности, поэтому таблица не может иметь несколько строк с одинаковыми первичными ключами. В этой примерной таблице довольно просто определить, какой столбец пользователь должен выбрать в качестве первичного ключа, и мы указываем его как `(key)` в круглых скобках после соответствующего ключевого слова. В реальных сценариях таблицы часто содержат десятки столбцов, и первичные ключи могут быть составными (состоять из нескольких столбцов в указанном порядке), поэтому выбор правильного первичного ключа становится больше похожим на искусство. Если вас интересует эта тема, есть [руководство по выбору первичного ключа для максимизации производительности](best_practices/pk_scalability.md). YDB таблицы обязаны иметь первичный ключ. +* `PRIMARY KEY` - одно из основных понятий SQL, которое оказывает огромное влияние на логику приложения и производительность. В соответствии со стандартом SQL, первичный ключ также подразумевает ограничение уникальности, поэтому таблица не может иметь несколько строк с одинаковыми первичными ключами. В этой примерной таблице довольно просто определить, какой столбец пользователь должен выбрать в качестве первичного ключа, и мы указываем его как `(key)` в круглых скобках после соответствующего ключевого слова. В реальных сценариях таблицы часто содержат десятки столбцов, и первичные ключи могут быть составными (состоять из нескольких столбцов в указанном порядке), поэтому выбор правильного первичного ключа становится больше похожим на искусство. Если вас интересует эта тема, есть [руководство по выбору первичного ключа для максимизации производительности](dba/primary-key/row-oriented.md). YDB таблицы обязаны иметь первичный ключ. ## Добавление тестовых данных diff --git a/ydb/docs/ru/core/troubleshooting/_includes/monitoring_sensors.md b/ydb/docs/ru/core/reference/observability/metrics/index.md index 9275e76de56..90de6e91b86 100644 --- a/ydb/docs/ru/core/troubleshooting/_includes/monitoring_sensors.md +++ b/ydb/docs/ru/core/reference/observability/metrics/index.md @@ -1,14 +1,13 @@ -<!-- This file is referenced as include from /ru/monitoring/metrics-ref/index.md --> -## Сервис {{ ydb-full-name }} {#ydb} +# Справка по метрикам -### Метрики использования ресурсов {#resources} +## Метрики использования ресурсов {#resources} Имя метрики<br/>Тип, единицы измерения | Описание<br/>Метки ----- | ----- -`resources.storage.used_bytes`<br/>`IGAUGE`, байты | Размер пользовательских и служебных данных, сохраненных в распределенном сетевом хранилище. К служебным данным относятся данные первичного и [вторичных индексов](../../concepts/secondary_indexes.md). +`resources.storage.used_bytes`<br/>`IGAUGE`, байты | Размер пользовательских и служебных данных, сохраненных в распределенном сетевом хранилище. К служебным данным относятся данные первичного и [вторичных индексов](../../../concepts/secondary_indexes.md). `resources.storage.limit_bytes`<br/>`IGAUGE`, байты | Ограничение на размер пользовательских и служебных данных, которые база данных может сохранить в распределенном сетевом хранилище. -### Метрики GRPC API общие {#grpc_api} +## Метрики GRPC API общие {#grpc_api} Имя метрики<br/>Тип, единицы измерения | Описание<br/>Метки ----- | ----- @@ -17,11 +16,11 @@ `api.grpc.request.inflight_count`<br/>`IGAUGE`, штуки | Количество запросов, которые одновременно обрабатываются базой данных в определенный период времени.<br/>Метки:<br/>- _api_service_ – название сервиса gRPC API, например `table`.<br/>- _method_ – название метода сервиса gRPC API, например `ExecuteDataQuery`. `api.grpc.request.inflight_bytes`<br/>`IGAUGE`, байты | Размер запросов, которые одновременно обрабатываются базой данных в определенный период времени.<br/>Метки:<br/>- _api_service_ – название сервиса gRPC API, например `table`.<br/>- _method_ – название метода сервиса gRPC API, например `ExecuteDataQuery`. `api.grpc.response.bytes`<br/>`RATE`, байты | Размер ответов, которые отправлены базой данный в определенный период времени.<br/>Метки:<br/>- _api_service_ – название сервиса gRPC API, например `table`.<br/>- _method_ – название метода сервиса gRPC API, например `ExecuteDataQuery`. -`api.grpc.response.count`<br/>`RATE`, штуки | Количество ответов, которые отправлены базой в определенный период времени.<br/>Метки:<br/>- _api_service_ – название сервиса gRPC API, например `table`.<br/>- _method_ – название метода сервиса gRPC API, например `ExecuteDataQuery`.<br/>- _status_ – статус выполнения запроса, подробнее статусы описаны в разделе [Обработка ошибок](../../reference/ydb-sdk/error_handling.md). +`api.grpc.response.count`<br/>`RATE`, штуки | Количество ответов, которые отправлены базой в определенный период времени.<br/>Метки:<br/>- _api_service_ – название сервиса gRPC API, например `table`.<br/>- _method_ – название метода сервиса gRPC API, например `ExecuteDataQuery`.<br/>- _status_ – статус выполнения запроса, подробнее статусы описаны в разделе [Обработка ошибок](../../../reference/ydb-sdk/error_handling.md). `api.grpc.response.dropped_count`<br/>`RATE`, штуки | Количество ответов, отправка которых была прекращена на на транспортном (gRPC) уровне из-за ошибки.<br/>Метки:<br/>- _api_service_ – название сервиса gRPC API, например `table`.<br/>- _method_ – название метода сервиса gRPC API, например `ExecuteDataQuery`. -`api.grpc.response.issues`<br/>`RATE`, штуки | Количество ошибок определенного типа, возникших при выполнении запросов в определенный период времени.<br/>Метки:<br/>- _issue_type_ – тип ошибки, единственное значение – `optimistic_locks_invalidation`, подробнее инвалидация блокировок описана в разделе [Транзакции и запросы к {{ ydb-short-name }}](../../concepts/transactions.md). +`api.grpc.response.issues`<br/>`RATE`, штуки | Количество ошибок определенного типа, возникших при выполнении запросов в определенный период времени.<br/>Метки:<br/>- _issue_type_ – тип ошибки, единственное значение – `optimistic_locks_invalidation`, подробнее инвалидация блокировок описана в разделе [Транзакции и запросы к {{ ydb-short-name }}](../../../concepts/transactions.md). -### Метрики GRPC API для топиков {#grpc_api_topics} +## Метрики GRPC API для топиков {#grpc_api_topics} Имя метрики<br/>Тип, единицы измерения | Описание<br/>Метки ----- | ----- @@ -41,7 +40,7 @@ `grpc.topic.stream_write.sessions_active_count`<br/>`GAUGE`, штуки | Количество открытых сессий записи.<br/>Метки:<br/>- _topic_ – название топика. `grpc.topic.stream_write.sessions_created`<br/>`RATE`, штуки | Количество созданных сессий записи.<br/>Метки:<br/>- _topic_ – название топика. -### Метрики HTTP API {#http_api} +## Метрики HTTP API {#http_api} Имя метрики<br/>Тип, единицы измерения | Описание<br/>Метки ----- | ----- @@ -56,7 +55,7 @@ `api.http.data_streams.put_records.successful_messages`<br/>`RATE`, штуки | Количество сообщений, отправленных методом `PutRecords`, которые были успешно записаны.<br/>Метки:<br/>- _topic_ – название топика. `api.http.data_streams.put_records.total_messages`<br/>`RATE`, штуки | Количество сообщений, отправленных методом `PutRecords`.<br/>Метки:<br/>- _topic_ – название топика. -### Метрики Kafka API {#kafka_api} +## Метрики Kafka API {#kafka_api} Имя метрики<br/>Тип, единицы измерения | Описание<br/>Метки ----- | ----- @@ -69,14 +68,14 @@ `api.kafka.produce.successful_messages`<br/>`RATE`, штуки | Количество сообщений в единицу времени, отправленных методом `PRODUCE`, которые были успешно записаны.<br/>Метки:<br/>- _topic_ – название топика. `api.kafka.produce.total_messages`<br/>`RATE`, штуки | Количество сообщений в единицу времени, отправленных методом `PRODUCE`<br/>Метки:<br/>- _topic_ – название топика. -### Метрики сессий {#sessions} +## Метрики сессий {#sessions} Имя метрики<br/>Тип, единицы измерения | Описание<br/>Метки ----- | ----- `table.session.active_count`<br/>`IGAUGE`, штуки | Количество сессий, открытых клиентами в данный момент времени. `table.session.closed_by_idle_count`<br/>`RATE`, штуки | Количество сессий, которые закрыты по инициативе сервера баз данных в определенный период времени из-за превышения времени, выделенного на существование неактивной сессии. -### Метрики обработки транзакций {#transactions} +## Метрики обработки транзакций {#transactions} Длительность выполнения транзакции можно анализировать с помощью гистограммного счетчика. Интервалы заданы в миллисекундах. График показывает количество транзакций, длительность которых попадает в определенный интервал времени. @@ -86,7 +85,7 @@ `table.transaction.server_duration_milliseconds`<br/>`HIST_RATE`, штуки | Количество транзакций определенной длительности выполнения на сервере. Длительность выполнения – это время выполнения запросов в транзакции на сервере. Не включет время ожидания на клиенте между отправкой отдельных запросов в одной транзакции.<br/>Метки:<br/> -_tx_kind_ – тип транзакции, возможные значения `read_only`, `read_write`, `write_only`, `pure`. `table.transaction.client_duration_milliseconds`<br/>`HIST_RATE`, штуки | Количество транзакций определенной длительности выполнения на клиенте. Длительность выполнения – это время ожидания на клиенте между отправкой отдельных запросов в одной транзакции. Не включает время выполнения запросов на сервере.<br/>Метки:<br/>- _tx_kind_ – тип транзакции, возможные значения `read_only`, `read_write`, `write_only`, `pure`. -### Метрики обработки запросов {#queries} +## Метрики обработки запросов {#queries} Имя метрики<br/>Тип, единицы измерения | Описание<br/>Метки ----- | ----- @@ -101,7 +100,7 @@ `table.query.compilation.cache_misses`<br/>`RATE`, штуки | Количество запросов в определенный период времени, для выполнения которых потребовалось компилировать запрос. `table.query.execution.latency_milliseconds`<br/>`HIST_RATE`, штуки | Гистограммный счетчик. Интервалы заданы в миллисекундах. Показывает количество запросов, время выполнения которых попадает в определенный интервал. -### Метрики партиций таблиц {#datashards} +## Метрики партиций таблиц {#datashards} Имя метрики<br/>Тип, единицы измерения | Описание<br/>Метки ----- | ----- @@ -119,7 +118,7 @@ `table.datashard.erase.rows`<br/>`RATE`, штуки | Количество строк, которые удалены в базе данных в определенный период времени. `table.datashard.erase.bytes`<br/>`RATE`, байты | Размер данных, которые удалены в базе в определенный период времени. -### Метрики использования ресурсов (только для режима Dedicated) {#ydb_dedicated_resources} +## Метрики использования ресурсов (только для режима Dedicated) {#ydb_dedicated_resources} Имя метрики<br/>Тип<br/>единицы измерения | Описание<br/>Метки ----- | ----- @@ -128,19 +127,19 @@ `resources.memory.used_bytes`<br/>`IGAUGE`, байты | Использованная нодами базы данных оперативная память. `resources.memory.limit_bytes`<br/>`IGAUGE`, байты | Доступная нодам базы данных оперативная память. -### Метрики обработки запросов (только для режима Dedicated) {#ydb_dedicated_queries} +## Метрики обработки запросов (только для режима Dedicated) {#ydb_dedicated_queries} Имя метрики<br/>Тип<br/>единицы измерения | Описание<br/>Метки ----- | ----- -`table.query.compilation.cache_evictions`<br/>`RATE`, штуки | Количество запросов, вытесненных из кэша [подготовленных запросов](../../reference/ydb-sdk/example/index.md#param-queries) в определенный период времени. -`table.query.compilation.cache_size_bytes`<br/>`IGAUGE`, байты | Размер кэша [подготовленных запросов](../../reference/ydb-sdk/example/index.md#param-queries). -`table.query.compilation.cached_query_count`<br/>`IGAUGE`, штуки | Размер кэша [подготовленных запросов](../../reference/ydb-sdk/example/index.md#param-queries). +`table.query.compilation.cache_evictions`<br/>`RATE`, штуки | Количество запросов, вытесненных из кэша [подготовленных запросов](../../../reference/ydb-sdk/example/index.md#param-queries) в определенный период времени. +`table.query.compilation.cache_size_bytes`<br/>`IGAUGE`, байты | Размер кэша [подготовленных запросов](../../../reference/ydb-sdk/example/index.md#param-queries). +`table.query.compilation.cached_query_count`<br/>`IGAUGE`, штуки | Размер кэша [подготовленных запросов](../../../reference/ydb-sdk/example/index.md#param-queries). -### Метрики топиков {#topics} +## Метрики топиков {#topics} Имя метрики<br/>Тип, единицы измерения | Описание<br/>Метки ----- | ----- -`topic.producers_count`<br/>`GAUGE`, штуки | Количество уникальных [источников](../concepts/topic#producer-id) топика.<br/>Метки:<br/>- _topic_ – название топика. +`topic.producers_count`<br/>`GAUGE`, штуки | Количество уникальных [источников](../../../concepts/topic#producer-id) топика.<br/>Метки:<br/>- _topic_ – название топика. `topic.storage_bytes`<br/>`GAUGE`, байты | Размер топика в байтах.<br/>Метки:<br/>- _topic_ – название топика. `topic.read.bytes`<br/>`RATE`, байты | Количество байт, прочитанных из топика.<br/>Метки:<br/>- _topic_ – название топика.<br/>- _consumer_ – имя читателя. `topic.read.messages`<br/>`RATE`, штуки | Количество сообщений, прочитанных из топика.<br/>Метки:<br/>- _topic_ – название топика.<br/>- _consumer_ – имя читателя. @@ -152,7 +151,7 @@ `topic.write.message_size_bytes`<br/>`HIST_RATE`, штуки | Гистограммный счетчик. Интервалы заданы в байтах. Показывает количество сообщений, размер которых соответствует границам интервала.<br/>Метки:<br/>- _topic_ – название топика. `topic.write.lag_milliseconds`<br/>`HIST_RATE`, штуки | Гистограммный счетчик. Интервалы заданы в миллисекундах. Показывает количество сообщений, у которых разница между временем записи и временем создания сообщения попадает в заданный интервал.<br/>Метки:<br/>- _topic_ – название топика. -### Агрегированные метрики партиций топика {#topics_partitions} +## Агрегированные метрики партиций топика {#topics_partitions} В следующей таблице приведены агрегированные метрики партиций для топика. Максимальные и минимальные значения считаются по всем партициям заданного топика. diff --git a/ydb/docs/ru/core/reference/observability/toc_p.yaml b/ydb/docs/ru/core/reference/observability/toc_p.yaml new file mode 100644 index 00000000000..b9a22a9f082 --- /dev/null +++ b/ydb/docs/ru/core/reference/observability/toc_p.yaml @@ -0,0 +1,3 @@ +items: +- name: Справка по метрикам + href: metrics/index.md diff --git a/ydb/docs/ru/core/reference/toc_p.yaml b/ydb/docs/ru/core/reference/toc_p.yaml index 8aae9052311..b1faf930907 100644 --- a/ydb/docs/ru/core/reference/toc_p.yaml +++ b/ydb/docs/ru/core/reference/toc_p.yaml @@ -26,4 +26,8 @@ items: - name: YDB DStool include: mode: link - path: ydb-dstool/toc_p.yaml
\ No newline at end of file + path: ydb-dstool/toc_p.yaml +- name: Observability + include: + mode: link + path: observability/toc_p.yaml
\ No newline at end of file diff --git a/ydb/docs/ru/core/reference/ydb-cli/_includes/commands.md b/ydb/docs/ru/core/reference/ydb-cli/_includes/commands.md index 07a00605411..e412e7fab15 100644 --- a/ydb/docs/ru/core/reference/ydb-cli/_includes/commands.md +++ b/ydb/docs/ru/core/reference/ydb-cli/_includes/commands.md @@ -64,12 +64,12 @@ table attribute drop | Удаление атрибута таблицы [table ttl set](../table-ttl-set.md) | Установка параметров TTL [table ttl reset](../table-ttl-reset.md) | Сброс параметров TTL [tools copy](../tools-copy.md) | Копирование таблиц -[tools dump](../export_import/tools_dump.md) | Выгрузка директории или таблицы в файловую систему +[tools dump](../export-import/tools-dump.md) | Выгрузка директории или таблицы в файловую систему {% if ydb-cli == "ydb" %} [tools pg-convert](../../../postgresql/pg-dump.md#pg-convert) | Конвертация дампа PostgreSQL, полученного утилитой pg_dump, в формат, понятный YDB {% endif %} [tools rename](../commands/tools/rename.md) | Переименование таблиц -[tools restore](../export_import/tools_restore.md) | Восстановление из файловой системы +[tools restore](../export-import/tools-restore.md) | Восстановление из файловой системы [topic create](../topic-create.md) | Создание топика [topic alter](../topic-alter.md) | Модификация параметров топика и перечня читателей [topic drop](../topic-drop.md) | Удаление топика diff --git a/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/secondary_index.md b/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/secondary_index.md index 5793ab8a1eb..72d454399fe 100644 --- a/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/secondary_index.md +++ b/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/secondary_index.md @@ -10,7 +10,7 @@ Также добавить или удалить вторичный индекс можно с помощью директив [ADD INDEX и DROP INDEX](../../../../yql/reference/syntax/alter_table.md#secondary-index) операции YQL ALTER TABLE. -О назначении и применении вторичных индексов при разработке приложений можно прочитать в статье [Вторичные индексы](../../../../best_practices/secondary_indexes.md) в разделе "Рекомендации". +О назначении и применении вторичных индексов при разработке приложений можно прочитать в статье [Вторичные индексы](../../../../dba/secondary-indexes.md). ## Создание вторичного индекса {#add} diff --git a/ydb/docs/ru/core/reference/ydb-cli/commands/workload/_includes/stock.md b/ydb/docs/ru/core/reference/ydb-cli/commands/workload/_includes/stock.md index d2e3e0495cb..fe88c807ba4 100644 --- a/ydb/docs/ru/core/reference/ydb-cli/commands/workload/_includes/stock.md +++ b/ydb/docs/ru/core/reference/ydb-cli/commands/workload/_includes/stock.md @@ -83,9 +83,9 @@ CREATE TABLE `orderLines`(id_order Uint64, product Utf8, quantity Int64, PRIMARY `--rate <значение>` | - | Суммарная частота запросов всех потоков, в транзакциях в секунду. Значение по умолчанию: 0 (не ограничена). `--quiet` | - | Выводит только итоговый результат теста. `--print-timestamp` | - | Печатать время вместе со статистикой каждого временного окна. -`--client-timeout` | - | [Транспортный таймаут в миллисекундах](../../../../../best_practices/timeouts.md). -`--operation-timeout` | - | [Таймаут на операцию в миллисекундах](../../../../../best_practices/timeouts.md). -`--cancel-after` | - | [Таймаут отмены операции в миллисекундах](../../../../../best_practices/timeouts.md). +`--client-timeout` | - | [Транспортный таймаут в миллисекундах](../../../../../dev/timeouts.md). +`--operation-timeout` | - | [Таймаут на операцию в миллисекундах](../../../../../dev/timeouts.md). +`--cancel-after` | - | [Таймаут отмены операции в миллисекундах](../../../../../dev/timeouts.md). `--window` | - | Длительность окна сбора статистики в секундах. Значение по умолчанию: 1. diff --git a/ydb/docs/ru/core/reference/ydb-cli/export_import/file_structure.md b/ydb/docs/ru/core/reference/ydb-cli/export_import/file_structure.md deleted file mode 100644 index a5c0143d94b..00000000000 --- a/ydb/docs/ru/core/reference/ydb-cli/export_import/file_structure.md +++ /dev/null @@ -1 +0,0 @@ -{% include [file-structure.md](../export-import/_includes/file-structure.md) %} diff --git a/ydb/docs/ru/core/reference/ydb-cli/export_import/import-file.md b/ydb/docs/ru/core/reference/ydb-cli/export_import/import-file.md deleted file mode 100644 index ebf02296144..00000000000 --- a/ydb/docs/ru/core/reference/ydb-cli/export_import/import-file.md +++ /dev/null @@ -1 +0,0 @@ -{% include [import-file.md](../export-import/_includes/import-file.md) %} diff --git a/ydb/docs/ru/core/reference/ydb-cli/export_import/index.md b/ydb/docs/ru/core/reference/ydb-cli/export_import/index.md deleted file mode 100644 index bac195e986f..00000000000 --- a/ydb/docs/ru/core/reference/ydb-cli/export_import/index.md +++ /dev/null @@ -1 +0,0 @@ -{% include [index.md](../export-import/_includes/index.md) %} diff --git a/ydb/docs/ru/core/reference/ydb-cli/export_import/s3_conn.md b/ydb/docs/ru/core/reference/ydb-cli/export_import/s3_conn.md deleted file mode 100644 index cada9d45ca3..00000000000 --- a/ydb/docs/ru/core/reference/ydb-cli/export_import/s3_conn.md +++ /dev/null @@ -1 +0,0 @@ -{% include [auth-s3.md](../export-import/_includes/auth-s3.md) %} diff --git a/ydb/docs/ru/core/reference/ydb-cli/export_import/s3_export.md b/ydb/docs/ru/core/reference/ydb-cli/export_import/s3_export.md deleted file mode 100644 index 43fd5f07846..00000000000 --- a/ydb/docs/ru/core/reference/ydb-cli/export_import/s3_export.md +++ /dev/null @@ -1 +0,0 @@ -{% include [export-s3.md](../export-import/_includes/export-s3.md) %} diff --git a/ydb/docs/ru/core/reference/ydb-cli/export_import/s3_import.md b/ydb/docs/ru/core/reference/ydb-cli/export_import/s3_import.md deleted file mode 100644 index 5e45757e1d7..00000000000 --- a/ydb/docs/ru/core/reference/ydb-cli/export_import/s3_import.md +++ /dev/null @@ -1 +0,0 @@ -{% include [import-s3.md](../export-import/_includes/import-s3.md) %} diff --git a/ydb/docs/ru/core/reference/ydb-cli/export_import/toc_i.yaml b/ydb/docs/ru/core/reference/ydb-cli/export_import/toc_i.yaml deleted file mode 100644 index 73b547b49fe..00000000000 --- a/ydb/docs/ru/core/reference/ydb-cli/export_import/toc_i.yaml +++ /dev/null @@ -1,15 +0,0 @@ -items: -- name: Файловая структура выгрузки - href: file_structure.md -- name: Выгрузка в файловую систему - href: tools_dump.md -- name: Загрузка из файловой системы - href: tools_restore.md -- name: Соединение и аутентификация с S3 - href: s3_conn.md -- name: Выгрузка в S3 - href: s3_export.md -- name: Загрузка из S3 - href: s3_import.md -- name: Импорт данных из файла в существующую таблицу - href: import-file.md diff --git a/ydb/docs/ru/core/reference/ydb-cli/export_import/toc_p.yaml b/ydb/docs/ru/core/reference/ydb-cli/export_import/toc_p.yaml deleted file mode 100644 index 3e62ad228bc..00000000000 --- a/ydb/docs/ru/core/reference/ydb-cli/export_import/toc_p.yaml +++ /dev/null @@ -1,4 +0,0 @@ -items: -- name: Обзор - href: index.md -- include: { mode: link, path: toc_i.yaml }
\ No newline at end of file diff --git a/ydb/docs/ru/core/reference/ydb-cli/export_import/tools_dump.md b/ydb/docs/ru/core/reference/ydb-cli/export_import/tools_dump.md deleted file mode 100644 index e31e5267c47..00000000000 --- a/ydb/docs/ru/core/reference/ydb-cli/export_import/tools_dump.md +++ /dev/null @@ -1 +0,0 @@ -{% include [tools-dump.md](../export-import/_includes/tools-dump.md) %} diff --git a/ydb/docs/ru/core/reference/ydb-cli/export_import/tools_restore.md b/ydb/docs/ru/core/reference/ydb-cli/export_import/tools_restore.md deleted file mode 100644 index 74057320716..00000000000 --- a/ydb/docs/ru/core/reference/ydb-cli/export_import/tools_restore.md +++ /dev/null @@ -1 +0,0 @@ -{% include [tools-restore.md](../export-import/_includes/tools-restore.md) %} diff --git a/ydb/docs/ru/core/reference/ydb-cli/toc_i.yaml b/ydb/docs/ru/core/reference/ydb-cli/toc_i.yaml index 2c98ecf951e..54f7a86fd23 100644 --- a/ydb/docs/ru/core/reference/ydb-cli/toc_i.yaml +++ b/ydb/docs/ru/core/reference/ydb-cli/toc_i.yaml @@ -44,10 +44,9 @@ items: - name: Скан запросы href: commands/scan-query.md - name: Выгрузка и загрузка данных - include: { mode: link, path: export-import/toc_p.yaml } - - name: Выгрузка и загрузка данных - include: { mode: link, path: export_import/toc_p.yaml } - hidden: true + include: + mode: link + path: export-import/toc_p.yaml - name: Работа с топиками items: - name: Команды для работы с топиком diff --git a/ydb/docs/ru/core/reference/ydb-cli/workload-kv.md b/ydb/docs/ru/core/reference/ydb-cli/workload-kv.md index 806243ce226..2c12b5d17a9 100644 --- a/ydb/docs/ru/core/reference/ydb-cli/workload-kv.md +++ b/ydb/docs/ru/core/reference/ydb-cli/workload-kv.md @@ -120,9 +120,9 @@ DROP TABLE `kv_test` `--rate <значение>` | - | Суммарная частота запросов всех потоков, в транзакциях в секунду Значение по умолчанию: 0 (не ограничена). `--quiet` | - | Выводит только итоговый результат теста. `--print-timestamp` | - | Печатать время вместе со статистикой каждого временного окна. -`--client-timeout` | - | [Транспортный таймаут в миллисекундах](../../best_practices/timeouts.md). -`--operation-timeout` | - | [Таймаут на операцию в миллисекундах](../../best_practices/timeouts.md). -`--cancel-after` | - | [Таймаут отмены операции в миллисекундах](../../best_practices/timeouts.md). +`--client-timeout` | - | [Транспортный таймаут в миллисекундах](../../dev/timeouts.md). +`--operation-timeout` | - | [Таймаут на операцию в миллисекундах](../../dev/timeouts.md). +`--cancel-after` | - | [Таймаут отмены операции в миллисекундах](../../dev/timeouts.md). `--window` | - | Длительность окна сбора статистики в секундах. Значение по умолчанию: 1. `--max-first-key` | - | Максимальное значение primary ключа таблицы. Значение по умолчанию: $2^{64} - 1$. `--cols` | - | Количество колонок в таблице. Значение по умолчанию: 2, считая Key. diff --git a/ydb/docs/ru/core/sre/ansible/_assets/terraform/AiC_scheme.png b/ydb/docs/ru/core/sre/ansible/_assets/terraform/AiC_scheme.png Binary files differdeleted file mode 100644 index e01304fa935..00000000000 --- a/ydb/docs/ru/core/sre/ansible/_assets/terraform/AiC_scheme.png +++ /dev/null diff --git a/ydb/docs/ru/core/sre/ansible/_includes/ansible-install-steps.md b/ydb/docs/ru/core/sre/ansible/_includes/ansible-install-steps.md deleted file mode 100644 index e6e4dd21769..00000000000 --- a/ydb/docs/ru/core/sre/ansible/_includes/ansible-install-steps.md +++ /dev/null @@ -1,85 +0,0 @@ -1. [Роль](https://github.com/ydb-platform/ydb-ansible/blob/main/roles/packages/tasks/main.yaml) `packages`. Задачи: - * `check dpkg audit` – проверка состояния dpkg с помощью команды `dpkg --audit` и сохранение результатов команды в переменной `dpkg_audit_result`. Задача завершится с ошибкой, если команда `dpkg_audit_result.rc` вернет значение отличное от 0 или 1. - * `run the equivalent of "apt-get clean" as a separate step` – очистка кеша apt, аналогично команде `apt-get clean`. - * `run the equivalent of "apt-get update" as a separate step` – обновление кеша apt, аналогично команде `apt-get update`. - * `fix unconfigured packages` – исправление неконфигурированных пакетов с помощью команды `dpkg --configure --pending`. - * `set vars_for_distribution_version variables` – установка переменных для конкретной версии дистрибутива. - * `setup apt repositories` – настройка репозиториев apt из заданного списка. - * `setup apt preferences` – настройка предпочтений apt (содержание переменных указано в `roles/packages/vars/distributions/<distributive name>/<version>/main.yaml`). - * `setup apt configs`– настройка конфигураций apt. - * `flush handlers` – принудительный запуск всех накопленных обработчиков (хендлеров). В данном случае запускается хендлер, который обновляет кеш apt. - * `install packages` – установка пакетов apt с учетом заданных параметров и времени валидности кеша. - -Ссылки на списки пакетов, которые будут установлены для Ubuntu 22.04 или Astra Linux 1.7: -* [Список](https://github.com/ydb-platform/ydb-ansible/blob/main/roles/packages/vars/distributions/Ubuntu/22.04/main.yaml) пакетов для Ubuntu 22.04; -* [Список](https://github.com/ydb-platform/ydb-ansible/blob/main/roles/packages/vars/distributions/Astra%20Linux/1.7_x86-64/main.yaml) пакетов для Astra Linux 1.7. - -2. [Роль](https://github.com/ydb-platform/ydb-ansible/blob/main/roles/system/tasks/main.yaml) `system`. Задачи: - * `configure clock` – блок задач настройки системных часов: - + `assert required variables are defined` – проверка переменной `system_timezone` на существование. Эта проверка гарантирует, что необходимая переменная доступна для следующей задачи в блоке. - + `set system timezone` – установка системного часового пояса. Часовой пояс задаётся значением переменной `system_timezone`, а аппаратные часы (`hwclock`) устанавливаются на UTC. После выполнения задачи отправляется уведомление для перезапуска службы `cron`. - + `flush handlers` – принудительное выполнение накопленных обработчиков директивой `meta`. Будет произведен рестарт следующих процессов: `timesyncd`, `journald`, `cron`, `cpufrequtils`, и выполнена команда `sysctl -p`. - * `configure systemd-timesyncd` – блок задач настройки `systemd-timesyncd`: - + `assert required variables are defined` - утверждает, что количество NTP серверов (`system_ntp_servers`) больше одного, если переменная `system_ntp_servers` определена. Если переменная `system_ntp_servers` не определена, выполнение блока задач `configure systemd-timesyncd` будет пропущено, включая проверку количества NTP серверов и настройку `systemd-timesyncd`. - + `create conf.d directory for timesyncd` - создаёт директорию `/etc/systemd/timesyncd.conf.d`, если переменная `system_ntp_servers` определена. - + `configure systemd-timesyncd` - создаёт конфигурационный файл `/etc/systemd/timesyncd.conf.d/ydb.conf` для службы `systemd-timesyncd` с основным и резервными NTP серверами. Задача будет выполнена, если переменная `system_ntp_servers` определена. После выполнения задачи отправляется уведомление для перезапуска службы `timesyncd`. - + `flush handlers` - вызываются накопленные обработчики. Выполняется обработчик `restart timesyncd`, который выполняет перезапуск сервиса `systemd-timesyncd.service`. - + `start timesyncd` - запуск и активация службы `systemd-timesyncd.service`. Далее служба будет стартовать автоматически при загрузке системы. - * `configure systemd-journald` – блок задач по настройке сервиса `systemd-journald`: - + `create conf.d directory for journald` - создание директории `/etc/systemd/journald.conf.d` для хранения конфигурационных файлов `systemd-journald`. - + `configure systemd-journald` - создание конфигурационного файла в `/etc/systemd/journald.conf.d/ydb.conf` для `systemd-journald`, в котором указывается секция `Journal` с опцией `ForwardToWall=no`. Параметр `ForwardToWall=no` в конфигурации `systemd-journald` означает, что журнал сообщений (логи) системы не будет перенаправляться как сообщения "wall" всем вошедшим в систему пользователям. После выполнения задачи отправляется уведомление для перезапуска службы `journald`. - + `flush handlers` - вызывает накопленные хендлеры. Будет выполнен хендлер `restart journald`, который перезапустит сервис `systemd-journald`. - + `start journald` - запуск и активация службы `systemd-journald.service`. Далее служба будет стартовать автоматически при загрузке системы. - * `configure kernel` – блок задач конфигурирования ядра: - + `configure /etc/modules-load.d dir` - создание директории `/etc/modules-load.d` с правами владельца и группы для пользователя root и разрешениями `0755`. - + `setup conntrack module` - копирование строки `nf_conntrack` в файл `/etc/modules-load.d/conntrack.conf` для загрузки модуля `nf_conntrack` при старте системы. - + `load conntrack module` - загрузка модуля `nf_conntrack` в текущей сессии. - + `setup sysctl files` - применяет шаблоны для создания конфигурационных файлов в `/etc/sysctl.d/` для различных системных настроек (таких, как настройки безопасности, сети и файловой системы). Список файлов включает `10-console-messages.conf`, `10-link-restrictions.conf` и другие. После выполнения этой задачи отправляется уведомление для применения изменений в настройках ядра. - + `flush handlers` - вызывает накопленные хендлеры. Будет вызван хендлер `apply kernel settings`, который выполнит команду `sysctl -p` для применения параметров ядра, указанных в файле `/etc/sysctl.conf` или в других файлах в каталоге `/etc/sysctl.d/`. - * `configure cpu governor` – блок задач настройки режима управления частотой процессора: - + `install cpufrequtils` - установка пакета `cpufrequtils` из apt. В задаче установлены параметры проверки кеша apt и таймаут выполнения задачи в 300 секунд, чтобы ускорить выполнения задачи и избежать бесконечного цикла ожидания обновления пакетов apt. - + `use performance cpu governor` - создание файла `/etc/default/cpufrequtils` с содержимым "GOVERNOR=performance", что устанавливает режим работы CPU governor в "performance" (Отключения режима энергосбережения при простое ядер CPU). После выполнения задачи отправляется уведомление для перезапуска службы `cpufrequtils`. - + `disable ondemand.service` - отключение сервиса `ondemand.service`, если он присутствует в системе. Сервис останавливается, его автоматический запуск отключается, и он маскируется (предотвращается его запуск). После выполнения задачи отправляется уведомление для перезапуска cpufrequtils. - + `flush handlers` - вызывает накопленные хендлеры. Будет вызван хендлер `restart cpufrequtils`, который перезапустит сервис `cpufrequtils`. - + `start cpufrequtils` - запуск и активация службы `cpufrequtils.service`. Далее служба будет стартовать автоматически при загрузке системы. -3. [Роль](https://github.com/ydb-platform/ydb-ansible/blob/main/roles/ydbd/tasks/main.yaml) `ydbd`. Задачи: - * `check if required variables are defined` – проверка, что переменные `ydb_archive`, `ydb_config`, `ydb_tls_dir` определены. Если какая-либо из них не определена, Ansible выведет соответствующее сообщение об ошибке и остановит выполнение плейбука. - * `set vars_for_distribution variables` – установка переменных из указанного файла в переменной `vars_for_distribution_file` во время выполнения плейбука. Задача управляет набором переменных, зависящих от конкретного дистрибутива Linux. - * `ensure libaio is installed` – проверка, что пакет `libaio` установлен. - * `install custom libidn from archive` – установка пользовательской версии библиотеки `libidn` из архива. - * `create certs group` – создание системной группы `certs`. - * `create ydb group` – создание системной группы `ydb`. - * `create ydb user` – создание системного пользователя `ydb` с домашней директорией. - * `install YDB server binary package from archive` – установка YDB из скаченного архива. - * `create YDB audit directory` – создание поддиректории `audit` в директории установки YDB. - * `setup certificates` – блок задач по установки сертификатов безопасности: - + `create YDB certs directory` – создание поддиректории `certs` в директории установки YDB. - + `copy the TLS ca.crt` – копирование корневого сертификата `ca.crt` на сервер. - + `copy the TLS node.crt` – копирование TLS-сертификата `node.crt` из директории сгенерированных сертификатов. - + `copy the TLS node.key` – копирование TLS-сертификата `node.key` из директории сгенерированных сертификатов. - + `copy the TLS web.pem` – копирование TLS pem ключа `web.pem` из директории сгенерированных сертификатов. - * `copy configuration file` – копирование конфигурационного файла `config.yaml` на сервер. - * `add configuration file updater script` – копирование скрипта `update_config_file.sh` на сервер. -4. [Роль](https://github.com/ydb-platform/ydb-ansible/blob/main/roles/ydbd_static/tasks/main.yaml) `ydbd_static`. Задачи: - * `check if required variables are defined` – проверка, что переменные `ydb_cores_static`, `ydb_disks`, `ydb_domain`, `ydb_user` определены. Если хотя бы одна из этих переменных не определена, задача завершится с ошибкой, и будет выведено соответствующее сообщение об ошибке для каждой переменной, которая не была определена. - * `check if required secrets are defined` – проверка определения секретной переменной `ydb_password`. Если эта переменная не определена, задача завершится с ошибкой, и будет выведено сообщение об ошибке. - * `create static node configuration file` – создание конфигурационного файла статической ноды путём запуска скопированного скрипта `update_config_file.sh` и передачи в него конфигураций `ydbd-config.yaml`, `ydbd-config-static.yaml`. - * `create static node systemd unit` – создание файла `ydbd-storage.service` для статического узла на основе шаблона. После выполнения задачи отправляется уведомление для перезапуска службы `systemd`. - * `flush handlers` – выполнение накопленных хендлеров. Выполняется перезапуск всех служб `systemd`. - * `format drives confirmation block` – блок задач по форматированию дисков и прерывания выполнения плейбука в случае отказа пользователя от подтверждения. В терминал будет выведен запрос на подтверждение форматирования подключенного к серверу диска. Варианты ответа: `yes` – продолжить выполнение плейбука с форматированием диска. Любое другое значение, будет восприниматься как отказ от форматирования. По умолчанию диски форматируется автоматически без запроса разрешения у пользователя, так как переменные `ydb_allow_format_drives` и `ydb_skip_data_loss_confirmation_prompt` равны `true`. Если нужно запросить подтверждение от пользователя, то нужно изменить значение переменной `ydb_skip_data_loss_confirmation_prompt` на `false` в инвентаризационном файле `50-inventory.yaml`. - * `prepare drives` – задача по форматированию подключенных дисков. Вызывается плагин `drive_prepare` – это специально разработанный Ansible-модуль для установки YDB, который входит в состав поставки коллекции YDB и располагается в директории `.../.ansible/collections/ansible_collections/ydb_platform/ydb/plugins/action/drive_prepare.py`. Модуль выполнит форматирование подключенного к серверу диска, указанного в переменной `ydb_disks`. Форматирование будет произведено если переменная `ydb_allow_format_drives` имеет значение `true`. - * `start storage node` – запуск процесса сторадж ноды с помощью `systemd`. В случае возникновения любых ошибок запуска сервиса исполнение плейбука будет прервано. - * `get ydb token` – запрос токена YDB для выполнения команды инициализации стораджа. Токен сохраняется в переменной `ydb_credentials`. В задаче вызывается модуль `get_token` из директории `.../.ansible/collections/ansible_collections/ydb_platform/ydb/plugins/modules`. В случае возникновение любых ошибок на данном шаге выполнение плейбука будет прервано. - * `wait for ydb discovery to start working locally` – вызывается модуль `wait_discovery`, который выполняет запрос `ListEndpoints` к YDB для проверки работоспособности базовых подсистем кластера. Если подсистемы работают исправно – можно выполнять команды инициализации стороджа и создания базы данных. - * `init YDB storage if not initialized` – инициализация хранилища в случае если оно еще не создано. В задаче вызывается плагин `init_storage`, который выполняет команду инициализации хранилища с помощью grpcs-запроса к статической ноде на порт 2135. Результат выполнения команды сохраняется в переменной `init_storage`. - * `wait for ydb healthcheck switch to "GOOD" status` – ожидание получения статуса `GOOD` от системы проверки состояния YDB. В задаче вызывается плагин `wait_healthcheck`, который выполняет команду проверке состояния YDB. - * `set cluster root password` – установка пароля для root пользователя YDB. В задаче выполняется плагин `set_user_password`, который выполняет grpcs запрос к YDB и устанавливает заранее заданный пароль для root пользователя YDB. Пароль задаётся переменной `ydb_password` в инвентаризационном файле `/examples/9-nodes-mirror-3-dc/inventory/99-inventory-vault.yaml` в зашифрованном виде. -5. [Роль](https://github.com/ydb-platform/ydb-ansible/blob/main/roles/ydbd_dynamic/tasks/main.yaml) `ydbd_dynamic`. Задачи: - * `check if required variables are defined` – проверка наличия установленных переменных (`ydb_domain`,`ydb_pool_kind`, `ydb_cores_dynamic`, `ydb_brokers`, `ydb_dbname`, `ydb_dynnodes`) и вывод ошибки в случае отсутствия любой из переменных. - * `create dynamic node configuration file` – создание конфигурационного файла для динамических нод. - * `create dynamic node systemd unit` – создание сервиса для systemd динамических нод. После выполнения задачи отправляется уведомление для перезапуска службы `systemd`. - * `flush handlers` – выполнение накопившихся хендлеров. Будет выполнен рестарт `systemd`. - * `start dynamic nodes` – запуск процесса динамических нод с помощью `systemd`. - * `get ydb token` – получение токена для создания базы данных. - * `create YDB database` – создание базы данных. В задаче выполняется плагин `create_database`, который выполняет запрос создания БД к YDB. - * `wait for ydb discovery to start working locally` – повторно вызывается модуль `wait_discovery` для проверки работоспособности базовых подсистем кластера.
\ No newline at end of file diff --git a/ydb/docs/ru/core/sre/ansible/_includes/repo-tree.md b/ydb/docs/ru/core/sre/ansible/_includes/repo-tree.md deleted file mode 100644 index 4b157e5f220..00000000000 --- a/ydb/docs/ru/core/sre/ansible/_includes/repo-tree.md +++ /dev/null @@ -1,18 +0,0 @@ -```text -├── 8-nodes-block-4-2 / 9-nodes-mirror-3-dc -│ ├── ansible.cfg #Конфигурационный файл Ansible, который содержит настройки подключения к серверам и опции структуры проекта. -│ ├── ansible_vault_password_file #Пароль для пользователя root. -│ ├── creds #Переменные окружения, задающие имя пользователя и пароль для YDB. -│ ├── files -│ │ ├── config.yaml #Конфигурационный файл YDB. -│ ├── inventory #Директория с инвентаризационными файлами. -│ │ ├── 50-inventory.yaml #Основной инвентаризационный файл. -│ │ └── 99-inventory-vault.yaml #Зашифрованный инвентаризационный файл, содержащий пароль root пользователя от YDB. -│ ├── setup_playbook.yaml #Плейбук, который запускает роли установки и настройки {{ ydb-short-name }} на кластере. -├── README.md #Описание репозитория. -├── requirements.txt #Файл со списком зависимостей для установки Python пакетов в виртуальное окружение. -├── requirements.yaml #Файл с указателем на актуальные Ansible коллекции. -├── TLS #Директория, в которой создаётся поддиректория CA с TLS сертификатами. -│ ├── ydb-ca-nodes.txt #Список FQDN серверов для генерации TLS сертификатов -│ └── ydb-ca-update.sh #Скрипт для генерации TLS сертификатов из списка ydb-ca-nodes.txt -```
\ No newline at end of file diff --git a/ydb/docs/ru/core/sre/ansible/_includes/terraform/aws.md b/ydb/docs/ru/core/sre/ansible/_includes/terraform/aws.md deleted file mode 100644 index e69de29bb2d..00000000000 --- a/ydb/docs/ru/core/sre/ansible/_includes/terraform/aws.md +++ /dev/null diff --git a/ydb/docs/ru/core/sre/ansible/_includes/terraform/azure.md b/ydb/docs/ru/core/sre/ansible/_includes/terraform/azure.md deleted file mode 100644 index b8f342615aa..00000000000 --- a/ydb/docs/ru/core/sre/ansible/_includes/terraform/azure.md +++ /dev/null @@ -1,9 +0,0 @@ -Создайте [аккаунт](https://portal.azure.com/#home) в Azure и пополните [счёт](https://portal.azure.com/#view/Microsoft_Azure_GTM/ModernBillingMenuBlade/~/BillingAccounts) аккаунта на сумму, достаточную для работы девяти ВМ. Рассчитать примерную стоимость содержания инфраструктуры в зависимости от региона и прочих обстоятельств можно с помощью [калькулятора](https://azure.com/e/26977c150e854617a888fb3a7d1a399d). - -Аутентификация в провайдере Azure для Terraform осуществляется через CLI. Скачать, установить и настроить Azure CLI можно, следуя [этой](https://learn.microsoft.com/ru-ru/cli/azure/install-azure-cli) инструкции. Авторизоваться в Azure с помощью Azure CLI можно в интерактивном режиме командой `az login`, а для создания пары SSH-ключей (Linux, macOS) проще всего будет воспользоваться командой `ssh-keygen`. - -После авторизации в Azure и генерации SSH-ключей нужно изменить дефолтное значение следующих переменных в корневом файле `variables.tf`: -* `auth_location` – название региона, где будет развернута инфраструктура. Список доступных регионов в зависимости от подписки можно получить командой `az account list-locations | grep "displayName"`. -* `ssh_key_path` – путь к публичной части сгенерированного SSH-ключа. - -Значение остальных переменных можно оставить без изменения. Находясь в корневой директории Terraform сценария, выполните команду `terraform init` – будет установлен Terraform провайдер и инициализированы модули. После выполните команду `terraform plan` для создания плана создания инфраструктуры и далее выполните команду `terraform apply` для создания инфраструктуры в облаке Azure.
\ No newline at end of file diff --git a/ydb/docs/ru/core/sre/ansible/_includes/terraform/gcp.md b/ydb/docs/ru/core/sre/ansible/_includes/terraform/gcp.md deleted file mode 100644 index 706db7b9b28..00000000000 --- a/ydb/docs/ru/core/sre/ansible/_includes/terraform/gcp.md +++ /dev/null @@ -1,18 +0,0 @@ -1. Зарегистрируйтесь в Google Cloud console и [создайте](https://console.cloud.google.com/projectselector2/home) проект. -3. Активируйте [платежный аккаунт](https://console.cloud.google.com/billing/manage) и пополните его средствами для запуска девяти ВМ. Рассчитать стоимость можно в [калькуляторе](https://cloud.google.com/products/calculator). -4. Актируйте [Compute Engine API](https://console.cloud.google.com/apis/api/compute.googleapis.com/metrics) и [Cloud DNS API](https://console.cloud.google.com/apis/api/dns.googleapis.com/metrics). -5. Скачайте и установите GCP CLI, следуя [этой](https://cloud.google.com/sdk/docs/install) инструкции. -6. Перейдите в поддиректорию `.../google-cloud-sdk/bin` и выполните команду `./gcloud compute regions list` для получения списка доступных регионов. -7. Выполните команду `./gcloud auth application-default login` для настройки профиля подключения. -8. Скачайте репозиторий с помощью команды `git clone https://github.com/ydb-platform/ydb-terraform`. -9. Перейдите в поддиректорию `gcp` (находится в скаченном репозитории) и в файле `variables.tf` задайте актуальные значения следующим переменным: - * `project` – название проекта, которое было задано в облачной консоли Google Cloud. - * `region` – регион, где будет развернута инфраструктура. - * `zones` – список зон доступности, в которых будут созданы подсети и ВМ. - -Теперь, находясь в поддиректории `gcp` можно выполнить последовательность следующих команд для установки провайдера, инициализации модулей и создания инфраструктуры: -* `terraform init` – установка провайдера и инициализация модулей. -* `terraform plan` – создание плана будущей инфраструктуры. -* `terraform init` (повторное выполнение) – создание ресурсов в облаке. - -Далее используются команды `terraform plan`, `terraform init` и `terraform destroy` (уничтожение созданной инфраструктуры).
\ No newline at end of file diff --git a/ydb/docs/ru/core/sre/ansible/_includes/terraform/yc.md b/ydb/docs/ru/core/sre/ansible/_includes/terraform/yc.md deleted file mode 100644 index 04e2f91aaae..00000000000 --- a/ydb/docs/ru/core/sre/ansible/_includes/terraform/yc.md +++ /dev/null @@ -1,44 +0,0 @@ -Для создания инфраструктуры в Yandex Cloud с помощью Terraform нужно: -1. Подготовить облако к работе: - * [Зарегистрироваться](https://console.cloud.yandex.ru/) в Yandex Cloud. - * [Подключить](https://cloud.yandex.com/ru/docs/billing/concepts/billing-account) платежный аккаунт. - * [Убедится](https://console.cloud.yandex.ru/billing) в наличии достаточного количества средств для создания девяти ВМ. -2. Установить и настроить Yandex Cloud CLI: - * [Скачать](https://cloud.yandex.ru/ru/docs/cli/quickstart) Yandex Cloud CLI. - * [Создать](https://cloud.yandex.ru/ru/docs/cli/quickstart#initialize) профиль -3. [Создать](https://cloud.yandex.com/ru/docs/tutorials/infrastructure-management/terraform-quickstart#get-credentials) сервисный аккаунт с помощью CLI. -4. [Сгенерировать](https://cloud.yandex.ru/ru/docs/cli/operations/authentication/service-account#auth-as-sa) SA ключ в JSON формате для подключения Terraform к облаку с помощью CLI: `yc iam key create --service-account-name <acc name> --output <file name> --folder-id <cloud folder id>`. Будет сгенерирован SA ключ, а в терминал будет выведена секретная информация: - ``` - access_key: - id: ajenhnhaqgd3vp... - service_account_id: aje90em65r6922... - created_at: "2024-03-05T20:10:50.0150..." - key_id: YCAJElaLsa0z3snzH4E... - secret: YCPKNJDVhRZgyywl4hQwVdcSRC... - ``` - Скопируйте `access_key.id` и `secret`. Значения этих полей нужны будут в дальнейшем при работе с AWS CLI. -5. [Скачать](https://aws.amazon.com/ru/cli/) AWS CLI. -6. Настроить окружение AWS CLI: - * Запустите команду `aws configure` и последовательно введите сохраненные ранее `access_key.id` и `secret`. Для значения региона используйте `ru-central1`: - ``` - aws configure - AWS Access Key ID [None]: AKIAIOSFODNN******** - AWS Secret Access Key [None]: wJalr********/*******/bPxRfiCYEX******** - Default region name [None]: ru-central1 - Default output format [None]: - ``` - Будут созданы файлы `~/.aws/credentials` и `~/.aws/config`. -7. Отредактировать `~/.aws/credentials` и `~/.aws/config` следующим образом: - * Добавьте `[Ya_def_reg]` в `~/.aws/config` перед `region = ru-central1-a`. - * Добавьте `[Yandex]` перед секретной информацией о ключах подключения. -8. [Настроить](https://cloud.yandex.com/ru/docs/tutorials/infrastructure-management/terraform-quickstart#configure-provider) Yandex Cloud Terraform провайдера. -9. Скачать данный репозиторий командой `git clone https://github.com/ydb-platform/ydb-terraform.git`. -10. Перейти в директорию `yandex_cloud` (директория в скаченном репозитории) и внести изменения в следующие переменные, в файле `variables.tf`: - * `key_path` – путь к сгенерированному SA ключу с помощью CLI. - * `cloud_id` – ID облака. Можно получить список доступных облаков командой `yc resource-manager cloud list`. - * `profile` – название профиля из файла `~/.aws/config`. - * `folder_id` – ID Cloud folder. Можно получить командой `yc resource-manager folder list`. - -Теперь, находясь в директории `yandex_cloud`, можно выполните команду `terraform init` для установки провайдера и инициализации модулей. Далее нужно выполнить серию команд: -* `terraform plan` – создание плана будущей инфраструктуры. -* `terraform init` (повторный вызов) – создание ресурсов в облаке.
\ No newline at end of file diff --git a/ydb/docs/ru/core/sre/ansible/index.md b/ydb/docs/ru/core/sre/ansible/index.md deleted file mode 100644 index 45c5772ff3c..00000000000 --- a/ydb/docs/ru/core/sre/ansible/index.md +++ /dev/null @@ -1,8 +0,0 @@ -# Работа с {{ ydb-short-name }} с помощью Ansible - -Этот раздел документации {{ ydb-short-name }} содержит набор статей, предназначенных для работы SRE с кластерами {{ ydb-short-name }} при помощи [Ansible](https://www.ansible.com/). Это рекомендуемый подход к запуску produciton кластеров {{ ydb-short-name }}, если ваша организация ещё не внедрила [Kubernetes](../kubernetes/index.md). - -Ключевые статьи для начала работы с этим разделом: - -* [Первоначальное развертывание](initial-deployment.md) -* [Подготовка виртуальных машин с помощью Terraform](preparing-vms-with-terraform.md) diff --git a/ydb/docs/ru/core/sre/ansible/initial-deployment.md b/ydb/docs/ru/core/sre/ansible/initial-deployment.md deleted file mode 100644 index 04e1dcddec8..00000000000 --- a/ydb/docs/ru/core/sre/ansible/initial-deployment.md +++ /dev/null @@ -1,277 +0,0 @@ -# Развертывание {{ ydb-short-name }} кластера с помощью Ansible - -В инструкции изложен процесс развертывания {{ ydb-short-name }} кластера на группе серверов с помощью Ansible. {{ ydb-short-name }} может быть развернут на любом желаемом количестве серверов, но минимальное количество серверов в кластере не должно быть меньше восемь штук для модели избыточности `block-4-2` и девяти серверов для модели избыточности `mirror-3-dc`. О моделях избыточности можно узнать из статьи [{#T}](../../cluster/topology.md). - -В процессе эксплуатации кластер может быть [расширен](../../maintenance/manual/cluster_expansion.md) без приостановки доступа пользователей к базам данных. - -{% note info %} - -**Рекомендуемые требования к серверам**: -* 16 CPU (рассчитывается исходя из утилизации 8 CPU сторадж нодой и 8 CPU динамической нодой). -* 16 GB RAM (рекомендуемый минимальный объем RAM). -* Дополнительный сетевой SSD-диск размером 120 GB (не может быть меньшего размера – требования инсталляции {{ ydb-short-name }}). -* Доступ по SSH; -* Сетевая связность машин в кластере. -* OS: Ubuntu 18+, Debian 9+. -* Доступ в интернет для обновления репозиториев и скачивания нужных пакетов. - -{% endnote %} - -Скачать репозиторий с плейбуком для установки {{ ydb-short-name }} на кластер можно с GitHub – `git clone https://github.com/ydb-platform/ydb-ansible-examples.git`. Этот репозиторий содержит: шаблоны установки {{ ydb-short-name }} на кластер из восьми серверов – `8-nodes-block-4-2`и девяти серверов – `9-nodes-mirror-3-dc`, а также скрипты для генерации TLS-сертификатов и файлы requirements для установки необходимых Python пакетов. - -{% cut "Структура репозитория" %} - -{% include [repo-tree](./_includes/repo-tree.md) %} - -{% endcut %} - -Для работы с проектом на локальной (промежуточной или инсталляционной) машине понадобится: Python 3 версии 3.10+ и Ansible core не ниже версии 2.15.2. Ansible можно установить и запустить глобально (устанавливается в систему) или в виртуальном окружении. Если Ansible уже установлен – можно переходить к шагу [«Настройка Ansible проекта»](#ansible-project-setup), если Ansible ещё не установлен, установите его одним из предложенных способов: - -{% list tabs %} - -- Установка Ansible в систему (глобально) - - * Обновите список пакетов apt репозитория – `sudo apt update`. - * Обновите пакеты – `sudo apt upgrade`. - * Установите пакет `software-properties-common` для управления источниками программного обеспечения вашего дистрибутива – `sudo apt install software-properties-common`. - * Добавьте новый PPA в apt – `sudo add-apt-repository --yes --update ppa:ansible/ansible`. - * Установите Ansible – `sudo apt install ansible-core`. - * Проверьте версию Ansible core – `ansible --version` - -- Установка Ansible в виртуальное окружение Python - - * Обновите список пакетов apt репозитория – `sudo apt update`. - * Установите пакет `venv` для Python3 – `sudo apt install python3-venv` - * Создайте директорию, где будет создано виртуальное окружение и куда будут скачены плейбуки. Например, `mkdir ydb-install-ansible`. - * Перейдите в созданную директорию и создайте виртуальное окружение – `sudo python3 -m venv ydb-ansible`. - * Активируйте виртуальное окружение – `source venv/bin/activate`. В дальнейшем все действия по работе с Ansible выполняются внутри виртуального окружения. Выйти из него можно командой `deactivate`. - * Установите Ansible рекомендуемой версии с помощью команды `pip install -r requirements.txt`, находясь в корневой директории скаченного репозитория. - * Проверьте версию Ansible core – `ansible --version` - -{% endlist %} - - -## Настройка Ansible проекта { #ansible-project-setup } - -Перейдите в корневую директорию скаченного репозитория и выполните команду `ansible-galaxy install -r requirements.yaml` – будут скачены Ansible коллекции `ydb_platform.ydb` и `community.general`, которые содержат роли и плагины для установки {{ ydb-short-name }}. - -[Скачайте](../../downloads/index.md#ydb-server) архив актуальной версию {{ ydb-short-name }} в корневую директорию проекта. Например, с помощью wget: `wget https://binaries.ydb.tech/release/23.3.17/ydbd-23.3.17-linux-amd64.tar.gz` и скопируйте сюда же приватную часть SSH-ключа для доступа к серверам кластера {{ ydb-short-name }}. На SSH-ключе должны быть установлены следующие права: -```text --rw------- (600) #Только владелец имеет разрешение на чтение и запись. -``` -Установить нужные права можно командой `sudo chmod 600 <ssh-key name>`. - -Далее можно перейти в директорию TLS и указать в файле `ydb-ca-nodes.txt` список FQDN серверов, для которых будут сгенерированы TLS сертификаты. По умолчанию список выглядит следующим образом: -```text -static-node-1 static-node-1.ydb-cluster.com -static-node-2 static-node-2.ydb-cluster.com -static-node-3 static-node-3.ydb-cluster.com -static-node-4 static-node-4.ydb-cluster.com -static-node-5 static-node-5.ydb-cluster.com -static-node-6 static-node-6.ydb-cluster.com -static-node-7 static-node-7.ydb-cluster.com -static-node-8 static-node-8.ydb-cluster.com -static-node-9 static-node-9.ydb-cluster.com -``` - -Сгенерировать набор TLS сертификатов, который будут размещены в поддиректории CA (`TLS/CA/certs/<create date_crete time>`) можно скриптом `ydb-ca-update.sh`. - -После генерации TLS сертификатов, установки Ansible коллекций, загрузки приватной части ssh-ключа и скачивания актуальной версии {{ ydb-short-name }} необходимо обновить инвентаризационные файлы в соответствии с выбранным видом кластера для развертывания. - -### Изменения инвентаризационных файлов проекта { #inventory-edit } - -Вне зависимости от вида создаваемого кластера (восемь серверов – `8-nodes-block-4-2` или девять серверов – `9-nodes-mirror-3-dc`) основные параметра установки и настройки {{ ydb-short-name }} содержатся в инвентаризационном файле `50-inventory.yaml`, который расположен в директории `<cluster model>/inventory/`. - -В инвентаризационном файле `50-inventory.yaml` нужно указать актуальный список FQDN серверов, на которые будет установлена {{ ydb-short-name }}. По умолчанию список выглядит следующим образом: - ```yaml - all: - children: - ydb: - hosts: - static-node-1.ydb-cluster.com: - static-node-2.ydb-cluster.com: - static-node-3.ydb-cluster.com: - static-node-4.ydb-cluster.com: - static-node-5.ydb-cluster.com: - static-node-6.ydb-cluster.com: - static-node-7.ydb-cluster.com: - static-node-8.ydb-cluster.com: - static-node-9.ydb-cluster.com: - ``` - -Далее нужно внести следующие изменения в раздел `vars` инвентаризационного файла: - * `ansible_user` – укажите пользователь для подключения Ansible по SSH. - * `ansible_ssh_common_args: "-o ProxyJump=<ansible_user>@<static-node-1 IP>"` – опция для подключения Ansible к серверу по IP, с которого будет устанавливаться {{ ydb-short-name }} (включая ProxyJump сервер). Используется при установки {{ ydb-short-name }} с локальной машины, не входящей в приватную DNS-зону. - * `ansible_ssh_private_key_file` – измените дефолтное название ssh-ключа, на актуальное: `"../<ssh-private-key-name>"`. - * `ydb_tls_dir` – укажите актуальную часть пути (`/files/CA/certs/<date_time create certs>`) к сертификатам безопасности после их генерации скриптом `ydb-ca-update.sh`. - * `ydb_brokers` – укажите список FQDN нод брокеров. Например: - ```yaml - ydb_brokers: - - static-node-1.ydb-cluster.com - - static-node-2.ydb-cluster.com - - static-node-3.ydb-cluster.com - ``` - * `ydb_cores_static` – задайте количество ядер CPU, потребляемое статической нодой; - * `ydb_cores_dynamic` – задайте количество ядер CPU, потребляемое динамической нодой; - -Значение переменной `ydb_database_groups` в разделе `vars` имеет фиксированное значение, которое привязано к типу избыточности и не зависит от размера кластера: -* Для типа избыточности `block-4-2` значение `ydb_database_groups` равно семи. -* Для типа избыточности `mirror-3-dc` значение `ydb_database_groups` равно восьми. - - -Значение переменных `system_timezone` и `system_ntp_servers` зависит от свойств инфраструктуры, на которой развертывается YDB кластер. По умолчанию в `system_ntp_servers` указан набор NTP-серверов без учёта географического расположения инфраструктуры, на которой будет развертываться YDB кластер. Мы настоятельно рекомендуем использовать локальный NTP-сервер для on-premise инфраструктуры и следующие NTP-серверы для облачных провайдеров: - -{% list tabs %} - -- Yandex Cloud - * `system_timezone`: Europe/Moscow - * `system_ntp_servers`: [0.ru.pool.ntp.org, 1.ru.pool.ntp.org, ntp0.NL.net, ntp2.vniiftri.ru, ntp.ix.ru, ntps1-1.cs.tu-berlin.de] [Подробнее](https://cloud.yandex.ru/ru/docs/tutorials/infrastructure-management/ntp) о настройках NTP-серверов Yandex Cloud. - -- AWS - * `system_timezone`: USA/<region_name> - * `system_ntp_servers`: [169.254.169.123, time.aws.com] [Подробнее](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/set-time.html#configure-time-sync) о настройках NTP-серверов AWS. - -- Azure - * О том как настраивается синхронизация времени на виртуальных машинах Azure можно прочесть в [данной](https://learn.microsoft.com/en-us/azure/virtual-machines/linux/time-sync) статье. - -- Alibaba - * Cпецифика подключения к NTP-серверам в Alibaba описана в этой [статье](https://www.alibabacloud.com/help/en/ecs/user-guide/alibaba-cloud-ntp-server). - -{% endlist %} - -Изменения других секций конфигурационного файла `50-inventory.yaml` не требуется. Далее можно изменить стандартный пароль root пользователя YDB, который содержится в зашифрованном инвентаризационном файле `99-inventory-vault.yaml` и файле `ansible_vault_password_file.txt`. Для изменения пароля – укажите новый пароль в файле `ansible_vault_password_file.txt` и продублируйте его в файле `99-inventory-vault.yaml` в формате: - ```yaml - all: - children: - ydb: - vars: - ydb_password: <new password> - ``` - -Для шифрования `99-inventory-vault.yaml` выполните команду `ansible-vault encrypt inventory/99-inventory-vault.yaml`. - -После изменения инвентаризационных файлов можно переходить к подготовке конфигурационного файла {{ ydb-short-name }}. - -### Подготовка конфигурационного файла {{ ydb-short-name }} { #ydb-config-prepare } - -Конфигурационный файл {{ ydb-short-name }} – содержит настройки нод {{ ydb-short-name }} и располагается в поддиректории `/files/config.yaml`. С подробным описанием секций настройки конфигурационного файла {{ ydb-short-name }} можно ознакомиться в стать [{#T}](../../deploy/configuration/config.md). - -Дефолтный конфигурационный файл {{ ydb-short-name }} уже содержит почти все необходимые настройки для развертывания кластера. Необходимо заменить стандартные FQDN хостов на актуальные FQDN в разделе `hosts` и `blob_storage_config`: -* Раздел `hosts`: - ```yaml - ... - hosts: - - host: static-node-1.ydb-cluster.com #FQDN ВМ - host_config_id: 1 - walle_location: - body: 1 - data_center: 'zone-a' - rack: '1' - ... - ``` -* Раздел `blob_storage_config`: - ```yaml - ... - - fail_domains: - - vdisk_locations: - - node_id: static-node-1.ydb-cluster.com #FQDN ВМ - pdisk_category: SSD - path: /dev/disk/by-partlabel/ydb_disk_1 - ... - ``` - -Остальные секции и настройки конфигурационного файла остаются без изменений. - - -## Развертывания кластера {{ ydb-short-name }} { #erasure-setup } - -{% note info %} - -Минимальное количество серверов в кластере {{ ydb-short-name }} – восемь серверов для модели избыточности `block-4-2` и девять серверов для модели избыточности `mirror-3-dc`. - -{% endnote %} - -[Репозиторий](https://github.com/ydb-platform/ydb-ansible-examples) содержит два готовых набора шаблонов для развертывания {{ ydb-short-name }} кластера из восьми (модель избыточности `block-4-2`) и девяти серверов (`mirror-3-dc`). Любой из предложенных вариантов может быть масштабирован на любое нужное количество серверов с учётом ряда технических требований. - -Для подготовки собственного шаблона можно воспользоваться следующей инструкцией: -1. Создайте копию директории с готовым примером (`9-nodes-mirror-3-dc` или `8-nodes-block-4-2`). -2. Укажите FQDN серверов в файле `TLS/ydb-ca-nodes.txt` и выполните скрипт `ydb-ca-update.sh` для генерации наборов TLS сертификатов. -3. Внесите изменения в инвентаризационные файлы шаблона в соответствии с [инструкцией](#inventory-edit). -4. Внесите изменения в конфигурационный файл {{ ydb-short-name }} в соответствии с [инструкцией](#ydb-config-prepare). -5. Выполните команду `ansible-playbook setup_playbook.yaml`, находясь в директории клонированного шаблона. - -## План выполнения сценария установки {{ ydb-short-name }} { #ydb-playbook-run } - -Последовательность выполнение ролей и их краткое описание: -1. Роль `packages` настраивает репозитории, управляет предпочтениями и конфигурациями APT, а также исправляет неконфигурированные пакеты и устанавливает необходимые программные пакеты в зависимости от версии дистрибутива. -2. Роль `system` устанавливает системные настройки, включая конфигурацию часов и временной зоны, синхронизацию времени через NTP с помощью `systemd-timesyncd`, настройку `systemd-journald` для управления журналами, конфигурацию загрузки модулей ядра и оптимизацию параметров ядра через `sysctl`, а также настройку производительности процессора с использованием `cpufrequtils`. -3. Роль `ydb` выполняет задачи по проверке необходимых переменных, установке базовых компонентов и зависимостей, настройке системных пользователей и групп, развертыванию и конфигурированию {{ ydb-short-name }}, включая управление сертификатами TLS и обновление конфигурационных файлов. -4. Роль `ydb-static` отвечает за подготовку и запуск статических нод {{ ydb-short-name }}, включая проверку необходимых переменных и секретов, форматирование и подготовку дисков, создание и запуск `systemd unit` для узла хранения, а также инициализацию хранилища и управление доступом к базе данных. -5. Роль `ydb-dynamic` настраивает и управляет динамическими узлами {{ ydb-short-name }}, включая проверку необходимых переменных, создание конфигурационных файлов и `systemd unit` файлов для каждого динамического узла, запуск этих узлов, получение токена для доступа к {{ ydb-short-name }}, создание базы данных в {{ ydb-short-name }}. - -{% cut "Подробное пошаговое описание установки {{ ydb-short-name }}" %} - -{% include [ansible-install-steps](./_includes/ansible-install-steps.md) %} - -{% endcut %} - -В результате выполнения плейбука будет создан кластер {{ ydb-short-name }}, на котором развернута тестовая база данных – `database`, создан `root` пользователь с максимальными правами доступа и запущен Embedded UI на порту 8765. Для подключения к Embedded UI можно настроить SSH-туннелирование. Для этого на локальной машине выполните команду `ssh -L 8765:localhost:8765 -i <ssh private key> <user>@<first ydb static node ip>`. После успешной установки соединения можно перейти по URL [localhost:8765](http://localhost:8765): - - - -## Мониторинг состояния кластера { #troubleshooting } - -После успешного создания кластера {{ ydb-short-name }} проверить его состояние с помощью Embedded UI – [http://localhost:8765/monitoring/cluster/tenants](http://localhost:8765/monitoring/cluster/tenants): - - - -В разделе отражены следующие параметры кластера {{ ydb-short-name }}, которые отражают состояние кластера: -* `Tablets` – список запущенных [таблеток](../../concepts/cluster/common_scheme_ydb.md#tablets). Все индикаторы состояния таблеток должны быть зеленого цвета; -* `Nodes` – количество и состояние запущенных статических и динамических нод в кластере. Индикатор состояния нод должен быть зеленым, а пропорция созданных и запущенных нод должна быть равной. Например, 27/27 для кластера из девяти нод. -Индикаторы показателей `Load` (количество используемой RAM) и `Storage` (количество используемого дискового пространства) должны быть зелеными. - -Проверь состояние сторадж группы можно в разделе `storage` – [http://localhost:8765/monitoring/cluster/storage](http://localhost:8765/monitoring/cluster/storage): - - - -Индикаторы `VDisks` должны быть зелеными, а статус `state` (находится в сплывающей подсказке при наведении на индикатор Vdisk) должен быть `Ok`. Подробнее о показателях состояния кластера и мониторинге можно прочитать в статье [{#T}](../../maintenance/embedded_monitoring/ydb_monitoring.md). - -## Тестирование кластера { #testing } - -Протестировать кластер можно с помощью встроенных в YDB CLI нагрузочных тестов. Для этого скачайте на машину, на которой установлен Ansible, YDB CLI версии [2.5.0](https://storage.yandexcloud.net/yandexcloud-ydb/release/2.5.0/linux/amd64/ydb). Например, с помощью wget: `wget https://storage.yandexcloud.net/yandexcloud-ydb/release/2.5.0/linux/amd64/ydb`. - -Сделайте скаченный бинарный файл исполняемым – `chmod +x ydb` и создайте [профиль](../../reference/ydb-cli/profile/index.md) подключения к YDB: -```shell -./ydb \ -config profile create <profile name> \ --d /Root/database \ --e grpcs://< FQDN node >:2135 \ ---ca-file <path to generated certs>/CA/certs/ca.crt \ ---user root \ ---password-file <path to vault password file>/ansible_vault_password_file -``` - -Параметры команды и их значения: -* `config profile create` – команда создания профиля подключения. Задаётся имя профиля. Более детальную информацию, о том как создавать и изменять профили можно найти в статье [{#T}](../../reference/ydb-cli/profile/create.md). -* `-e` – эндпоинт (endpoint) - строка в формате `protocol://host:port`. Можно указать FQDN любой ноды кластера и не указывать порт. По умолчанию будет использован 2135 порт. -* `--ca-file` – путь к корневому сертификату для подключения к базе по `grpcs`. Сертификат создаётся скриптом `ydb-ca-update.sh` в директории `TLS` и располагается по пути `TLS/CA/certs/` относительно корня репозитория ydb-ansible-examples. -* `--user` – пользователь для подключения к БД. По умолчанию при выполнении `setup_playbook.yaml` плейбука создаётся пользователь root. -* `--password-file` – путь к файлу с паролем. В каждой папке с шаблоном развертывания YDB кластера находится файл `ansible_vault_password_file`, который содержит пароль пользователя `root`. - -Проверить создался ли профиль можно командой `./ydb config profile list` – будет выведен список профилей. После создания профиля, его нужно активировать командой `./ydb config profile activate <profile name>`. Проверить, что профиль был активирован можно повторным выполнением команды `./ydb config profile list` – активный профиль будет иметь отметку (active). - -Теперь можно выполнить YQL запрос `./ydb yql -s 'select 1;'`, который вернет в терминал результат выполнения команды `select 1` в табличной форме. После проверки соединения можно создать тестовую таблицу командой: -`./ydb workload kv init --init-upserts 1000 --cols 4`. Будет создана тестовая таблица `kv_test`, состоящая из 4 столбцов и 1000 строк. Проверь, что таблица `kv_test` создалась и заполнилась тестовыми данными, можно командой `./ydb yql -s 'select * from kv_test limit 10;'`. - -В терминал будет выведена таблица из 10 строк. Теперь можно выполнять тестирование производительности кластера. В статье [{#T}](../../reference/ydb-cli/workload-kv.md) описаны 5 видов нагрузок (`upsert`, `insert`, `select`, `read-rows`, `mixed`) и параметры их выполнения. Пример выполнения тестовой нагрузки `upsert` с параметром вывода времени выполнения запроса `--print-timestamp` и стандартными параметрами исполнения: `./ydb workload kv run upsert --print-timestamp`. - -В терминал будет выведен отчёт следующего вида: -``` -Window Txs/Sec Retries Errors p50(ms) p95(ms) p99(ms) pMax(ms) Timestamp -1 727 0 0 11 27 71 116 2024-02-14T12:56:39Z -2 882 0 0 10 21 29 38 2024-02-14T12:56:40Z -3 848 0 0 10 22 30 105 2024-02-14T12:56:41Z -... -``` - -После завершения тестов удалить таблицу `kv_test` можно командой: `./ydb workload kv clean`. Подробнее об опциях создания тестовой таблицы и тестах можно прочесть в статье [{#T}](../../reference/ydb-cli/workload-kv.md).
\ No newline at end of file diff --git a/ydb/docs/ru/core/sre/ansible/preparing-vms-with-terraform.md b/ydb/docs/ru/core/sre/ansible/preparing-vms-with-terraform.md deleted file mode 100644 index e1d489a8574..00000000000 --- a/ydb/docs/ru/core/sre/ansible/preparing-vms-with-terraform.md +++ /dev/null @@ -1,141 +0,0 @@ -# Разворачивание инфраструктуры для кластера {{ ydb-short-name }} с помощью Terraform - -Существует три рекомендованных способа разворачивать кластера {{ ydb-short-name }} для production использования: c помощью [Ansible](initial-deployment.md), [Kubernetes](../kubernetes/initial-deployment.md) или [вручную](../../deploy/index.md). Если вариант с Kubernetes практически самодостаточен, то для вариантов с Ansible и вручную для старта нужен ssh доступ на необходимое количество правильно сконфигурированных серверов или виртуальных машин. В данной статье описывается как можно создать и сконфигурировать необходимый для кластера {{ ydb-short-name }} набор виртуальных машин в различных облачных провайдерах. - -**[Terraform](https://www.terraform.io/)** – это программное обеспечение с открытым исходным кодом для управления инфраструктурой по модели "инфраструктура как код" (Infrastructure as Code). Такой же подход используется в Ansible, в системе управления конфигурациями. Terraform и Ansible работают на разных уровнях: Terraform управляет инфраструктурой, а Ansible настраивает окружения на ВМ: - - - -Конфигурация настройки окружения ВМ описывается в YAML формате, а инфраструктурный код пишется на [HCL](https://github.com/hashicorp/hcl) (язык конфигурации Terraform). Основной логической единицей записи в HCL является "блок". Блок состоит из ключевого слова, идентифицирующего его тип, названия и фигурных скобок, обозначающих тело блока. Например, так может выглядеть блок управления виртуальным сервером в AWS: -```hcl -resource "aws_instance" "ydb-vm" { - count = var.instance_count - ami = "ami-008fe2fc65df48dac" - instance_type = "t2.micro" - key_name = var.req_key_pair - vpc_security_group_ids = [var.input_security_group_id] - subnet_id = element(var.input_subnet_ids, count.index % length(var.input_subnet_ids)) - - tags = { - Name = "ydb-node-${count.index +1}" - Username = "ubuntu" - } - -} -``` - -Блоки могут располагаться друг за другом в одном файле и быть независимыми, могут ссылать друг на друга и быть зависимыми, а также могут вкладываться друг в друга. - -Основные типы блоков: -* `resource` – блок инициализация ресурса инфраструктуры (ВМ, сеть, подсеть, диск, DNS-зона и т.д.); -* `provider` – блок инициализация провайдера, версии API и данных для аутентификации; -* `variable` – переменная как со значением по умолчанию, так и пустая для хранения данных, введенных пользователем или переданных другими блоками; -* `output` – вывод данных в терминал и сохранение в переменной; -* `data` – переменная для запроса данных от внешних облачных ресурсов, не представленных в создаваемой инфраструктуре; -* `module` – логическая группировка ресурсов, которые можно переиспользовать несколько раз в рамках одного или разных проектов; -* `terraform` – блок настройки поведения самого Terraform, включая версию Terraform и используемых провайдеров, а также настройки бэкенда, который используется для хранения состояния Terraform. - -Блоки записываются в файлы с расширением `.tf` и логически группируются в директориях, которые в терминологии Terraform называют модулями. Модуль обычно состоит из следующих файлов: -* `main.tf` – основной файл, в котором находится код инфраструктуры. Может быть несколько файлов, содержащих инфраструктурный код. -* `variables.tf` – локальные переменные модуля, которые принимают данные от других модулей или имеют дефолтные значения. -* `outputs.tf` – переменные, которые содержат результаты работы ресурса (IP адреса ВМ, ID сетей/подсетей и т.д). - -Модули подключаются к проекту в корневом файле `main.tf` следующим образом: -``` -module "vpc" { - source = "./modules/vpc" - subnets_count = var.subnets_count - subnets_availability_zones = var.availability_zones -} -``` -В примере подключается модуль `vpc` (имя модуля назначается при подключении). Обязательный параметр – это `source` – путь к директории, где располагается модуль. `subnets_count` и `subnets_availability_zones` – это переменные внутри модуля `vpc`, которые принимают значения из переменных глобального уровня `var.subnets_count`, `var.availability_zones`. - -Модули так же как и блоки располагаются друг за другом в корневом `main.tf` проекта. Основное преимущество модульного подхода организации проекта – возможность легко управлять логически связанными наборами ресурсов. Поэтому наш [репозиторий](https://github.com/ydb-platform/ydb-terraform) с готовыми Terraform сценариями организован следующим образом: -```txt -. -├── README.md -├── README_RU.md -├── aws -│ ├── README.md -│ ├── README_RU.md -│ ├── main.tf -│ ├── modules -│ │ ├── dns -│ │ ├── eip -│ │ ├── instance -│ │ ├── key_pair -│ │ ├── security -│ │ └── vpc -│ └── variables.tf -├── azure -│ ├── README.md -│ ├── README_RU.md -│ ├── main.tf -│ ├── modules -│ │ ├── dns -│ │ ├── resource_group -│ │ ├── security -│ │ ├── vm -│ │ └── vpc -│ └── variables.tf -├── ... -``` - -Поддиректории содержат два `readme`, файл `variables.td` с локальными переменными модуля и основной файл `main.tf`, который подключает модули из поддиректории `modules`. Набор модулей зависит от облачного провайдера. Базовые модули, функционально одинаковые для всех провайдеров имеют одинаковые названия: -* `vpc` – модуль управления облачной сетью и подсетями. -* `dns` – модуль управления DNS-зоной и DNS-записями. -* `security` – модуль управления группами безопасности. -* `instance` – модуль управления ВМ. - -Для того, чтобы воспользоваться готовыми Terraform сценариями из репозитория, нужно скачать репозиторий командой `git clone https://github.com/ydb-platform/ydb-terraform.git`, внести изменения в конфигурационный файл Terraform `~/.terraformrc`, задать актуальные значения глобальных переменных сценария и скачать CLI того облачного провайдера, где будет создана инфраструктура. - -Если вы планируете использовать несколько провайдеров, можно добавить следующий код в `~/.terraformrc`, который установит пути скачивания для всех провайдеров описанных ниже: -``` -provider_installation { - network_mirror { - url = "https://terraform-mirror.yandexcloud.net/" - include = ["registry.terraform.io/*/*"] - } - direct { - exclude = ["registry.terraform.io/*/*"] - exclude = ["terraform.storage.ydb.tech/*/*"] - } - - filesystem_mirror { - path = "/Applications/ - } - } -``` - -Если уже используются Terraform провайдеры, представленные в [официальном репозитории](https://registry.terraform.io/browse/providers), они продолжат работать. - -Далее приведены пошаговые инструкции создания инфраструктуры в [AWS](#aws-cluster), [Azure](#aws-cluster), [GCP](#gcp-cluster), [Yandex Cloud](#gcp-cluster). Предложенные Terraform сценарии развертывают однотипную инфраструктуру: - -В инфраструктуру входят: -* Девять виртуальных ВМ (16 CPU, 32 GB RAM, дополнительный диск на 200 GB). -* Облачная сеть и три подсети (по подсети на зону доступности). -* Приватная DNS-зона. -* Группы безопасности, разрешающие трафик на портах: 22, icmp, 8765. - -Большинство параметров кластера регулируется (количество ВМ, объём и тип подключаемого диска, количество сетей, домен DNS-зоны и т.д.), однако обратите внимание на то, что есть рекомендуемые значения параметров кластера, которые уже определены как дефолтные значения. Их изменения в меньшую сторону может привести кластер в нерабочее состояние. Такими рекомендуемыми значениями параметров кластера являются: -* Количество ядер CPU. Минимальное рекомендуемое количество ядер CPU – 16 штук. -* Размер RAM. Минимальный рекомендуемый объём RAM – 32 GB. -* Объём присоединенного диска. Минимальный рекомендуемый объём присоединенного диска – 200 GB. - -## Создание инфраструктуры в AWS для развертывания {{ ydb-short-name }} кластера {#aws-cluster} - -{% include [aws](./_includes/terraform/aws.md) %} - -## Создание инфраструктуры в Azure для развертывания {{ ydb-short-name }} кластера {#azure-cluster} - -{% include [azure](./_includes/terraform/azure.md) %} - -## Создание инфраструктуры в Google Cloud Platform для развертывания {{ ydb-short-name }} кластера {#gcp-cluster} - -{% include [gcp](./_includes/terraform/gcp.md) %} - -## Создание инфраструктуры в Yandex Cloud для развертывания {{ ydb-short-name }} кластера {#yc-cluster} - -{% include [yc](./_includes/terraform/yc.md) %} - -С помощью Yandex Cloud провайдера можно не только создавать инфраструктуру для дальнейшего развертывания на ней YDB кластера с помощью [Ansible](./initial-deployment.md), но и управлять [serverless или dedicated](https://cloud.yandex.ru/ru/services/ydb) версией YDB прямо из Terraform. О возможностях работы с YDB в Yandex Cloud читайте в разделе [Работа с YDB через Terraform](https://cloud.yandex.ru/ru/docs/ydb/terraform/intro) документации Yandex Cloud. diff --git a/ydb/docs/ru/core/sre/ansible/toc_p.yaml b/ydb/docs/ru/core/sre/ansible/toc_p.yaml deleted file mode 100644 index 3d19c2b5986..00000000000 --- a/ydb/docs/ru/core/sre/ansible/toc_p.yaml +++ /dev/null @@ -1,7 +0,0 @@ -items: -- name: Обзор - href: index.md -- name: Изначальное развёртывание - href: initial-deployment.md -- name: Подготовка виртуальных машин с Terraform - href: preparing-vms-with-terraform.md
\ No newline at end of file diff --git a/ydb/docs/ru/core/toc_i.yaml b/ydb/docs/ru/core/toc_i.yaml index b1af84c30ce..80c59e4db51 100644 --- a/ydb/docs/ru/core/toc_i.yaml +++ b/ydb/docs/ru/core/toc_i.yaml @@ -11,29 +11,34 @@ items: include: mode: link path: devops/toc_p.yaml - -# Main -- { name: Практические руководства, include: { mode: link, path: operations/toc_p.yaml } } -- { name: Рекомендации, include: { mode: link, path: best_practices/toc_p.yaml } } -- { name: Управление базами данных, include: { mode: link, path: db/toc_p.yaml } } -- { name: Управление кластером, include: { mode: link, path: cluster/toc_p.yaml } } - +- name: Для DBA + include: + mode: link + path: dba/toc_p.yaml +- name: Для разработчиков + include: + mode: link + path: dev/toc_p.yaml +- name: Для контрибьюторов + include: + mode: link + path: contributor/toc_p.yaml - name: Справка include: mode: link path: reference/toc_p.yaml - -# Footer - name: Вопросы и ответы include: mode: link path: faq/toc_p.yaml -- name: Для контрибьюторов +- name: Загрузки include: mode: link - path: development/toc_p.yaml -- include: { mode: link, path: downloads/toc_p.yaml } + path: downloads/toc_p.yaml - name: Публичные материалы href: public-talks.md -- { name: Список изменений, include: { mode: link, path: toc_changelog.yaml } } +- name: Список изменений + include: + mode: link + path: toc_changelog.yaml diff --git a/ydb/docs/ru/core/troubleshooting/_includes/system_views/intro_cluster.md b/ydb/docs/ru/core/troubleshooting/_includes/system_views/intro_cluster.md deleted file mode 100644 index 6c9d4a4cdeb..00000000000 --- a/ydb/docs/ru/core/troubleshooting/_includes/system_views/intro_cluster.md +++ /dev/null @@ -1,5 +0,0 @@ -Для возможности внутренней интроспекции состояния кластера пользователю предоставляется возможность осуществлять запросы в специальные служебные таблицы (system views). Эти таблицы доступны из корневой директории кластера и используют системный префикс пути `.sys`. - -Пользователи облачных баз данных обычно не имеют доступа к системным таблицам кластера, так как за его поддержку и своевременную диагностику отвечает команда облака. - -В описаниях доступных полей далее по тексту колонка **Ключ** содержит индекс поля первичного ключа соответствующей таблицы. diff --git a/ydb/docs/ru/core/troubleshooting/_includes/system_views/intro_db.md b/ydb/docs/ru/core/troubleshooting/_includes/system_views/intro_db.md deleted file mode 100644 index 5e320902a04..00000000000 --- a/ydb/docs/ru/core/troubleshooting/_includes/system_views/intro_db.md +++ /dev/null @@ -1,14 +0,0 @@ -# Системные таблицы базы данных - -Вы можете отправлять запросы в специальные служебные таблицы (system views), чтобы следить за состоянием базы данных. Эти таблицы доступны из корня дерева базы данных и используют системный префикс пути `.sys`. - -Индекс поля первичного ключа соответствующей таблицы содержится в описаниях доступных полей далее по тексту. - -Системные таблицы содержат: - -* [Детальные данные об отдельных партициях таблиц БД](#partitions). -* [Топы запросов по определенным характеристикам](#top-queries). -* [Подробная информация о запросах](#query-metrics). -* [История перегруженных партиций](#top-overload-partitions). - -{% include [notes](notes.md) %} diff --git a/ydb/docs/ru/core/troubleshooting/_includes/system_views/notes.md b/ydb/docs/ru/core/troubleshooting/_includes/system_views/notes.md deleted file mode 100644 index bb8de470c00..00000000000 --- a/ydb/docs/ru/core/troubleshooting/_includes/system_views/notes.md +++ /dev/null @@ -1,5 +0,0 @@ -{% note info %} - -Обращение к системным таблицам имеет скорее аналитический характер нагрузки. Частое обращение к ним в больших базах будет существенно расходовать системные ресурсы. Рекомендуемая нагрузка не более 1-2 RPS. - -{% endnote %} diff --git a/ydb/docs/ru/core/troubleshooting/_includes/system_views/partitions.md b/ydb/docs/ru/core/troubleshooting/_includes/system_views/partitions.md deleted file mode 100644 index 513630b0684..00000000000 --- a/ydb/docs/ru/core/troubleshooting/_includes/system_views/partitions.md +++ /dev/null @@ -1,6 +0,0 @@ - -{% include [header.md](partitions_header.md) %} - -Примеры: - -{% include [example_yql](partitions_example_yql.md) %} diff --git a/ydb/docs/ru/core/troubleshooting/_includes/system_views/partitions_example_yql.md b/ydb/docs/ru/core/troubleshooting/_includes/system_views/partitions_example_yql.md deleted file mode 100644 index af8c100f86a..00000000000 --- a/ydb/docs/ru/core/troubleshooting/_includes/system_views/partitions_example_yql.md +++ /dev/null @@ -1,24 +0,0 @@ - Топ-5 самых загруженных партиций среди всех таблиц базы данных: - - > ```sql - > SELECT - > Path, - > PartIdx, - > CPUCores - > FROM `.sys/partition_stats` - > ORDER BY CPUCores DESC - > LIMIT 5 - > ``` - - Список таблиц базы с размерами и нагрузкой в моменте: - - > ```sql - > SELECT - > Path, - > COUNT(*) as Partitions, - > SUM(RowCount) as Rows, - > SUM(DataSize) as Size, - > SUM(CPUCores) as CPU - > FROM `.sys/partition_stats` - > GROUP BY Path - > ```
\ No newline at end of file diff --git a/ydb/docs/ru/core/troubleshooting/_includes/system_views/partitions_header.md b/ydb/docs/ru/core/troubleshooting/_includes/system_views/partitions_header.md deleted file mode 100644 index 1f653e5f1ca..00000000000 --- a/ydb/docs/ru/core/troubleshooting/_includes/system_views/partitions_header.md +++ /dev/null @@ -1,37 +0,0 @@ -## Партиции {#partitions} - -Следующая системная таблица хранит детализированную информацию об отдельных [партициях](../../../concepts/datamodel/table.md#partitioning) всех таблиц базы данных: - -* `partition_stats` — cодержит информацию о моментальных метриках и кумулятивные счетчики операций. К первым относятся, например, данные о нагрузке на CPU или количестве выполняемых [транзакций](../../../concepts/transactions.md). Ко вторым — общее количество прочитанных строк. - -Предназначена для выявления различных неравномерностей в нагрузке на партицию или отображения размера данных в ней. - -Кумулятивные поля (`RowReads`, `RowUpdates` и т.д.) хранят накопленные значения с момента последнего старта таблетки, обслуживающей партицию. - -Структура таблицы: - -Поле | Описание ---- | --- -`OwnerId` | Идентификатор SchemeShard, обслуживающего таблицу.<br>Тип: `Uint64`.<br>Ключ: `0`. -`PathId` | Идентификатор пути в SchemeShard.<br>Тип: `Uint64`.<br>Ключ: `1`. -`PartIdx` | Порядковый номер партиции.<br>Тип: `Uint64`.<br>Ключ: `2`. -`DataSize` | Приблизительный размер партиции в байтах.<br>Тип: `Uint64`. -`RowCount` | Приблизительное количество строк.<br>Тип: `Uint64`. -`IndexSize` | Размер индекса партиции в таблетке.<br>Тип: `Uint64`. -`CPUCores` | Double Моментальное значение нагрузки на партицию (доля ядра) -`TabletId` | Идентификатор таблетки, обслуживающей партицию.<br>Тип: `Uint64`. -`Path` | Полный путь к таблице.<br>Тип: `Utf8`. -`NodeId` | Идентификатор ноды, на которой в данный момент обслуживается партиция.<br>Тип: `Uint32`. -`StartTime` | Последний момент запуска таблетки, обслуживающей партицию.<br>Тип: `Timestamp`. -`AccessTime` | Последний момент чтения из партиции.<br>Тип: `Timestamp`. -`UpdateTime` | Последний момент записи в партицию.<br>Тип: `Timestamp`. -`RowReads` | Количество точечных чтений с момента старта таблетки партиции.<br>Тип: `Uint64`. -`RowUpdates` | Количество записанных строк с момента старта.<br>Тип: `Uint64`. -`RowDeletes` | Количество удалённых строк с момента старта.<br>Тип: `Uint64`. -`RangeReads` | Количество чтений диапазонов строк с момента старта.<br>Тип: `Uint64`. -`RangeReadRows` | Количество строк, прочитанных в диапазонах с момента старта.<br>Тип: `Uint64`. -`InFlightTxCount` | Количество транзакций, находящихся в процессе исполнения.<br>Тип: `Uint64`. -`ImmediateTxCompleted` | Количество завершившихся одношардовых транзакций с момента старта.<br>Тип: `Uint64`. -`CoordinatedTxCompleted` | Количество завершившихся координируемых транзакций с момента старта.<br>Тип: `Uint64`. -`TxRejectedByOverload` | Количество транзакций, отменённых по причине слишком высокой нагрузки (с момента старта).<br>Тип: `Uint64`. -`TxRejectedByOutOfStorage` | Количество транзакций, отменённых из-за нехватки места (с момента старта).<br>Тип: `Uint64`. diff --git a/ydb/docs/ru/core/troubleshooting/_includes/system_views/query_metrics.md b/ydb/docs/ru/core/troubleshooting/_includes/system_views/query_metrics.md deleted file mode 100644 index ffeef9ec25b..00000000000 --- a/ydb/docs/ru/core/troubleshooting/_includes/system_views/query_metrics.md +++ /dev/null @@ -1,6 +0,0 @@ - -{% include [header.md](query_metrics_header.md) %} - -Примеры: - -{% include [example_yql](query_metrics_example_yql.md) %}
\ No newline at end of file diff --git a/ydb/docs/ru/core/troubleshooting/_includes/system_views/query_metrics_example_yql.md b/ydb/docs/ru/core/troubleshooting/_includes/system_views/query_metrics_example_yql.md deleted file mode 100644 index 043c1029f2d..00000000000 --- a/ydb/docs/ru/core/troubleshooting/_includes/system_views/query_metrics_example_yql.md +++ /dev/null @@ -1,27 +0,0 @@ - Топ-10 запросов за последние 6 часов по общему количеству записанных строк в минутном интервале: - - > ```sql - > SELECT - > SumUpdateRows, - > Count, - > QueryText, - > IntervalEnd - > FROM `.sys/query_metrics_one_minute` - > ORDER BY SumUpdateRows DESC LIMIT 10 - > ``` - - Недавние запросы, прочитавшие больше всего байт за минуту: - - > ```sql - > SELECT - > IntervalEnd, - > SumReadBytes, - > MinReadBytes, - > SumReadBytes / Count as AvgReadBytes, - > MaxReadBytes, - > QueryText - > FROM `.sys/query_metrics_one_minute` - > WHERE SumReadBytes > 0 - > ORDER BY IntervalEnd DESC, SumReadBytes DESC - > LIMIT 100 - > ```
\ No newline at end of file diff --git a/ydb/docs/ru/core/troubleshooting/_includes/system_views/query_metrics_header.md b/ydb/docs/ru/core/troubleshooting/_includes/system_views/query_metrics_header.md deleted file mode 100644 index b78881d0165..00000000000 --- a/ydb/docs/ru/core/troubleshooting/_includes/system_views/query_metrics_header.md +++ /dev/null @@ -1,44 +0,0 @@ -## Подробная информация о запросах {#query-metrics} - -Следующая системная таблица хранит подробную информацию о запросах: - -* `query_metrics_one_minute` — данные разбиты по минутным интервалам, содержит до 256 запросов за последние 6 часов. - -Каждая строка таблицы содержит информацию о множестве случившихся за интервал запросов с одинаковым текстом. Поля таблицы предоставляют минимальное, максимальное и суммарное значение по каждой отслеживаемой характеристике запроса. В пределах интервала запросы отсортированы по убыванию суммарного потраченного процессорного времени. - -Ограничения: - -* текст запроса ограничен 4 килобайтами; -* статистика может быть неполной, если база испытывает сильную нагрузку. - -Структура таблицы: - -Поле | Описание ----|--- -`IntervalEnd` | Момент закрытия минутного интервала.<br>Тип: `Timestamp`.<br>Ключ: `0`. -`Rank` | Ранг запроса в пределах интервала (по полю SumCPUTime).<br>Тип: `Uint32`.<br>Ключ: `1`. -`QueryText` | Текст запроса.<br>Тип: `Utf8`. -`Count` | Количество запусков запроса.<br>Тип: `Uint64`. -`SumDuration` | Общая длительность запросов.<br>Тип: `Interval`. -`Count` | Количество запусков запроса.<br>Тип: `Uint64`. -`SumDuration` | Общая длительность запросов.<br>Тип: `Interval`. -`MinDuration` | Минимальная длительность запроса.<br>Тип: `Interval`. -`MaxDuration` | Максимальная длительность запроса.<br>Тип: `Interval`. -`SumCPUTime` | Общее затраченное процессорное время.<br>Тип: `Uint64`. -`MinCPUTime` | Минимальное затраченное процессорное время.<br>Тип: `Uint64`. -`MaxCPUTime` | Максимальное затраченное процессорное время.<br>Тип: `Uint64`. -`SumReadRows` | Общее количество прочитанных строк.<br>Тип: `Uint64`. -`MinReadRows` | Минимальное количество прочитанных строк.<br>Тип: `Uint64`. -`MaxReadRows` | Максимальное количество прочитанных строк.<br>Тип: `Uint64`. -`SumReadBytes` | Общее количество прочитанных байт.<br>Тип: `Uint64`. -`MinReadBytes` | Минимальное количество прочитанных байт.<br>Тип: `Uint64`. -`MaxReadBytes` | Максимальное количество прочитанных байт.<br>Тип: `Uint64`. -`SumUpdateRows` | Общее количество записанных строк.<br>Тип: `Uint64`. -`MinUpdateRows` | Минимальное количество записанных строк.<br>Тип: `Uint64`. -`MaxUpdateRows` | Максимальное количество записанных строк.<br>Тип: `Uint64`. -`SumUpdateBytes` | Общее количество записанных байт.<br>Тип: `Uint64`. -`MinUpdateBytes` | Минимальное количество записанных байт.<br>Тип: `Uint64`. -`MaxUpdateBytes` | Максимальное количество записанных байт.<br>Тип: `Uint64`. -`SumDeleteRows` | Общее количество удалённых строк.<br>Тип: `Uint64`. -`MinDeleteRows` | Минимальное количество удалённых строк.<br>Тип: `Uint64`. -`MaxDeleteRows` | Максимальное количество удалённых строк.<br>Тип: `Uint64`. diff --git a/ydb/docs/ru/core/troubleshooting/_includes/system_views/top-overload-partitions.md b/ydb/docs/ru/core/troubleshooting/_includes/system_views/top-overload-partitions.md deleted file mode 100644 index 0772eee6a1a..00000000000 --- a/ydb/docs/ru/core/troubleshooting/_includes/system_views/top-overload-partitions.md +++ /dev/null @@ -1,60 +0,0 @@ -## История перегруженных партиций {#top-overload-partitions} - -Следующие системные таблицы хранят историю моментов высокой нагрузки на отдельные партиции таблиц БД: - -* `top_partitions_one_minute` — данные разбиты на минутные интервалы, содержит историю за последние 6 часов; -* `top_partitions_one_hour` — данные разбиты на часовые интервалы, содержит историю за последние 2 недели. - -В таблицы попадают партиции с пиковой нагрузкой более 70 % (`CPUCores` > 0,7). В пределах одного интервала партиции ранжированы по пиковому значению нагрузки. - -Обе таблицы содержат одинаковый набор полей: - -Поле | Описание ---- | --- -`IntervalEnd` | Момент закрытия минутного или часового интервала.<br>Тип: `Timestamp`.<br>Ключ: `0`. -`Rank` | Ранг партиции в пределах интервала (по CPUCores).<br>Тип: `Uint32`.<br>Ключ: `1`. -`TabletId` | Идентификатор таблетки, обслуживающей партицию.<br>Тип: `Uint64`. -`Path` | Полный путь к таблице.<br>Тип: `Utf8`. -`PeakTime` | Момент пикового значения в пределах интервала.<br>Тип: `Timestamp`. -`CPUCores` | Пиковое значение нагрузки на партицию (доля ядра).<br>Тип: `Double`. -`NodeId` | Идентификатор ноды, на которой находилась партиция в момент пика.<br>Тип: `Uint32`. -`DataSize` | Приблизительный размер партиции в байтах в момент пика.<br>Тип: `Uint64`. -`RowCount` | Приблизительное количество строк в момент пика.<br>Тип: `Uint64`. -`IndexSize` | Размер индекса партиции в таблетке в момент пика.<br>Тип: `Uint64`. -`InFlightTxCount` | Количество транзакций, находящихся в процессе исполнения в момент пика.<br>Тип: `Uint32`. - -Примеры: - -Следующий запрос выводит партиции с потреблением CPU более 70% в указанном интервале времени, с идентификаторами таблеток и их размерами на момент превышения. Запрос выполняется к таблице `.sys/top_partitions_one_minute`, которая содержит данные за последние 6 часов с разбиением по часовым интервалам: - ->```yql ->SELECT -> IntervalEnd, -> CPUCores, -> Path, -> TabletId, -> DataSize ->FROM `.sys/top_partitions_one_minute` ->WHERE CPUCores > 0.7 ->AND IntervalEnd BETWEEN Timestamp("YYYY-MM-DDThh:mm:ss.uuuuuuZ") AND Timestamp("YYYY-MM-DDThh:mm:ss.uuuuuuZ") ->ORDER BY IntervalEnd desc, CPUCores desc ->``` - -* `"YYYY-MM-DDTHH:MM:SS.UUUUUUZ"` — время в зоне UTC 0 (`YYYY` — год, `MM` — месяц, `DD` — число, `hh` — часы, `mm` — минуты, `ss` — секунды, `uuuuuu` — микросекунды). Например, `"2023-01-26T13:00:00.000000Z"`. - -Следующий запрос выводит партиции с потреблением CPU более 90% в указанном интервале времени, с идентификаторами таблеток и их размерами на момент превышения. Запрос выполняется к таблице `.sys/top_partitions_one_hour`, которая содержит данные за последние 2 недели с разбиением по минутным интервалам: - ->```yql ->SELECT -> IntervalEnd, -> CPUCores, -> Path, -> TabletId, -> DataSize ->FROM `.sys/top_partitions_one_hour` ->WHERE CPUCores > 0.9 ->AND IntervalEnd BETWEEN Timestamp("YYYY-MM-DDThh:mm:ss.uuuuuuZ") AND Timestamp("YYYY-MM-DDThh:mm:ss.uuuuuuZ") ->ORDER BY IntervalEnd desc, CPUCores desc ->``` - -* `"YYYY-MM-DDTHH:MM:SS.UUUUUUZ"` — время в зоне UTC 0 (`YYYY` — год, `MM` — месяц, `DD` — число, `hh` — часы, `mm` — минуты, `ss` — секунды, `uuuuuu` — микросекунды). Например, `"2023-01-26T13:00:00.000000Z"`. diff --git a/ydb/docs/ru/core/troubleshooting/_includes/system_views/tops.md b/ydb/docs/ru/core/troubleshooting/_includes/system_views/tops.md deleted file mode 100644 index f5fedd8fd4d..00000000000 --- a/ydb/docs/ru/core/troubleshooting/_includes/system_views/tops.md +++ /dev/null @@ -1,6 +0,0 @@ - -{% include [header.md](tops_header.md) %} - -Примеры: - -{% include [example_yql.md](tops_example_yql.md) %} diff --git a/ydb/docs/ru/core/troubleshooting/_includes/system_views/tops_example_yql.md b/ydb/docs/ru/core/troubleshooting/_includes/system_views/tops_example_yql.md deleted file mode 100644 index ba6c6dd68ee..00000000000 --- a/ydb/docs/ru/core/troubleshooting/_includes/system_views/tops_example_yql.md +++ /dev/null @@ -1,30 +0,0 @@ - Топ запросов по времени выполнения за последнюю минуту их отправки: - - > ```sql - > PRAGMA AnsiInForEmptyOrNullableItemsCollections; - > $last = ( - > SELECT - > MAX(IntervalEnd) - > FROM `.sys/top_queries_by_duration_one_minute` - > ); - > SELECT - > IntervalEnd, - > Rank, - > QueryText, - > Duration - > FROM `.sys/top_queries_by_duration_one_minute` - > WHERE IntervalEnd IN $last - > ``` - - Запросы, прочитавшие больше всего байт, в разбивке по минутам: - - > ```sql - > SELECT - > IntervalEnd, - > QueryText, - > ReadBytes, - > ReadRows, - > Partitions - > FROM `.sys/top_queries_by_read_bytes_one_minute` - > WHERE Rank = 1 - > ```
\ No newline at end of file diff --git a/ydb/docs/ru/core/troubleshooting/_includes/system_views/tops_header.md b/ydb/docs/ru/core/troubleshooting/_includes/system_views/tops_header.md deleted file mode 100644 index d4ed4f2fe35..00000000000 --- a/ydb/docs/ru/core/troubleshooting/_includes/system_views/tops_header.md +++ /dev/null @@ -1,49 +0,0 @@ -## Топы запросов {#top-queries} - -Следующие системные таблицы хранят данные для анализа потока пользовательских запросов: - -* `top_queries_by_duration_one_minute` — данные разбиты на минутные интервалы, содержит топ-5 запросов с наибольшим полным временем исполнения за последние 6 часов; -* `top_queries_by_duration_one_hour` — данные разбиты на часовые интервалы, содержит топ-5 запросов с наибольшим полным временем исполнения за последние 2 недели; -* `top_queries_by_read_bytes_one_minute` — данные разбиты на минутные интервалы, содержит топ-5 запросов с наибольшим количеством прочитанных из таблицы байт за последние 6 часов; -* `top_queries_by_read_bytes_one_hour` — данные разбиты на часовые интервалы, содержит топ-5 запросов с наибольшим количеством прочитанных из таблицы байт за последние 2 недели; -* `top_queries_by_cpu_time_one_minute` — данные разбиты на минутные интервалы, содержит топ-5 запросов с наибольшим затраченным процессорным временем за последние 6 часов; -* ` top_queries_by_cpu_time_one_hour` — данные разбиты на часовые интервалы, содержит топ-5 запросов с наибольшим затраченным процессорным временем за последние 2 недели. - -Различные запуски запроса с одним и тем же текстом дедуплицируются. Топ содержит информацию о конкретном запуске с максимальным значением соответствующей характеристики запроса в пределах одного временного интервала. - -Поля, предоставляющие информацию о затраченном процессорном времени (...`CPUTime`), выражены в микросекундах. - -Текст запроса ограничен 4 килобайтами. - -Все таблицы содержат одинаковый набор полей: - -Поле | Описание ---- | --- -`IntervalEnd` | Момент закрытия минутного или часового интервала.<br>Тип: `Timestamp`.<br>Ключ: `0`. -`Rank` | Ранг запроса в топе.<br>Тип: `Uint32`.<br>Ключ: `1`. -`QueryText` | Текст запроса.<br>Тип: `Utf8`. -`Duration` | Полное время исполнения запроса.<br>Тип: `Interval`. -`EndTime` | Момент окончания исполнения запроса. <br>Тип: `Timestamp`. -`Type` | Тип запроса ("data", "scan", "script").<br>Тип: `String`. -`ReadRows` | Количество прочитанных строк.<br>Тип: `Uint64`. -`ReadBytes` | Количество прочитанных байт.<br>Тип: `Uint64`. -`UpdateRows` | Количество записанных строк.<br>Тип: `Uint64`. -`UpdateBytes` | Количество записанных байт.<br>Тип: `Uint64`. -`DeleteRows` | Количество удалённых строк.<br>Тип: `Uint64`. -`DeleteBytes` | Количество удалённых байт.<br>Тип: `Uint64`. -`Partitions` | Количество партиций таблиц, участвовавших в исполнении запроса.<br>Тип: `Uint64`. -`UserSID` | Security ID пользователя.<br>Тип: `String`. -`ParametersSize` | Размер параметров запроса в байтах.<br>Тип: `Uint64`. -`CompileDuration` | Длительность компиляции запроса.<br>Тип: `Interval`. -`FromQueryCache` | Использовался ли кэш подготовленных запросов.<br>Тип: `Bool`. -`CPUTime` | Общее процессорное время, использованное для исполнения запроса (микросекунды).<br>Тип: `Uint64`. -`ShardCount` | Количество шардов, участвующих в исполнении запроса.<br>Тип: `Uint64`. -`SumShardCPUTime` | Общее процессорное время, затраченное в шардах.<br>Тип: `Uint64`. -`MinShardCPUTime` | Минимальное процесорное время, затраченное в шардах.<br>Тип: `Uint64`. -`MaxShardCPUTime` | Максимальное процессорное время, затраченное в шардах.<br>Тип: `Uint64`. -`ComputeNodesCount` | Количество вычислительных нод, задействованных в исполнении запроса.<br>Тип: `Uint64`. -`SumComputeCPUTime` | Общее процессорное время, затраченное в вычислительных нодах.<br>Тип: `Uint64`. -`MinComputeCPUTime` | Минимальное процессорное время, затраченное в вычислительных нодах.<br>Тип: `Uint64`. -`MaxComputeCPUTime` | Максимальное процессорное время, затраченное в вычислительных нодах.<br>Тип: `Uint64`. -`CompileCPUTime` | Процессорное время, затраченное на компиляцию запроса.<br>Тип: `Uint64`. -`ProcessCPUTime` | Процессорное время, затраченное на общую обработку запроса.<br>Тип: `Uint64`. diff --git a/ydb/docs/ru/core/troubleshooting/index.md b/ydb/docs/ru/core/troubleshooting/index.md deleted file mode 100644 index 81a913a87e1..00000000000 --- a/ydb/docs/ru/core/troubleshooting/index.md +++ /dev/null @@ -1,7 +0,0 @@ -# Диагностика - -В данном разделе собраны статьи по инструментам диагностики баз данных YDB. - -- [Системные таблицы](system_views_db.md) -- [Метрики](monitoring.md) -- [Дашборды Grafana](../administration/grafana-dashboards.md) diff --git a/ydb/docs/ru/core/troubleshooting/monitoring.md b/ydb/docs/ru/core/troubleshooting/monitoring.md deleted file mode 100644 index 3204845af8a..00000000000 --- a/ydb/docs/ru/core/troubleshooting/monitoring.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -editable: false ---- - -# Справочник метрик - -{% include notitle [ydb_monitoring_sensors.md](_includes/monitoring_sensors.md) %} diff --git a/ydb/docs/ru/core/troubleshooting/system_views.md b/ydb/docs/ru/core/troubleshooting/system_views.md deleted file mode 100644 index 72b417be784..00000000000 --- a/ydb/docs/ru/core/troubleshooting/system_views.md +++ /dev/null @@ -1,7 +0,0 @@ -# Системные таблицы - -Информация по системным таблицам доступна в следующих статьях: - -- [Системные таблицы базы данных](system_views_db.md) -- [Системные таблицы кластера](system_views_cluster.md) - diff --git a/ydb/docs/ru/core/troubleshooting/system_views_cluster.md b/ydb/docs/ru/core/troubleshooting/system_views_cluster.md deleted file mode 100644 index d9700500622..00000000000 --- a/ydb/docs/ru/core/troubleshooting/system_views_cluster.md +++ /dev/null @@ -1,7 +0,0 @@ -# Системные таблицы кластера - -{% include [intro.md](_includes/system_views/intro_cluster.md) %} - -{% include [distributed_storage.md](_includes/system_views/distributed_storage.md) %} - -{% include [notes.md](_includes/system_views/notes.md) %} diff --git a/ydb/docs/ru/core/troubleshooting/system_views_db.md b/ydb/docs/ru/core/troubleshooting/system_views_db.md deleted file mode 100644 index 0c8c26a7590..00000000000 --- a/ydb/docs/ru/core/troubleshooting/system_views_db.md +++ /dev/null @@ -1,9 +0,0 @@ -{% include [intro.md](_includes/system_views/intro_db.md) %} - -{% include [partitions.md](_includes/system_views/partitions.md) %} - -{% include [tops.md](_includes/system_views/tops.md) %} - -{% include [query_metrics.md](_includes/system_views/query_metrics.md) %} - -{% include [top-overload-partitions.md](_includes/system_views/top-overload-partitions.md) %} diff --git a/ydb/docs/ru/core/troubleshooting/toc_i.yaml b/ydb/docs/ru/core/troubleshooting/toc_i.yaml deleted file mode 100644 index 1557851b33b..00000000000 --- a/ydb/docs/ru/core/troubleshooting/toc_i.yaml +++ /dev/null @@ -1,9 +0,0 @@ -items: -- name: Системные таблицы - href: system_views_db.md -- name: Мониторинг - href: monitoring.md -- name: System views (deprecated) - href: system_views.md - hidden: true -
\ No newline at end of file diff --git a/ydb/docs/ru/core/troubleshooting/toc_p.yaml b/ydb/docs/ru/core/troubleshooting/toc_p.yaml deleted file mode 100644 index 3e62ad228bc..00000000000 --- a/ydb/docs/ru/core/troubleshooting/toc_p.yaml +++ /dev/null @@ -1,4 +0,0 @@ -items: -- name: Обзор - href: index.md -- include: { mode: link, path: toc_i.yaml }
\ No newline at end of file diff --git a/ydb/docs/ru/core/yql/query_plans.md b/ydb/docs/ru/core/yql/query_plans.md index 1c22e2b7b27..ffdf7459013 100644 --- a/ydb/docs/ru/core/yql/query_plans.md +++ b/ydb/docs/ru/core/yql/query_plans.md @@ -3,7 +3,7 @@ Чтобы лучше понимать работу запроса, вы можете получить и проанализировать его план. Структура плана запроса в {{ ydb-short-name }} представляет собой граф, где каждый узел содержит информацию об операциях и таблицах. -Ниже представлена справочная информация по типам узлов, а пример анализа конкретного плана запроса можно посмотреть [здесь](../operations/query_plans_optimization.md). +Ниже представлена справочная информация по типам узлов, а пример анализа конкретного плана запроса можно посмотреть [здесь](../dba/query-plans-optimization.md). ## Типы узлов ### Stage |
