From f5547cba2669ba55f749ae9485fd7feeb8028b56 Mon Sep 17 00:00:00 2001 From: Evgenii Guguchkin Date: Tue, 9 Sep 2025 13:10:14 +0300 Subject: [PATCH] docs: translate architecture docs to russian --- docs/en/13-architecture.md | 2 +- docs/ru/13-architecture.md | 163 +++++++++++++++++-------------------- 2 files changed, 74 insertions(+), 91 deletions(-) diff --git a/docs/en/13-architecture.md b/docs/en/13-architecture.md index cd59e81b..37967c2b 100644 --- a/docs/en/13-architecture.md +++ b/docs/en/13-architecture.md @@ -156,5 +156,5 @@ That is, if a write operation succeeds on a replica of a shard and fails on anot would be out of sync and won't be (automatically) synced. The only given guarantee is that a write operation will succeed only having at least RF replicas saved on disk. This optimization allows seq-db to have a higher than alternatives ingestion throughput -with the obvious price of the possible inconsistencies of retrieval and aggregation queries. +with the obvious price of the possible inconsistencies of histogram and aggregation queries. seq-db was designed as a database for logs/traces with this tradeoff in mind. \ No newline at end of file diff --git a/docs/ru/13-architecture.md b/docs/ru/13-architecture.md index cd59e81b..dc6fa7df 100644 --- a/docs/ru/13-architecture.md +++ b/docs/ru/13-architecture.md @@ -1,75 +1,61 @@ -# Cluster-Mode Architecture +# Архитектура кластерного режима -## Components overview +## Обзор компонентов -In cluster mode, seq-db consists of two main components: - - seq-db store (seq-db instance running with `--mode=store flag`) - - seq-db proxy (seq-db instance running with `--mode=proxy flag`). +В кластерном режиме seq-db состоит из двух основных компонентов: +- seq-db store (экземпляр seq-db, запущенный с флагом `--mode=store`) +- seq-db proxy (экземпляр seq-db, запущенный с флагом `--mode=proxy`). ### seq-db store -seq-db store is the stateful storage component, that keeps all the -written documents and handles both reads and writes. -All data written into seq-db eventually makes its way to one or multiple stores. +seq-db store — это stateful-компонент, который хранит все записанные документы и обрабатывает как чтение, так и запись. +Все данные, записанные в seq-db, в конечном итоге попадают в один или несколько store'ов. +#### Ключевые характеристики +- Развертывается как k8s `Statefulset` +- Архитектура без общего состояния (share-nothing): экземпляр seq-db store не знает о других store'ах. +- Поддерживает обратный индекс в памяти и на диске, что позволяет осуществлять поиск по индексированным полям. -#### Key characteristics -- Deployed as k8s `Statefulset` -- Share-nothing architecture: a seq-db store instance is unaware of any other stores. -- Maintains in-memory and on-disk inverted indexes, allowing search on indexed fields. +#### Структура файлов +seq-db store хранит все данные документов в трех типах файлов: +| Тип файла | Назначение | +|-----------|--------------------------------------------------------| +| `.docs` | Хранит сжатые батчи сырых документов логов | +| `.meta` | Токенизированный поток метаданных (для восстановления) | +| `.index` | Дисковый обратный индекс. | -#### File layout -seq-db store keeps all document data in three file types: +Поскольку набор данных хранится в этих трех типах файлов, перемещение или восстановление шарда выполняется просто: достаточно скопировать (`cp` / `rsync`) директорию на целевой узел и запустить под. -| File type | Purpose | -|-----------|------------------------------------------------| -| `.docs` | Stores compressed batches of raw log documents | -| `.meta` | Tokenized metadata stream (used for recovery) | -| `.index` | On-disk inverted index | +Подробнее о типах файлов и их внутренней структуре читайте [здесь](internal/fractions.md). - -Because the dataset is stored in these three file types, moving or restoring a -shard is straightforward: simply `cp` / `rsync` the directory -to the target node and start the pod. - -Read more about file types and their internal structure [here](internal/fractions.md). - -#### Durability -A write operation is acknowledged only after the payload is safely persisted: +#### Durability (обеспечение надежности) +Операция записи подтверждается только после того, как полезная нагрузка гарантированно сохранена: ``` -write, fsync # .meta file -write, fsync # .data file +write, fsync # файл .meta +write, fsync # файл .data ``` -That is, two write system calls followed by two fsync -calls—guaranteeing the data survives a node -crash or restart before the client receives a success response. -Indexing occurs asynchronously, so it usually takes under 1 -second before the newly written documents are available for search queries. -Note that this value may be slightly higher when bulk load spikes happen +То есть, два системных вызова `write`, за которыми следуют два вызова `fsync` — это гарантирует, что данные переживут аварию узла или его перезапуск до того, как клиент получит ответ об успехе. +Индексация происходит асинхронно, поэтому обычно проходит менее 1 секунды, прежде чем вновь записанные документы становятся доступны для поисковых запросов. +Примечание: это значение может быть немного выше в периоды пиковой нагрузки. ### seq-db proxy -seq-db proxy is a stateless coordinator for all read & write traffic. -It maintans a user-defined cluster topology, and allows changes in read-write -traffic distribution without changes to the stateful components +seq-db proxy — это stateless-координатор всего трафика чтения и записи. +Он поддерживает заданную пользователем топологию кластера и позволяет изменять распределение read-write трафика без изменений stateful-компонентов. +#### Ключевые характеристики +- Развертывается как k8s `Deployment` +- Выполняет логическую репликацию между store'ами +- Маршрутизирует трафик между уровнями хранения (hot/cold stores) -#### Key characteristics -- Deployed as k8s `Deployment` -- Performs logical replication between stores -- Routes traffic between storage tiers (hot/cold stores) +seq-db proxy токенизирует каждый входящий документ и сжимает батчи с помощью zstd / lz4 перед отправкой батчей в seq-db stores. -seq-db proxy tokenizes every incoming document -and compresses batches with zstd / lz4 -before sending batches to seq-db stores. +### Read-path & write-path (коэффициент репликации rf=2) +Давайте рассмотрим пример архитектуры с 4 шардами seq-db и коэффициентом репликации (replication-factor)=2 (каждый лог должен храниться в двух отдельных seq-db stores). +Обратите внимание, что реплики шарда могут располагаться в разных зонах доступности (availability zones). -### Read-path & write-path (rf=2) -Let's take a look at an example architecture with 4 seq-db shards and replication-factor=2 -(each log must be stored in two separate seq-db stores). -Note that replicas of shard can be located in different availability zones. - -### Write-path -The write commits only after seq-db proxy receives an ack **from all replicas of the addressed shard**. +### Write-path (путь записи) +Запись фиксируется (commit) только после того, как seq-db proxy получает подтверждение (ack) **от всех реплик целевого шарда**. ```mermaid sequenceDiagram @@ -78,16 +64,16 @@ sequenceDiagram participant Proxy as seq-db proxy box Shard1 - participant A as seq-db store
shard1 replica A - participant B as seq-db store
shard1 replica B + participant A as seq-db store
шард1 реплика A + participant B as seq-db store
шард1 реплика B end box Shard2 - participant C as seq-db store
shard2 replica A - participant D as seq-db store
shard2 replica B + participant C as seq-db store
шард2 реплика A + participant D as seq-db store
шард2 реплика B end - Note over Proxy,B: seq-db proxy chooses a random shard + Note over Proxy,B: seq-db proxy выбирает случайный шард Client->>Proxy: write(batch1) Proxy->>A: write(batch1) Proxy->>B: write(batch1) @@ -96,7 +82,7 @@ sequenceDiagram B-->>Proxy: ack Proxy-->>Client: ack - Note over Proxy,B: the write is done if acks received
from both replicas of a shard + Note over Proxy,B: запись завершена, если подтверждения получены
от обеих реплик шарда Client->>Proxy: write(batch2) Proxy->>C: write(batch2) @@ -108,10 +94,8 @@ sequenceDiagram Proxy-->>Client: ack ``` -### Read-path -While the written document must be acknowledged by all replicas -of a shard, -a read is successful when **at least one replica of each shard** returns a response. +### Read-path (путь чтения) +В то время как записанный документ должен быть подтвержден всеми репликами шарда, чтение считается успешным, когда **хотя бы одна реплика каждого шарда** возвращает ответ. ```mermaid sequenceDiagram @@ -120,41 +104,40 @@ sequenceDiagram participant Proxy as seq-db proxy box Shard1 - participant A as seq-db store
shard1 replica A - participant B as seq-db store
shard1 replica B + participant A as seq-db store
шард1 реплика A + participant B as seq-db store
шард1 реплика B end box Shard2 - participant C as seq-db store
shard2 replica A - participant D as seq-db store
shard2 replica B + participant C as seq-db store
шард2 реплика A + participant D as seq-db store
шард2 реплика B end - Note over Proxy,C: seq-db proxy chooses
a random replica of each shard - Client->>Proxy: request 1 - Proxy->>A: request 1 - Proxy->>C: request 1 + Note over Proxy,C: seq-db proxy выбирает
случайную реплику каждого шарда + Client->>Proxy: запрос 1 + Proxy->>A: запрос 1 + Proxy->>C: запрос 1 - A-->>Proxy: response 1 (shard1 replica A) - C-->>Proxy: response 1 (shard2 replica A) - Note over Proxy: seq-db proxy merges the returned responses - Proxy-->>Client: merge(res1_s1rA, res1_s2rA) + A-->>Proxy: ответ 1 (шард1 реплика A) + C-->>Proxy: ответ 1 (шард2 реплика A) + Note over Proxy: seq-db proxy объединяет (merge) полученные ответы + Proxy-->>Client: merge(ответ1_ш1рA, ответ1_ш2рA) + Client->>Proxy: запрос 2 + Proxy->>B: запрос 2 + Proxy->>D: запрос 2 - Client->>Proxy: request 2 - Proxy->>B: request 2 - Proxy->>D: request 2 - - B-->>Proxy: response 2 (shard1 replica B) - D-->>Proxy: response 2 (shard2 replica B) + B-->>Proxy: ответ 2 (шард1 реплика B) + D-->>Proxy: ответ 2 (шард2 реплика B) - Proxy-->>Client: merge(res2_s1rB, res2_s2rB) + Proxy-->>Client: merge(ответ2_ш1рB, ответ2_ш2рB) ``` -## Notes about replication & consistency -seq-db doesn't have any mechanism to keep replicas consistent between each other. -That is, if a write operation succeeds on a replica of a shard and fails on another replica, the replicas -would be out of sync and won't be (automatically) synced. -The only given guarantee is that a write operation will succeed only having at least RF replicas saved on disk. -This optimization allows seq-db to have a higher than alternatives ingestion throughput -with the obvious price of the possible inconsistencies of retrieval and aggregation queries. -seq-db was designed as a database for logs/traces with this tradeoff in mind. \ No newline at end of file +## Примечания о репликации и согласованности (consistency) +seq-db не имеет каких-либо механизмов для поддержания согласованности реплик между собой. +То есть, если операция записи завершилась успешно на одной реплике шарда и завершилась ошибкой на другой, реплики окажутся +в рассогласованном состоянии и не будут автоматически синхронизированы. Единственная предоставляемая гарантия +заключается в том, что операция записи завершится успехом, только если как минимум RF реплик сохранили данные на диск. +Эта оптимизация позволяет seq-db иметь более высокую пропускную способность приема данных по сравнению с аналогами, +за очевидную цену — возможной несогласованности результатов запросов на получение гистограмм и агрегации. +seq-db был разработан как база данных для логов/трейсов с учетом этого компромисса. \ No newline at end of file