This is an automated email from the ASF dual-hosted git repository.
weichiu pushed a commit to branch HDDS-9225-website-v2
in repository https://gitbox.apache.org/repos/asf/ozone-site.git
The following commit(s) were added to refs/heads/HDDS-9225-website-v2 by this
push:
new 10ab692df HDDS-14458. [Website v2] [Docs] [Core Concepts] Recon (#274)
10ab692df is described below
commit 10ab692dfab2af9f810dabf0ccac72a5d0f9c56e
Author: Gargi Jaiswal <[email protected]>
AuthorDate: Fri Jan 23 13:00:36 2026 +0530
HDDS-14458. [Website v2] [Docs] [Core Concepts] Recon (#274)
---
cspell.yaml | 4 +
docs/03-core-concepts/01-architecture/06-recon.md | 105 +++++++++++++++++++++
.../01-architecture/ReconHighLevelDesign.png | Bin 0 -> 239168 bytes
.../01-architecture/ReconOmDesign.png | Bin 0 -> 162797 bytes
.../01-architecture/ReconScmDesign.png | Bin 0 -> 181628 bytes
5 files changed, 109 insertions(+)
diff --git a/cspell.yaml b/cspell.yaml
index 94bc41447..ed36f5d7b 100644
--- a/cspell.yaml
+++ b/cspell.yaml
@@ -180,6 +180,10 @@ words:
- checksummed
- ISA
- doublebuffer
+- untars
+- jdbc
+- JDBC
+- MIS
- defragged
# Company names for "Who Uses Ozone" page
- Shopee
diff --git a/docs/03-core-concepts/01-architecture/06-recon.md
b/docs/03-core-concepts/01-architecture/06-recon.md
new file mode 100644
index 000000000..dedb7b6dc
--- /dev/null
+++ b/docs/03-core-concepts/01-architecture/06-recon.md
@@ -0,0 +1,105 @@
+---
+sidebar_label: Recon
+---
+
+# Recon
+
+Recon serves as a management and monitoring console for Ozone. It gives a
bird's-eye view of Ozone and helps users troubleshoot any issues by presenting
the current state of the cluster through REST based APIs and rich web UI.
+
+## High Level Design
+
+
+
+On a high level, Recon collects and aggregates metadata from Ozone Manager
(OM), Storage Container Manager (SCM) and Datanodes (DN) and acts as a central
management and monitoring console. Ozone administrators can use Recon to query
the current state of the system without overloading OM or SCM.
+
+Recon maintains multiple databases to enable batch processing, faster querying
and to persist aggregate information. It maintains a local copy of OM db and
SCM db along with a SQL database for persisting aggregate information.
+
+Recon also integrates with Prometheus to provide a HTTP endpoint to query
Prometheus for Ozone metrics and also to display a few crucial point in time
metrics in the web UI.
+
+## Recon and Ozone Manager
+
+
+
+Recon gets a full snapshot of OM rocks db initially from the leader OM's HTTP
endpoint, untars the file and initializes RocksDB for querying locally. The
database is kept in sync by periodically requesting delta updates from the
leader OM via RPC calls from the last applied sequence id. If for any reason,
the delta updates could not be retrieved or applied to the local db, a full
snapshot is requested again to keep the local db in sync with OM db. Due to
this, Recon can show stale inform [...]
+
+The db updates retrieved from OM is then converted into a batch of events for
further processing by OM db tasks via [Recon Task Framework](#task-framework).
+
+## Recon and Storage Container Manager
+
+
+
+Recon also acts as a passive SCM for Datanodes. When Recon is configured in
the cluster, all the Datanodes register with Recon and send heartbeats,
container reports, incremental container reports etc. to Recon similar to SCM.
Recon uses all the information it gets from Datanodes to construct its own copy
of SCM rocks db locally. Recon never sends any command to Datanodes in response
and just acts as a passive SCM for faster lookup of SCM metadata.
+
+## Task Framework
+
+Recon has its own Task framework to enable batch processing of data obtained
from OM and SCM. A task can listen to and act upon db events such as `PUT`,
`DELETE`, `UPDATE`, etc. on either OM db or SCM db. Based on this, a task
either implements `org.apache.hadoop.ozone.recon.tasks.ReconOmTask` or extends
`org.apache.hadoop.ozone.recon.scm.ReconScmTask`.
+
+An example `ReconOmTask` is `ContainerKeyMapperTask` that persists the
container -> key mapping in RocksDB. This is useful to understand which keys
were part
+of the container when the container is reported missing or is in a bad health
state. Another example is FileSizeCountTask which keeps track of count of
+files within a given file size range in a SQL database. These tasks have
implementations for two scenarios:
+
+- Full snapshot (`reprocess()`)
+- Delta updates (`process()`)
+
+When a full snapshot of OM db is obtained from the leader OM, the
`reprocess()` is called on all the registered OM tasks. On subsequent delta
updates, `process()` is called on these OM tasks.
+
+An example `ReconScmTask` is `ContainerHealthTask` that runs in configurable
intervals to scan the list of all the containers and to persist the state of
unhealthy containers (`MISSING`, `MIS_REPLICATED`, `UNDER_REPLICATED`,
`OVER_REPLICATED`) in a SQL table. This information is used to determine if
there are any missing containers in the cluster.
+
+## Recon and Prometheus
+
+Recon can integrate with any Prometheus instance configured to collected
metrics and can display useful information in Recon UI in Datanodes and
Pipelines pages. Recon also exposes a proxy endpoint
+([/metrics](https://ozone.apache.org/docs/edge/interface/reconapi.html#metrics))
to query Prometheus. This integration can be enabled by setting this
configuration `ozone.recon.prometheus.http.endpoint` to the Prometheus endpoint
like `ozone.recon.prometheus.http.endpoint=http://prometheus:9090`.
+
+## API Reference
+
+[Link to complete API
Reference](../../05-administrator-guide/03-operations/09-observability/02-recon/02-recon-rest-api.md)
+
+## Persisted state
+
+- A local copy of [OM database](./02-ozone-manager.md#persisted-state)
+- A local copy of [SCM
database](./03-storage-container-manager.md#persisted-state)
+
+The following data is persisted in Recon in the specified RocksDB directory:
+
+- **ContainerKey table**
+ - Stores the mapping (container, key) -> count
+- **ContainerKeyCount table**
+ - Stores containerID -> no. of keys count within the container
+
+The following data is stored in the configured SQL database (**default is
Derby**):
+
+- **GlobalStats table**
+ - A Key -> Value table to store aggregate information like total number of
volumes / buckets / keys present in the cluster
+- **FileCountBySize table**
+ - Keeps track of the number of files present within a file size range in the
cluster
+- **ReconTaskStatus table**
+ - Keeps track of the status and last run timestamp of the registered OM and
SCM db tasks in the [Recon Task Framework](#task-framework)
+- **ContainerHistory table**
+ - Stores ContainerReplica -> Datanode mapping with last known timestamp.
This is used to determine the last known Datanodes when a container is reported
missing
+- **UnhealthyContainers table**
+ - Keeps track of all the Unhealthy Containers (MISSING, UNDER_REPLICATED,
OVER_REPLICATED, MIS_REPLICATED) in the cluster at any given time
+
+## Notable configurations
+
+| Key | Default
| Description
|
+|-----|------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
+| `ozone.recon.http-address` | 0.0.0.0:9888
| The address and the base port where the Recon
web UI will listen on.
|
+| `ozone.recon.address` | 0.0.0.0:9891
| RPC address of the Recon.
|
+| `ozone.recon.heatmap.provider` | none
| HeatMapProvider for Recon.
|
+| `ozone.recon.db.dir` | none
| Directory where the Recon Server stores its metadata.
|
+| `ozone.recon.om.db.dir` | none
| Directory where the Recon Server stores its OM
snapshot DB.
|
+| `ozone.recon.om.snapshot.task.interval.delay` | 10m
| Interval in MINUTES by Recon
to request OM DB Snapshot / delta updates.
|
+| `ozone.recon.task.missingcontainer.interval` | 300s
| Time interval of the periodic
check for Unhealthy Containers in the cluster.
|
+| `ozone.recon.task.safemode.wait.threshold` | 300s
| Max time for Recon to wait
before it exits out of safe or warmup mode.
|
+| `ozone.recon.sql.db.jooq.dialect` | DERBY
| Please refer to [SQL
Dialect](https://www.jooq.org/javadoc/latest/org.jooq/org/jooq/SQLDialect.html)
to specify a different dialect. |
+| `ozone.recon.sql.db.jdbc.url` |
`jdbc:derby:${ozone.recon.db.dir}`<br></br>`/ozone_recon_derby.db` |
Recon SQL database jdbc url.
|
+| `ozone.recon.sql.db.username` | none
| Recon SQL database username.
|
+| `ozone.recon.sql.db.password` | none
| Recon SQL database password.
|
+| `ozone.recon.sql.db.driver` | `org.apache.derby.jdbc.EmbeddedDriver`
| Recon SQL database jdbc driver.
|
+| `ozone.recon.prometheus.http.endpoint` | none
| Prometheus HTTP endpoint URL for
Recon to integrate with Prometheus. Enables display of metrics in Recon UI and
exposes a proxy endpoint to query Prometheus. Example:
`http://prometheus:9090`. |
+| `ozone.recon.scmconfig` | none
| Prefix for SCM configuration.
|
+| `ozone.recon.db.dirs.permissions` | `750`
| Permissions for the metadata directories
for Recon. The permissions can either be octal or symbolic. If the default
permissions are not set then the default value of 750 will be used. |
+| `ozone.recon.datanode.address` | none
| Datanode address for Recon.
|
+| `ozone.recon.heatmap.enable` | `false`
| To enable/disable Recon heatmap feature. Along
with this config, user must also provide the implementation of
`org.apache.hadoop.ozone.recon.heatmap.IHeatMapProvider` interface and
configure in `ozone.recon.heatmap.provider` configuration. |
+| `ozone.recon.https-address` | `0.0.0.0:9889`
| The address and the base port where the Recon
web UI will listen on using HTTPS. If the port is 0 then the server will start
on a free port. |
+| `ozone.recon.datanode.bind.host` | `0.0.0.0`
| Bind host for Datanode address.
|
diff --git a/docs/03-core-concepts/01-architecture/ReconHighLevelDesign.png
b/docs/03-core-concepts/01-architecture/ReconHighLevelDesign.png
new file mode 100644
index 000000000..3bd6443d8
Binary files /dev/null and
b/docs/03-core-concepts/01-architecture/ReconHighLevelDesign.png differ
diff --git a/docs/03-core-concepts/01-architecture/ReconOmDesign.png
b/docs/03-core-concepts/01-architecture/ReconOmDesign.png
new file mode 100644
index 000000000..20ea6a336
Binary files /dev/null and
b/docs/03-core-concepts/01-architecture/ReconOmDesign.png differ
diff --git a/docs/03-core-concepts/01-architecture/ReconScmDesign.png
b/docs/03-core-concepts/01-architecture/ReconScmDesign.png
new file mode 100644
index 000000000..32d07e02d
Binary files /dev/null and
b/docs/03-core-concepts/01-architecture/ReconScmDesign.png differ
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
