DOC-12541 Added a new file and modified the cli-intro file

Pallavi-Janardhan · simon-dew · commit c3be5c078a14 · 2025-10-03T13:43:10.000+01:00
diff --git a/modules/cli/pages/cbqueryreportgen.adoc b/modules/cli/pages/cbqueryreportgen.adoc
@@ -1,5 +1,5 @@
 = cbqueryreportgen
-:description: pass:q[A query tool that returns the complete details of any Query service to generate reports.]
+:description: pass:q[The 'cbqueryreportgen' tool returns the complete details of any Query service to generate reports.]
 :page-status: Couchbase Server 8.0
 :page-component: Query
 ifndef::doctype-manpage[:doctitle: cbqueryreportgen]
@@ -10,242 +10,64 @@ ifndef::doctype-manpage[:doctitle: cbqueryreportgen]
 {A query tool that returns the complete details of any Query Service to generate reports.}
 
 == Syntax
-The basic syntax is:
 
 ----
-cbqueryreportgen [-<args>]
+cbqueryreportgen [-<args>
+                  [ -c, --cluster <cluster> ]
+                  [ -u, --username <username> ]
+                  [ -p, --password <password> ]
+                  [ -k, --keyspace <keyspace> ]
+                  [ -t1, --time-period <time-period> ]
+                  [ -o, --output <output> ]
+                  [ --report-type <report-type> ]
+                  [ --output-file <output-file> ]
+                  [ --format <format> ]
+                  [ -l, --limit <limit> ]
+                  [ -v, --verbose ]
+                  [ -h, --help ] 
+                 ]
 ----
 
-Required Flags: 
-  -c, --cluster       The hostname of the Couchbase cluster. Example: 'couchbase://localhost'.
-  -u, --username      The username of the Couchbase cluster. Example: 'Administrator'.
-  -p, --password      The password of the Couchbase cluster.
-  -k, --keyspace      The keyspace where the awr stats are read from. Example: 'travel-sample._default.awr'.
-  -t1, --time-period  The required format is 'start-time, end-time' in the format 'YYYY-MM-DDTHH:MM:SS'. Example: '2025-10-01T00:00:00,2025-10-02T00:00:00'.
-  -o, --output        The output file to write the report to. Example: 'report.html'.
-
-
-optional Flags:
-
-      --report-type   The type of report to generate. Supported values are 'AWR' and 'ADHOC'. Default is 'AWR'(Automatic Workload Repository).
-      --output-file   The file path where the report will be saved. If not provided, the report will be printed to stdout.
-      --format        The format of the report. 'HTML' is the default format.
-      -l, --limit     The maximum number of results to include for every query. The default is '1000'.
-      -v, --verbose   Enable verbose logging for debugging purposes.
-      -h, --help      Prints the help information.
 
 == Description
 
-cbqueryreportgen is a command-line tool that connects to a Couchbase cluster and generates performance reports based on the Query service's AWR statistics.
+The 'cbqueryreportgen' command connects to a Couchbase cluster and generates performance reports based on the Query service's AWR statistics.
 
 The tool allows users to specify a time range for the report, the type of report, and the output format. 
 By default, the output of the command is a report in HTML format. 
 You can save the generated report to a file or print it to the standard output.
 
-For more information on how specific commands work, run "cbqueryreportgen --help".
-
-ifeval::['{page-component-version}' == '8.0'] 
-This tool is only available in Couchbase Server 8.0 and later.
-endif::[]
-
-Depending upon your platform, this tool is at the following locations:
-
-[cols="1,3"]
-|===
-| Operating system | Location
-
-| Linux
-| [.path]`/opt/couchbase/bin/`
-
-| Windows
-| [.path]`C:\Program Files\Couchbase\Server\bin\`
-
-| Mac OS X
-| [.path]`/Applications/CouchbaseServer.app/Contents/Resources/couchbase-core/bin/`
-|===
-
-== Options
-
-The query report generation tool supports the following options:
-
-The tool takes a single argument, which must be one of the following:
-
-number::
-A number representing an error code.
-In this case, the tool returns the full details of the error matching the error code.
-
-string::
-A string.
-In this case, the tool searches for the target string in all of the error message fields except for `USER ERROR`, and returns the full details of any errors that match the string.
-
-regex::
-A regular expression.
-In this case, the tool searches for the regular expression in all of the error message fields except for `USER ERROR`, and returns the full details of any errors that match the pattern.
-
-== Output
-
-If the tool finds a single error that matches the find argument, it outputs the full details of the error.
-
-If the tool finds multiple errors that match the find argument, it outputs a list showing the code and description of each matching error.
-You can use the tool again, passing the code or description as an argument, to get the full details of any of these errors.
-
-Full error details include some or all of the following fields.
-
-[options="header", cols="50a,147a"]
-|===
-|Name|Description
-
-|**APPLIES TO**
-|One of the following:
-
-* `cbq-shell`: The error applies to the cbq shell.
-* `Server`: The error applies to the server.
-
-|**CODE**
-|A number representing the error.
-
-|**DESCRIPTION**
-|Message describing why the error occurred.
-
-|**REASON**
-|List of possible causes of the error.
-
-|**USER ACTION**
-|List of possible steps a user can take to mitigate the error.
-
-|**USER ERROR**
-|One of the following:
-
-* `Yes`: The error was caused by the user.
-* `No`: The error was caused by other services, or was internal to the server.
-* `Maybe`: A combination of both.
-|===
-
-NOTE: The error details also include a `SYMBOL` field, which contains a representation string for the error.
-This field is for internal use only, and is not shown in the output.
-However, the tool does search this field when the find argument is a string or a regular expression.
+The '--cluster' flag specifies the hostname of the Couchbase cluster. Example: 'couchbase://localhost'.
 
-== Examples
+The '--username' flag specifies the username of the Couchbase cluster. Example: 'Administrator'.
 
-[[cbqueryreportgen-ex1]]
-.Find error details by code number
-====
-.Command
-[source,sh]
-----
-./cbqueryreportgen 5011
-----
-
-.Output
-----
-CODE
-  5011 (error)
-
-
-DESCRIPTION
-  Abort: «reason»
-
-
-REASON
-  The SQL++ abort() function was called in the statement.
-  e.g. SELECT abort('An example cause')
-
-
-USER ERROR
-  Yes
-
-
-APPLIES TO
-  Server
-----
-====
-
-[cbqueryreportgen-ex2]
-.Find error details by matching a string
-====
-.Command
-[source,sh]
-----
-./cbqueryreportgen "A semantic error is present in the statement."
-----
-
-.Output
-----
-CODE
-  3100 (error)
+The '--password' flag specifies the password of the Couchbase cluster. Example: 'password'.
 
+The '--keyspace' flag specifies the keyspace where the AWR stats are read from. Example: 'travel-sample._default.awr'.
 
-DESCRIPTION
-  A semantic error is present in the statement.
+The '--time-period' flag specifies the time period for the report. The required format is 'start-time,end-time' in the format 'YYYY-MM-DDTHH:MM:SS'. Example: '2025-10-01T00:00:00,2025-10-02T00:00:00'.
 
+The '--output' flag specifies the output file to write the report to. Example: 'report.html'.
 
-REASON
-  The statement includes portions that violate semantic constraints.
+optional Flags:
 
+The '--report-type' flag specifies the type of report to generate. Supported values are 'AWR' and 'ADHOC'. Default is 'AWR'(Automatic Workload Repository).
 
-USER ACTION
-  The cause will contain more detail on the violation; revise the statement and re-submit.
+The '--output-file' flag specifies the file path where the report will be saved. If not provided, the report will be printed to stdout.
 
+The '--format' flag specifies the format of the report. 'HTML' is the default format.
 
-USER ERROR
-  Yes
+The '-l, --limit' flag specifies the maximum number of results to include for every query. The default is '1000'.
 
+The '-v, --verbose' flag enables verbose logging for debugging purposes.
 
-APPLIES TO
-  Server
-----
-====
+The '-h, --help' flag prints the help information.
 
-[cbqueryreportgen-ex3]
-.Find multiple errors by matching a string
-====
-.Command
-[source,sh]
-----
-./cbqueryreportgen "semantic"
-----
+For more information on how the specific command works, run "cbqueryreportgen --help".
 
-.Output
-----
-Matching errors
-  3100 A semantic error is present in the statement.
-  3220 «name» window function «clause» «reason»
-  3300 recursive_with semantics: «cause»
-----
-====
-
-[cbqueryreportgen-ex4]
-.Find multiple errors by matching a regular expression
-====
-.Command
-[source,sh]
-----
-./cbqueryreportgen "[UI][NP]SERT"
-----
-
-.Output
-----
-Matching errors
-  3150 MERGE with ON KEY clause cannot have document key specification in INSERT action.
-  3160 MERGE with ON clause must have document key specification in INSERT action
-  3180 MERGE with ON KEY clause cannot have USE INDEX hint specified on target.
-  5006 Out of key validation space.
-  5050 No INSERT key for «document»
-  5060 No INSERT value for «document»
-  5070 Cannot INSERT non-string key «key» of type «type»
-  5071 Cannot INSERT non-OBJECT options «options» of type «type»
-  5072 No UPSERT key for «value»
-  5073 Cannot act on the same key multiple times in an UPSERT statement
-  5075 No UPSERT value for «value»
-  5078 Cannot UPSERT non-string key «key» of type «type».
-  5079 Cannot UPSERT non-OBJECT options «value» of type «type».
-  5330 Multiple INSERT of the same document (document key «key») in a MERGE statement
- 12036 Error in INSERT of key: «key»
- 15005 No keys to insert «details»
-----
-====
+The `--version` flag prints to the console the version number of the Couchbase Server.
 
-== See Also
+== See Also 
+(Writer's NOTE: Should we include more information after this? If yes, will change the xref's to appropriate links else will remove this section.)
 
-* The {sqlpp} xref:n1ql:n1ql-language-reference/metafun.adoc#cbqueryreportgen[cbqueryreportgen()] function
-* xref:n1ql:n1ql-language-reference/n1ql-error-codes.adoc[]
+For more information on AWR, see xref:n1ql:n1ql-manage/query-awr.adoc[ AWR Query].
diff --git a/modules/cli/pages/cli-intro.adoc b/modules/cli/pages/cli-intro.adoc
@@ -86,11 +86,11 @@ The Server admin tools package lets you install the following Server utilities o
 * xref:tools:cbimport.adoc[`cbimport`]
 * xref:cli:cbq-tool.adoc[`cbq`]
 * xref:cli:cbstats-intro.adoc[`cbstats`]
+* xref:cli:cbqueryreportgen.adoc[`cbqueryreportgen`] 
 * xref:cli:cbcli/couchbase-cli.adoc[`couchbase-cli`]
 * xref:cli:mcstat.adoc[`mcstat`]
 * xref:cli:mctimings.adoc[`mctimings`]
 * xref:cli:mctestauth.adoc[`mctestauth`]
-* xref:cli:cbqueryreportgen.adoc[`cbqueryreportgen`] 
 
 Download the command line tools package for your platform from the following links:
 
@@ -123,14 +123,15 @@ The versions of the utilities installed by the tools package are the same as the
 
 For the Server developer tools package, the {tools-ver} version of the utilities `cbimport`, `cbexport`, `cbbackupmgr`, and `cbq` are compatible with the following Couchbase Server versions:
 
-* 8.0 
 * 7.6.0, 7.6.1, 7.6.2, 7.6.3
 * 7.2.x
 * 7.1.x
 * 7.0.x
 
 You can download and use the latest version of the utilities (`cbimport`, `cbexport`, `cbbackupmgr`, and `cbq`) with earlier Couchbase Server versions.
 
+The 'cbqueryreportgen' utility is supported only on Couchbase Server 8.0 and later.
+
 For the Server admin tools package, do the following:
 
 * Use the `--version` option to get the version of the utility. However, for the `cbc` utility, use the `cbc version` option.
