Merge pull request github#6011 from github/docs-4433-diagnostic-info

Make minimal changes to CodeQL docs for new diagnostic data

Author: felicitymay

docs/codeql/codeql-cli/analyzing-databases-with-the-codeql-cli.rst

@@ -24,11 +24,12 @@ Before starting an analysis you must:
 Running ``codeql database analyze``
 ------------------------------------
 
-When you run ``database analyze``, it does two things:
+When you run ``database analyze``, it:
 
 #. Executes one or more query files, by running them over a CodeQL database.
 #. Interprets the results, based on certain query metadata, so that alerts can be
    displayed in the correct location in the source code.
+#. Reports the results of any diagnostic and summary queries to standard output.
 
 You can analyze a database by running the following command::
 
@@ -142,6 +143,13 @@ These are stored alongside the code scanning suites with names of the form: ``<l
 For information about creating custom query suites, see ":doc:`Creating
 CodeQL query suites <creating-codeql-query-suites>`."
 
+Diagnostic and summary information
+..................................
+
+When you create a CodeQL database, the extractor stores diagnostic data in the database. The code scanning query suites include additional queries to report on this diagnostic data and calculate summary metrics. When the ``database analyze`` command completes, the CLI generates the results file and reports any diagnostic and summary data to standard output. If you choose to generate SARIF output, the additional data is also included in the SARIF file.
+
+If the analysis found fewer results for standard queries than you expected, review the results of the diagnostic and summary queries to check whether the CodeQL database is likely to be a good representation of the codebase that you want to analyze.
+
 Running all queries in a directory
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/codeql/codeql-cli/using-custom-queries-with-the-codeql-cli.rst

@@ -33,8 +33,10 @@ following two properties to ensure that the results are interpreted correctly:
 
 - Query identifier (``@id``): a sequence of words composed of lowercase letters or
   digits, delimited by ``/`` or ``-``, identifying and classifying the query. 
-- Query type (``@kind``): identifies the query is an alert (``@kind problem``)
-  or a path (``@kind path-problem``).
+- Query type (``@kind``): identifies the query as a simple alert (``@kind problem``),
+  an alert documented by a sequence of code locations (``@kind path-problem``), 
+  for extractor troubleshooting (``@kind diagnostic``), or a summary metric 
+  (``@kind metric`` and ``@tags summary``).
 
 For more information about these metadata properties, see ":ref:`Metadata for CodeQL queries
 <metadata-for-codeql-queries>`" and the `Query metadata style guide

docs/codeql/writing-codeql-queries/about-codeql-queries.rst

@@ -57,8 +57,10 @@ Query metadata is used to identify your custom queries when they are added to th
 
     Queries that are contributed to the open source repository, added to a query pack in LGTM, or used to analyze a database with the :ref:`CodeQL CLI <codeql-cli>` must have a query type (``@kind``) specified. The ``@kind`` property indicates how to interpret and display the results of the query analysis:
 
-    - Alert query metadata must contain ``@kind problem``.
-    - Path query metadata must contain ``@kind path-problem``.
+    - Alert query metadata must contain ``@kind problem`` to identify the results as a simple alert.
+    - Path query metadata must contain ``@kind path-problem`` to identify the results as an alert documented by a sequence of code locations.
+    - Diagnostic query metadata must contain ``@kind diagnostic`` to identify the results as troubleshooting data about the extraction process.
+    - Summary query metadata must contain ``@kind metric`` and ``@tags summary`` to identify the results as summary metrics for the CodeQL database.
 
     When you define the ``@kind`` property of a custom query you must also ensure that the rest of your query has the correct structure in order to be valid, as described below.
 
@@ -114,6 +116,8 @@ You can modify the alert message defined in the final column of the ``select`` s
 
 Select clauses for path queries (``@kind path-problem``) are crafted to display both an alert and the source and sink of an associated path graph. For more information, see ":doc:`Creating path queries <creating-path-queries>`."
 
+Select clauses for diagnostic queries (``@kind diagnostic``) and summary metric queries (``@kind metric`` and ``@tags summary``) have different requirements. For examples, see the `diagnostic queries <https://github.com/github/codeql/search?q=%22%40kind+diagnostic%22>`__ and the `summary metric queries <https://github.com/github/codeql/search?q=%22%40kind+metric%22+%22%40tags+summary%22>`__  in the CodeQL repository.
+
 Viewing the standard CodeQL queries
 ***********************************