From ad51306f51067e7f474acfd2f4311cf2f8c05739 Mon Sep 17 00:00:00 2001 From: Julie Stickler Date: Thu, 3 Oct 2024 10:54:42 -0400 Subject: [PATCH 1/2] docs: Revise the LogQL Analyzer topic --- docs/sources/query/analyzer.md | 96 ++++++++++++++++++------ docs/sources/query/bp-query.md | 2 +- docs/sources/query/ip.md | 2 +- docs/sources/query/log_queries/_index.md | 2 +- docs/sources/query/metric_queries.md | 2 +- docs/sources/query/query_examples.md | 2 +- docs/sources/query/template_functions.md | 2 +- 7 files changed, 81 insertions(+), 27 deletions(-) diff --git a/docs/sources/query/analyzer.md b/docs/sources/query/analyzer.md index 3ac057e4ff5b5..5ccae0310c584 100644 --- a/docs/sources/query/analyzer.md +++ b/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 --- + -# 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 Loki's primary supported log parsers: + +- [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//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//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//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.
- Log line format: + Log line format: @@ -92,7 +104,6 @@ Clicking on a line in the results pane expands the details, showing why the line Line {{inc @index}}
- {{#if this.log_result}} {{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}} the line has been filtered out on this stage - {{/if}} + {{/if}} {{#if added_labels}} @@ -196,7 +207,7 @@ level=info ts=2022-03-23T11:55:45.221254326Z caller=loki.go:355 msg="Loki starte [//]: # (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}}" - [//]: # (Pattern parser examples) +## 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="GET" +``` + +Parses unstructured logs with the pattern parser, filtering for lines where the HTTP method is "GET". + +```logQL +| pattern "<_> - <_> \" \" <_> <_> \"<_>\" <_>" | user=~"kling.*" +``` +Parses unstructured logs with the pattern parser, extracting the 'user' field, and filtering for lines where the user field starts with "kling". diff --git a/docs/sources/query/bp-query.md b/docs/sources/query/bp-query.md index 819fdc0a76b06..692cb14ee2948 100644 --- a/docs/sources/query/bp-query.md +++ b/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 diff --git a/docs/sources/query/ip.md b/docs/sources/query/ip.md index 6456030ce5d4a..f299e35a3f9d1 100644 --- a/docs/sources/query/ip.md +++ b/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 diff --git a/docs/sources/query/log_queries/_index.md b/docs/sources/query/log_queries/_index.md index 3457f9637147e..5e429b2f3b86c 100644 --- a/docs/sources/query/log_queries/_index.md +++ b/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 diff --git a/docs/sources/query/metric_queries.md b/docs/sources/query/metric_queries.md index 3eacabf204c6a..d3d2efb2714d7 100644 --- a/docs/sources/query/metric_queries.md +++ b/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 diff --git a/docs/sources/query/query_examples.md b/docs/sources/query/query_examples.md index 1298a36f4a915..922565fe9985f 100644 --- a/docs/sources/query/query_examples.md +++ b/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 diff --git a/docs/sources/query/template_functions.md b/docs/sources/query/template_functions.md index 499220c5e377c..c92c3d49de351 100644 --- a/docs/sources/query/template_functions.md +++ b/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 From 1dd13be0b72e192acc1f09b5fc1d39e0f45d9f9b Mon Sep 17 00:00:00 2001 From: J Stickler Date: Wed, 9 Oct 2024 13:40:59 -0400 Subject: [PATCH 2/2] Apply suggestions from code review Review comments Co-authored-by: Jack Baldry --- docs/sources/query/analyzer.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/sources/query/analyzer.md b/docs/sources/query/analyzer.md index 5ccae0310c584..92ddd8ba91692 100644 --- a/docs/sources/query/analyzer.md +++ b/docs/sources/query/analyzer.md @@ -1,7 +1,7 @@ --- title: Simple LogQL simulator -menuTitle: LogQL Simulator -description: The LogQL Simulator is an online educational tool for experimenting with writing simple LogQL queries. +menuTitle: LogQL simulator +description: The LogQL simulator is an online educational tool for experimenting with writing simple LogQL queries. aliases: - ../logql/analyzer/ weight: 200 @@ -13,9 +13,9 @@ weight: 200 # 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. +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 Loki's primary supported log parsers: +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) @@ -245,19 +245,19 @@ level=info ts=2022-03-23T11:55:45.221254326Z caller=loki.go:355 msg="Loki starte -## Additional Sample Queries +## Additional sample queries These are some additional sample queries that you can use in the LogQL simulator. ### Logfmt -```logQL +```logql | logfmt | level = "debug" ``` Parses logfmt-formatted logs and returns only log lines where the "level" field is equal to "debug". -```logQL +```logql | logfmt | msg="server listening on addresses" ``` @@ -265,13 +265,13 @@ Parses logfmt-formatted logs and returns only log lines with the message “serv ### JSON -```logQL +```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 +```logql |~ `(T|t)omcat` ``` @@ -279,13 +279,13 @@ Performs a regular expression filter for the string 'tomcat' or 'Tomcat', withou ### Unstructured text -```logQL +```logql | pattern "<_> - <_> <_> \" \" <_> <_> \"<_>\" <_>" | method="GET" ``` Parses unstructured logs with the pattern parser, filtering for lines where the HTTP method is "GET". -```logQL +```logql | pattern "<_> - <_> \" \" <_> <_> \"<_>\" <_>" | user=~"kling.*" ```