Docs: improve LogQL section (#4145)

* Docs: improve LogQL section - Add a subsection for examples - Fix typos and wording * Update docs/sources/logql/query_examples.md Co-authored-by: Sandeep Sukhani <[email protected]> * Update docs/sources/logql/query_examples.md Co-authored-by: Sandeep Sukhani <[email protected]> Co-authored-by: Owen Diehl <[email protected]> Co-authored-by: Sandeep Sukhani <[email protected]>
grafana · Aug 19, 2021 · 368d18c · 368d18c
1 parent 10c92a9
commit 368d18c
Show file tree

Hide file tree

Showing 3 changed files with 69 additions and 5 deletions.
diff --git a/docs/sources/logql/_index.md b/docs/sources/logql/_index.md
@@ -415,10 +415,10 @@ those labels:
 
 ##### unpack
 
-The `unpack` parser will parse a json log line, and unpack all embedded labels via the [`pack`](../clients/promtail/stages/pack/) stage.
+The `unpack` parser parses a JSON log line, unpacking all embedded labels in the [`pack`](../clients/promtail/stages/pack/) stage.
 **A special property `_entry` will also be used to replace the original log line**.
 
-For example, using `| unpack` with the following log line:
+For example, using `| unpack` with the log line:
 
 ```json
 {
@@ -428,9 +428,9 @@ For example, using `| unpack` with the following log line:
 }
 ```
 
-allows to extract the `container` and `pod` labels and the `original log message` as the new log line.
+extracts the `container` and `pod` labels; it sets `original log message` as the new log line.
 
-> You can combine `unpack` with `json` parser (or any other parsers) if the original embedded log line is specific format.
+You can combine the `unpack` and `json` parsers (or any other parsers) if the original embedded log line is of a specific format.
 
 #### Label Filter Expression
 

diff --git a/docs/sources/logql/ip.md b/docs/sources/logql/ip.md
@@ -30,7 +30,7 @@ also matches example IP addresses such as 93.180.71.3. A better choice uses a re
 The LogQL support for matching IP addresses handles both IPv4 and IPv6 single addresses, as well as ranges within IP addresses
 and CIDR patterns.
 
-Match IP addresses wtih the syntax: `ip("<pattern>")`.
+Match IP addresses with the syntax: `ip("<pattern>")`.
 The `<pattern>` can be:
 
 -  A single IP address. Examples: `ip("192.0.2.0")`, `ip("::1")`

diff --git a/docs/sources/logql/query_examples.md b/docs/sources/logql/query_examples.md
@@ -0,0 +1,64 @@
+---
+title: Query examples
+weight: 40
+---
+
+# Query examples
+
+Some useful query examples here.
+
+## Log Query examples
+
+### Examples that filter on IP address 
+
+- Return log lines that are not within a range of IPv4 addresses:
+
+    ```logql
+    {job_name="myapp"} != ip("192.168.4.5-192.168.4.20")
+    ```
+
+
+- This example matches log lines with all IPv4 subnet values `192.168.4.5/16` except IP address `192.168.4.2`:
+
+    ```logql
+    {job_name="myapp"}
+		| logfmt
+		| addr = ip("192.168.4.5/16")
+		| addr != ip("192.168.4.2")
+    ```
+
+### Examples that aid in security evaluation
+
+- Extract the user and IP address of failed logins from Linux `/var/log/secure`
+
+    ```logql
+    {job="security"} 
+        |~ "Invalid user.*"
+        | regexp "(^(?P<user>\\S+ {1,2}){8})"
+        | regexp "(^(?P<ip>\\S+ {1,2}){10})"
+        | line_format "IP = {{.ip}}\tUSER = {{.user}}"
+    ```
+   
+- Get successful logins from Linux `/var/log/secure`
+
+    ```logql
+    {job="security"}
+        != "grafana_com"
+        |= "session opened"
+        != "sudo: "
+        |regexp "(^(?P<user>\\S+ {1,2}){11})"
+        | line_format "USER = {{.user}}"
+    ```
+
+## Metrics Query examples
+
+- Return the per-second rate of all non-timeout errors
+within the last minutes per host for the MySQL job,
+and only include errors whose duration is above ten seconds.
+
+    ```
+    sum by (host) (rate({job="mysql"}
+        |= "error" != "timeout"
+        | json
+        | duration > 10s [1m]))
+    ```