Skip to content

Commit cc885fc

Browse files
even-weieven-wei
authored
Merge pull request #18 from DataRecce/feature/drc-1388-add-docs-for-recce-debug-command
Add recce debug releated docs
2 parents a8b1e95 + 52f6cb9 commit cc885fc

File tree

3 files changed

+132
-4
lines changed

3 files changed

+132
-4
lines changed

‎docs/configure-diff.md‎

Lines changed: 18 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ icon: material/package-variant
55

66
# Configure Diff
77

8-
To compare changes, Recce needs a baseline. This guide explains the concept of Diff in Recce and how it fits into data validation workflows. Setup steps vary by environment, so this guide focuses on the core ideas rather than copy-paste instructions.
8+
To compare changes, Recce needs a baseline. This guide explains the concept of Diff in Recce and how it fits into data validation workflows. Setup steps vary by environment, so this guide focuses on the core ideas rather than copy-paste instructions.
99

1010
For a concrete example, refer to the [5-minute Jaffle Shop tutorial](./get-started-jaffle-shop/).
1111

@@ -33,7 +33,7 @@ For example:
3333
- `prod` schema for production
3434
- `dev` schema for development
3535

36-
These schemas represent where dbt builds its models.
36+
These schemas represent where dbt builds its models.
3737

3838
!!! tip
3939

@@ -43,9 +43,23 @@ Schemas are typically configured in the `profiles.yml` file, which defines how d
4343

4444
Once both artifacts and schemas are configured, Recce can surface meaningful diffs across logic, metadata, and data.
4545

46-
## Check setup in Environment Info
46+
## Verify your setup
4747

48-
Use **Environment Info** at the top-right corner to verify that the configuration is complete.
48+
There are two ways to check that your configuration is complete:
49+
50+
### 1. Debug Command (CLI)
51+
52+
Run `recce debug` from the command line to verify your setup before launching the server:
53+
54+
```bash
55+
recce debug
56+
```
57+
58+
This command checks artifacts, directories, and warehouse connection, providing detailed feedback on any missing components.
59+
60+
### 2. Environment Info (Web UI)
61+
62+
Use **Environment Info** at the top-right corner of the Recce web interface to verify your configuration.
4963

5064
A correctly configured setup will display two environments:
5165

‎docs/features/recce-debug.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
---
2+
title: Debug
3+
icon: material/bug-check
4+
---
5+
6+
The `recce debug` command is a diagnostic tool that helps you verify your Recce setup by checking the development and base environments. It validates that all required dbt artifacts are in place and tests the warehouse connection, ensuring everything is properly configured before running other Recce commands.
7+
8+
## Usage
9+
10+
```bash
11+
recce debug [OPTIONS]
12+
```
13+
14+
## Options
15+
16+
| Option | Description |
17+
| ------------------------- | ----------------------------------------------------------------- |
18+
| `-t, --target TEXT` | Which target to load for the given profile |
19+
| `--profile TEXT` | Which existing profile to load |
20+
| `--project-dir PATH` | Which directory to look in for the dbt_project.yml file |
21+
| `--profiles-dir PATH` | Which directory to look in for the profiles.yml file |
22+
| `--target-path TEXT` | dbt artifacts directory for your development branch |
23+
| `--target-base-path TEXT` | dbt artifacts directory to be used as the base for the comparison |
24+
| `--help` | Show help message and exit |
25+
26+
## Example Outputs
27+
28+
### Success Case
29+
30+
When everything is properly configured, you'll see output like this:
31+
32+
```shell
33+
────────────────────── Development Environment ──────────────────────
34+
[OK] Directory exists: target
35+
[OK] Manifest JSON file exists : target/manifest.json
36+
[OK] Catalog JSON file exists: target/catalog.json
37+
─────────────────────────── Base Environment ────────────────────────
38+
[OK] Directory exists: target-base
39+
[OK] Manifest JSON file exists : target-base/manifest.json
40+
[OK] Catalog JSON file exists: target-base/catalog.json
41+
────────────────────── Warehouse Connection ─────────────────────────
42+
[OK] Connection test
43+
──────────────────────────── Result ─────────────────────────────────
44+
[OK] Ready to launch! Type 'recce server'.
45+
```
46+
47+
### Partial Setup Cases
48+
49+
Even when some components are missing, Recce can still launch with limited features and provides helpful tips:
50+
51+
#### Missing Base Environment Directory
52+
53+
```shell
54+
────────────────────── Development Environment ──────────────────────
55+
[OK] Directory exists: target
56+
[OK] Manifest JSON file exists : target/manifest.json
57+
[OK] Catalog JSON file exists: target/catalog.json
58+
─────────────────────────── Base Environment ────────────────────────
59+
[MISS] Directory not found: target-base
60+
────────────────────── Warehouse Connection ─────────────────────────
61+
[OK] Connection test
62+
──────────────────────────── Result ─────────────────────────────────
63+
[OK] Ready to launch with limited features. Type 'recce server'.
64+
[TIP] Run dbt with '--target-path target-base' or overwrite the
65+
default directory of the base environment with
66+
'--target-base-path'.
67+
```
68+
69+
#### Missing Base Environment Artifacts
70+
71+
```shell
72+
────────────────────── Development Environment ──────────────────────
73+
[OK] Directory exists: target
74+
[OK] Manifest JSON file exists : target/manifest.json
75+
[OK] Catalog JSON file exists: target/catalog.json
76+
─────────────────────────── Base Environment ────────────────────────
77+
[OK] Directory exists: target-base
78+
[MISS] Manifest JSON file not found: target-base/manifest.json
79+
[MISS] Catalog JSON file not found: target-base/catalog.json
80+
────────────────────── Warehouse Connection ─────────────────────────
81+
[OK] Connection test
82+
──────────────────────────── Result ─────────────────────────────────
83+
[OK] Ready to launch with limited features. Type 'recce server'.
84+
[TIP] 'dbt run --target-path target-base' to generate the
85+
manifest JSON file for the base environment.
86+
[TIP] 'dbt docs generate --target-path target-base' to generate
87+
the catalog JSON file for the base environment.
88+
```
89+
90+
#### Connection Failure
91+
92+
When the database connection fails, you'll see output like this:
93+
94+
```shell
95+
────────────────────── Development Environment ──────────────────────
96+
[OK] Directory exists: target
97+
[OK] Manifest JSON file exists : target/manifest.json
98+
[OK] Catalog JSON file exists: target/catalog.json
99+
─────────────────────────── Base Environment ────────────────────────
100+
[OK] Directory exists: target-base
101+
[OK] Manifest JSON file exists : target-base/manifest.json
102+
[OK] Catalog JSON file exists: target-base/catalog.json
103+
────────────────────── Warehouse Connection ─────────────────────────
104+
[FAIL] Connection test
105+
──────────────────────────── Result ─────────────────────────────────
106+
[TIP] Run 'dbt debug' to check the connection.
107+
```
108+
109+
## Related Documentation
110+
111+
- [Getting Started](../get-started.md): Learn how to set up your first Recce environment
112+
- [Environment Preparation Best Practices](../guides/best-practices-prep-env.md): Detailed guide on preparing environments
113+
- [Run Command](./recce-run.md): Execute checks from the command line

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@ nav:
4949
- features/query.md
5050
- features/checklist.md
5151
- Command Line Interface:
52+
- features/recce-debug.md
5253
- features/recce-run.md
5354
- features/recce-summary.md
5455
- Advanced Features:

0 commit comments

Comments
 (0)