docs: Revise the LogQL Analyzer topic (backport release-3.1.x) (#14455)

Co-authored-by: J Stickler <[email protected]>

docs/sources/query/analyzer.md

@@ -1,37 +1,49 @@
 ---
-title: LogQL Analyzer
-menuTitle: LogQL Analyzer 
-description: The LogQL Analyzer is an inline educational tool for experimenting with writing LogQL queries.
-aliases: 
+title: Simple LogQL simulator
+menuTitle: LogQL simulator
+description: The LogQL simulator is an online educational tool for experimenting with writing simple LogQL queries.
+aliases:
 - ../logql/analyzer/
-weight: 60
+weight: 200
 ---
 
+
 <link rel="stylesheet" href="../analyzer/style.css">
 <script src="../analyzer/handlebars.js"></script>
 
-# LogQL Analyzer
+# Simple LogQL simulator
+
+The LogQL simulator is an online tool that you can use to experiment with writing simple LogQL queries and seeing the results, without needing to run an instance of Loki.
+
+A set of example log lines are included for each of the primary log parsers supported by Loki:
+
+- [Logfmt](https://brandur.org/logfmt)
+- [JSON](https://www.json.org/json-en.html)
+- Unstructured text, which can be parsed with the Loki pattern or regex parsers
+
+The [log stream selector](https://grafana.com/docs/loki/<LOKI_VERSION>/query/log_queries/#log-stream-selector) `{job="analyze"}` is shown as an example, and it remains fixed for all possible example queries in the simulator. A log stream is a set of logs which share the same labels. In LogQL, you use a log stream selector to determine which log streams to include in a query's results.
+
+{{< admonition type="note" >}}
+This is a very limited simulator, primarily for evaluating filters and parsers. If you want to practice writing more complex queries, such as metric queries, you can use the [Explore](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/explore/logs-integration/) feature in Grafana.
+{{< /admonition >}}
 
-The LogQL Analyzer is an inline tool for experimenting with writing LogQL queries.
+To use the LogQL simulator:
 
-Chose the log line format with the radio buttons.
-A set of example log lines are included for each format.
+1. Select a log line format using the radio buttons.
 
-Use the provided example log lines, or copy and paste your own log lines into the example log lines box.
+1. You can use the provided example log lines, or copy and paste your own log lines into the example log lines box.
 
-Use the provided example query, or enter your own query.
-The [log stream selector]({{< relref "./log_queries#log-stream-selector" >}}) remains fixed for all possible example queries.
-Modify the remainder of the log line and click on the **Run query** button
-to run the entered query against the example log lines. 
+1. Use the provided example LogQL query, or enter your own query. The [log stream selector](https://grafana.com/docs/loki/<LOKI_VERSION>/query/log_queries/#log-stream-selector) remains fixed for all possible example queries. There are additional sample queries at the end of this topic.
 
-The results output provides details for each example log line.
-Clicking on a line in the results pane expands the details, showing why the line is or is not included in the query result set.
+1. Click the **Run query** button to run the entered query against the example log lines.
+
+The results output simulates how Loki would return results for your query. You can also click each line in the results pane to expand the details, which give an explanation for why the log line is or is not included in the query result set.
 
 <main class="logql-analyzer">
     <section class="logs-source panel-container">
         <div class="logs-source__header">
             <div class="examples">
-                <span>Log line format:</span> 
+                <span>Log line format:</span>
                 <span class="example">
                     <input type="radio" class="example-select" name="example" id="logfmt-example" checked>
                     <label for="logfmt-example">logfmt</label>
@@ -92,7 +104,6 @@ Clicking on a line in the results pane expands the details, showing why the line
                         <span>Line {{inc @index}}</span>
                     </div>
                 </div>
-
                 {{#if this.log_result}}
                     <span {{#if this.filtered_out}}class="filtered-out"{{/if}}>
                         {{this.log_result}}
@@ -158,7 +169,7 @@ Clicking on a line in the results pane expands the details, showing why the line
                                     {{/unless}}
                                     {{#if this.filtered_out}}
                                         <span class="important-text">the line has been filtered out on this stage</span>
-                                    {{/if}}                                    
+                                    {{/if}}
                                 </div>
                             </div>
                             {{#if added_labels}}
@@ -196,7 +207,7 @@ level=info ts=2022-03-23T11:55:45.221254326Z caller=loki.go:355 msg="Loki starte
 </script>
 
 <script type="text/plain" id="logfmt-example-query">
-| logfmt | level = "info" 
+| logfmt | level = "info"
 </script>
 
 [//]: # (Json parser examples)
@@ -215,7 +226,6 @@ level=info ts=2022-03-23T11:55:45.221254326Z caller=loki.go:355 msg="Loki starte
 | json | level="INFO" | line_format "{{.message}}"
 </script>
 
-
 [//]: # (Pattern parser examples)
 <script type="text/plain" id="pattern-parser-example-logs">
 238.46.18.83 - - [09/Jun/2022:14:13:44 -0700] "PUT /target/next-generation HTTP/2.0" 404 19042
@@ -235,4 +245,48 @@ level=info ts=2022-03-23T11:55:45.221254326Z caller=loki.go:355 msg="Loki starte
 
 <script src="../analyzer/script.js"> </script>
 
+## Additional sample queries
+
+These are some additional sample queries that you can use in the LogQL simulator.
+
+### Logfmt
+
+```logql
+| logfmt | level = "debug"
+```
+
+Parses logfmt-formatted logs and returns only log lines where the "level" field is equal to "debug".
+
+```logql
+| logfmt | msg="server listening on addresses"
+```
+
+Parses logfmt-formatted logs and returns only log lines with the message “server listening on address.”
+
+### JSON
+
+```logql
+| json | level="INFO" | file="SpringApplication.java" | line_format `{{.class}}`
+```
+
+Parses JSON-formatted logs, filtering for lines where the 'level' field is "INFO" and the 'file field is "SpringApplication.java", then formats the line to return only the 'class' field.
+
+```logql
+|~ `(T|t)omcat`
+```
+
+Performs a regular expression filter for the string 'tomcat' or 'Tomcat', without using a parser.
+
+### Unstructured text
+
+```logql
+| pattern "<_> - <_> <_> \"<method> <url> <protocol>\" <status> <_> <_> \"<_>\" <_>" | method="GET"
+```
+
+Parses unstructured logs with the pattern parser, filtering for lines where the HTTP method is "GET".
+
+```logql
+| pattern "<_> - <user> <_> \"<method> <url> <protocol>\" <status> <_> <_> \"<_>\" <_>" | user=~"kling.*"
+```
 
+Parses unstructured logs with the pattern parser, extracting the 'user' field, and filtering for lines where the user field starts with "kling".

docs/sources/query/bp-query.md

@@ -4,7 +4,7 @@ menuTitle:  Query best practices
 description: Describes best practices for querying in Grafana Loki.
 aliases:
 - ../bp-query
-weight: 700
+weight: 100
 ---
 # Query best practices
 

docs/sources/query/ip.md

@@ -4,7 +4,7 @@ menuTItle:
 description: Describes how LogQL supports matching IP addresses.
 aliases: 
  - ../logql/ip/
-weight: 40
+weight: 600
 ---
 
 # Matching IP addresses

docs/sources/query/log_queries/_index.md

@@ -4,7 +4,7 @@ menuTItle:
 description: Overview of how log queries are constructed and parsed.
 aliases: 
 - ../logql/log_queries/
-weight: 10 
+weight: 300 
 ---
 
 # Log queries

docs/sources/query/metric_queries.md

@@ -4,7 +4,7 @@ menuTItle:
 description: Provides an overview of how metric queries are constructed and parsed. Metric queries extend log queries by applying a function to log query results.
 aliases: 
 - ../logql/metric_queries/
-weight: 20  
+weight: 400  
 ---
 
 # Metric queries

docs/sources/query/query_examples.md

@@ -4,7 +4,7 @@ menuTitle: Query examples
 description: Provides LogQL query examples with explanations on what those queries accomplish.
 aliases: 
 - ../logql/query_examples/
-weight: 50 
+weight: 800 
 ---
 
 # Query examples

docs/sources/query/template_functions.md

@@ -4,7 +4,7 @@ menuTItle:  Template functions
 description: Describes query functions that are supported by the Go text template.
 aliases:
 - ../logql/template_functions/
-weight: 30
+weight: 500
 ---
 
 # LogQL template functions