From 5f3e6b8569b5b71853208949506bbcd3c44488b5 Mon Sep 17 00:00:00 2001
From: Paul Buetow <paul@buetow.org>
Date: Wed, 13 Oct 2021 20:39:00 +0300
Subject: backport docs from master

---
 doc/examples.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

(limited to 'doc/examples.md')

diff --git a/doc/examples.md b/doc/examples.md
index 964660a..91ab7f2 100644
--- a/doc/examples.md
+++ b/doc/examples.md
@@ -1,13 +1,13 @@
 Examples
 ========
 
-This page demonstrate the basic usage of DTail. Please also see ``dtail --help`` for more available options.
+This page demonstrates the primary usage of DTail. Please also see ``dtail --help`` for more available options.
 
 # How to use ``dtail``
 
 ## Tailing logs
 
-The following example demonstrates how to follow logs of multiple servers at once. The server list is provided as a flat text file. The example filters all logs containing the string ``STAT``. Any other Go compatible regular expression can be used instead of ``STAT``.
+The following example demonstrates how to follow logs of multiple servers at once. The server list is provided as a flat text file. The example filters all records containing the string ``STAT``. Any other Go compatible regular expression can be used instead of ``STAT``.
 
 ```shell
 % dtail --servers serverlist.txt --files "/var/log/service/*.log" --regex STAT
@@ -17,7 +17,7 @@ The following example demonstrates how to follow logs of multiple servers at onc
 
 ## Aggregating logs
 
-To run ad-hoc mapreduce aggregations on newly written log lines you also must add a query. This example follows all remote log lines and prints out every 5 seconds the top 10 servers with most average free memory according to the logs. To run a mapreduce query across log lines written in the past please use the ``dmap`` command instead.
+To run ad-hoc MapReduce aggregations on newly written log lines, you also must add a query. The following example follows all remote log lines and prints out every 5 seconds the top 10 servers with the most average free memory. To run a MapReduce query across log lines written in the past, please use the ``dmap`` command instead.
 
 ```shell
 % dtail --servers serverlist.txt  \
@@ -25,13 +25,13 @@ To run ad-hoc mapreduce aggregations on newly written log lines you also must ad
     --files '/var/log/service/*.log'
 ```
 
-In order for mapreduce queries to work you have to make sure that your log format is supported by DTail. You can either use the ones which are already defined in ``internal/mapr/logformat`` or add an extension to support a custom log format.
+For MapReduce queries to work, you have to ensure that DTail supports your log format. You can either use the ones already defined in ``internal/mapr/log format`` or add an extension to support a custom log format.
 
 ![dtail-map](dtail-map.gif "Tail mapreduce example")
 
 # How to use ``dcat``
 
-The following example demonstrates how to cat files (display the whole content of the files) of multiple servers at once. The servers are provided as a comma separated list this time.
+The following example demonstrates how to cat files (display the full content of the files) of multiple servers at once. The servers are provided as a comma-separated list this time.
 
 ```shell
 % dcat --servers serv-011.lan.example.org,serv-012.lan.example.org,serv-013.lan.example.org \
@@ -42,7 +42,7 @@ The following example demonstrates how to cat files (display the whole content o
 
 # How to use ``dgrep``
 
-The following example demonstrates how to grep files (display only the lines which match a given regular expression) of multiple servers at once. In this example we look after the swap partition in ``/etc/fstab``. We do that only on the first 20 servers from ``serverlist.txt``. ``dgrep`` is also very useful for searching log files of the past.
+The following example demonstrates how to grep files (display only the lines which match a given regular expression) of multiple servers at once. In this example, we look after the swap partition in ``/etc/fstab``. We do that only on the first 20 servers from ``serverlist.txt``. ``dgrep`` is also very useful for searching log files of the past.
 
 ```shell
 % dgrep --servers <(head -n 20 serverlist.txt) \
@@ -54,7 +54,7 @@ The following example demonstrates how to grep files (display only the lines whi
 
 # How to use ``dmap``
 
-To run a mapreduce aggregation over logs written in the past the ``dmap`` command can be used. For example the following command aggregates all mapreduce fields of all the logs and calculates the average memory free grouped by day of the month, hour, minute and the server hostname. ``dmap`` will print interim results every few seconds. The final result however will be written to file ``mapreduce.csv``.
+To run a MapReduce aggregation over logs written in the past, the ``dmap`` command can be used. For example, the following command aggregates all MapReduce fields of all the records and calculates the average memory free grouped by day of the month, hour, minute and the server hostname. ``dmap`` will print interim results every few seconds. The final product, however, will be written to file ``mapreduce.csv``.
 
 ```shell
 % dmap --servers serv-011.lan.example.org,serv-012.lan.example.org,serv-013.lan.example.org,serv-021.lan.example.org,serv-022.lan.example.org,serv-023.lan.example.org \
@@ -62,6 +62,6 @@ To run a mapreduce aggregation over logs written in the past the ``dmap`` comman
     --files "/var/log/service/*.log"
 ```
 
-Remember: In order for that to work you have to make sure that your log format is supported by DTail. You can either use the ones which are already defined in ``internal/mapr/logformat`` or add an extension to support a custom log format.
+Remember: For that to work, you have to make sure that DTail supports your log format. You can either use the ones already defined in ``internal/mapr/log format`` or add an extension to support a custom log format.
 
 ![dmap](dmap.gif "DMap example")
-- 
cgit v1.2.3


From dadbaab24d66685db0a2a6655bd75cdbb19eb929 Mon Sep 17 00:00:00 2001
From: Paul Buetow <pbuetow@mimecast.com>
Date: Wed, 27 Oct 2021 10:35:36 +0300
Subject: Update docs to reflect some of the changes made in the past

---
 doc/examples.md | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

(limited to 'doc/examples.md')

diff --git a/doc/examples.md b/doc/examples.md
index 91ab7f2..6c23120 100644
--- a/doc/examples.md
+++ b/doc/examples.md
@@ -15,6 +15,12 @@ The following example demonstrates how to follow logs of multiple servers at onc
 
 ![dtail](dtail.gif "Tail example")
 
+You can also use the shorthand version:
+
+```shell
+% dtail --servers serverlist.txt --regex STAT "/var/log/service/*.log"
+```
+
 ## Aggregating logs
 
 To run ad-hoc MapReduce aggregations on newly written log lines, you also must add a query. The following example follows all remote log lines and prints out every 5 seconds the top 10 servers with the most average free memory. To run a MapReduce query across log lines written in the past, please use the ``dmap`` command instead.
@@ -29,6 +35,14 @@ For MapReduce queries to work, you have to ensure that DTail supports your log f
 
 ![dtail-map](dtail-map.gif "Tail mapreduce example")
 
+You can also use the shorthand version:
+
+```shell
+% dtail --servers serverlist.txt  \
+    'select avg(memfree), $hostname from MCVMSTATS group by $hostname order by avg(memfree) limit 10 interval 5' \
+    '/var/log/service/*.log'
+```
+
 # How to use ``dcat``
 
 The following example demonstrates how to cat files (display the full content of the files) of multiple servers at once. The servers are provided as a comma-separated list this time.
@@ -40,6 +54,13 @@ The following example demonstrates how to cat files (display the full content of
 
 ![dcat](dcat.gif "Cat example")
 
+You can also use the shorthand version:
+
+```shell
+% dcat --servers serv-011.lan.example.org,serv-012.lan.example.org,serv-013.lan.example.org \
+    /etc/hostname
+```
+
 # How to use ``dgrep``
 
 The following example demonstrates how to grep files (display only the lines which match a given regular expression) of multiple servers at once. In this example, we look after the swap partition in ``/etc/fstab``. We do that only on the first 20 servers from ``serverlist.txt``. ``dgrep`` is also very useful for searching log files of the past.
@@ -52,6 +73,14 @@ The following example demonstrates how to grep files (display only the lines whi
 
 ![dgrep](dgrep.gif "Grep example")
 
+You can also use the shorthand version:
+
+TODO: Auto detect that swap is a regex.
+```shell
+% dgrep --servers <(head -n 20 serverlist.txt) \
+    /etc/fstab swap
+```
+
 # How to use ``dmap``
 
 To run a MapReduce aggregation over logs written in the past, the ``dmap`` command can be used. For example, the following command aggregates all MapReduce fields of all the records and calculates the average memory free grouped by day of the month, hour, minute and the server hostname. ``dmap`` will print interim results every few seconds. The final product, however, will be written to file ``mapreduce.csv``.
@@ -65,3 +94,11 @@ To run a MapReduce aggregation over logs written in the past, the ``dmap`` comma
 Remember: For that to work, you have to make sure that DTail supports your log format. You can either use the ones already defined in ``internal/mapr/log format`` or add an extension to support a custom log format.
 
 ![dmap](dmap.gif "DMap example")
+
+You can also use the shorthand version:
+
+```shell
+% dmap --servers serv-011.lan.example.org,serv-012.lan.example.org,serv-013.lan.example.org,serv-021.lan.example.org,serv-022.lan.example.org,serv-023.lan.example.org \
+    'select avg(memfree), $day, $hour, $minute, $hostname from MCVMSTATS group by $day, $hour, $minute, $hostname order by avg(memfree) limit 10 outfile mapreduce.csv' \
+    "/var/log/service/*.log"
+```
-- 
cgit v1.2.3


From 93e4ae02f1b1f8e03e72594e520f471fbac3c652 Mon Sep 17 00:00:00 2001
From: Paul Buetow <paul@buetow.org>
Date: Sun, 7 Nov 2021 13:07:09 +0200
Subject: new dtail cont. map example gifs

---
 doc/examples.md | 33 ++++++++++++++++++++++-----------
 1 file changed, 22 insertions(+), 11 deletions(-)

(limited to 'doc/examples.md')

diff --git a/doc/examples.md b/doc/examples.md
index 6c23120..584a9fb 100644
--- a/doc/examples.md
+++ b/doc/examples.md
@@ -7,28 +7,30 @@ This page demonstrates the primary usage of DTail. Please also see ``dtail --hel
 
 ## Tailing logs
 
-The following example demonstrates how to follow logs of multiple servers at once. The server list is provided as a flat text file. The example filters all records containing the string ``STAT``. Any other Go compatible regular expression can be used instead of ``STAT``.
+The following example demonstrates how to follow logs of multiple servers at once. The server list is provided as a flat text file. The example filters all records containing the string ``INFO``. Any other Go compatible regular expression can be used instead of ``INFO``.
 
 ```shell
-% dtail --servers serverlist.txt --files "/var/log/service/*.log" --regex STAT
+% dtail --servers serverlist.txt --grep INFO --files "/var/log/dserver/*.log"
 ```
 
+Hint: you can also provide a comma separated server list, e.g.: `--servers server1.example.org,server2.example.org:PORT,...`.
+
 ![dtail](dtail.gif "Tail example")
 
-You can also use the shorthand version:
+You can also use the shorthand version (omitting the `--files`):
 
 ```shell
-% dtail --servers serverlist.txt --regex STAT "/var/log/service/*.log"
+% dtail --servers serverlist.txt --grep INFO "/var/log/dserver/*.log"
 ```
 
 ## Aggregating logs
 
-To run ad-hoc MapReduce aggregations on newly written log lines, you also must add a query. The following example follows all remote log lines and prints out every 5 seconds the top 10 servers with the most average free memory. To run a MapReduce query across log lines written in the past, please use the ``dmap`` command instead.
+To run ad-hoc MapReduce aggregations on newly written log lines, you also must add a query. The following example follows all remote log lines and prints out every few seconds the top 10 servers with the most average free memory. To run a MapReduce query across log lines written in the past, please use the ``dmap`` command instead.
 
 ```shell
-% dtail --servers serverlist.txt  \
-    --query 'select avg(memfree), $hostname from MCVMSTATS group by $hostname order by avg(memfree) limit 10 interval 5' \
-    --files '/var/log/service/*.log'
+% dtail --servers serverlist.txt \
+    --files '/var/log/dserver/*.log' \
+    --query 'from STATS select sum($goroutines),sum($cgocalls),last($time),max(lifetimeConnections)'
 ```
 
 For MapReduce queries to work, you have to ensure that DTail supports your log format. You can either use the ones already defined in ``internal/mapr/log format`` or add an extension to support a custom log format.
@@ -38,11 +40,20 @@ For MapReduce queries to work, you have to ensure that DTail supports your log f
 You can also use the shorthand version:
 
 ```shell
-% dtail --servers serverlist.txt  \
-    'select avg(memfree), $hostname from MCVMSTATS group by $hostname order by avg(memfree) limit 10 interval 5' \
-    '/var/log/service/*.log'
+% dtail --servers serverlist.txt \
+    --files '/var/log/dserver/*.log' \
+    'from STATS select sum($goroutines),sum($cgocalls),last($time),max(lifetimeConnections)'
+```
+Here is yet another example:
+
+```shell
+% dtail --servers serverlist.txt \
+    --files '/var/log/dserver/*.log' \
+    --query 'from STATS select $hostname,max($goroutines),max($cgocalls),$loadavg,lifetimeConnections group by $hostname order by max($cgocalls)'
 ```
 
+![dtail-map](dtail-map2.gif "Tail mapreduce example 2")
+
 # How to use ``dcat``
 
 The following example demonstrates how to cat files (display the full content of the files) of multiple servers at once. The servers are provided as a comma-separated list this time.
-- 
cgit v1.2.3


From e11a4b5bc7960ee7f20cabc7fd7810572d934806 Mon Sep 17 00:00:00 2001
From: Paul Buetow <paul@buetow.org>
Date: Sun, 7 Nov 2021 13:20:14 +0200
Subject: update dcat.gif example

---
 doc/examples.md | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

(limited to 'doc/examples.md')

diff --git a/doc/examples.md b/doc/examples.md
index 584a9fb..4a08321 100644
--- a/doc/examples.md
+++ b/doc/examples.md
@@ -17,7 +17,7 @@ Hint: you can also provide a comma separated server list, e.g.: `--servers serve
 
 ![dtail](dtail.gif "Tail example")
 
-You can also use the shorthand version (omitting the `--files`):
+Hint: You can also use the shorthand version (omitting the `--files`):
 
 ```shell
 % dtail --servers serverlist.txt --grep INFO "/var/log/dserver/*.log"
@@ -37,7 +37,7 @@ For MapReduce queries to work, you have to ensure that DTail supports your log f
 
 ![dtail-map](dtail-map.gif "Tail mapreduce example")
 
-You can also use the shorthand version:
+Hint: You can also use the shorthand version:
 
 ```shell
 % dtail --servers serverlist.txt \
@@ -56,20 +56,20 @@ Here is yet another example:
 
 # How to use ``dcat``
 
-The following example demonstrates how to cat files (display the full content of the files) of multiple servers at once. The servers are provided as a comma-separated list this time.
+The following example demonstrates how to cat files (display the full content of the files) of multiple servers at once.
+
+As you can see in this example, a DTail client also creates a local log file of all received data in `~/log`. You can also use the `-noColor` and `-plain` flags (they also work with other commands than `dcat`).
 
 ```shell
-% dcat --servers serv-011.lan.example.org,serv-012.lan.example.org,serv-013.lan.example.org \
-    --files /etc/hostname
+% dcat --servers serverlist.txt --files /etc/hostname
 ```
 
 ![dcat](dcat.gif "Cat example")
 
-You can also use the shorthand version:
+Hint: You can also use the shorthand version:
 
 ```shell
-% dcat --servers serv-011.lan.example.org,serv-012.lan.example.org,serv-013.lan.example.org \
-    /etc/hostname
+% dcat --servers serverlist.txt /etc/hostname
 ```
 
 # How to use ``dgrep``
@@ -86,7 +86,6 @@ The following example demonstrates how to grep files (display only the lines whi
 
 You can also use the shorthand version:
 
-TODO: Auto detect that swap is a regex.
 ```shell
 % dgrep --servers <(head -n 20 serverlist.txt) \
     /etc/fstab swap
-- 
cgit v1.2.3


From bbaf2d95f75002045e49b89f7abb6ad04e2a096a Mon Sep 17 00:00:00 2001
From: Paul Buetow <paul@buetow.org>
Date: Sun, 7 Nov 2021 13:45:25 +0200
Subject: update dgrep.gif example

---
 doc/examples.md | 15 +++++----------
 1 file changed, 5 insertions(+), 10 deletions(-)

(limited to 'doc/examples.md')

diff --git a/doc/examples.md b/doc/examples.md
index 4a08321..1fb4f41 100644
--- a/doc/examples.md
+++ b/doc/examples.md
@@ -74,22 +74,17 @@ Hint: You can also use the shorthand version:
 
 # How to use ``dgrep``
 
-The following example demonstrates how to grep files (display only the lines which match a given regular expression) of multiple servers at once. In this example, we look after the swap partition in ``/etc/fstab``. We do that only on the first 20 servers from ``serverlist.txt``. ``dgrep`` is also very useful for searching log files of the past.
+The following example demonstrates how to grep files (display only the lines which match a given regular expression) of multiple servers at once. In this example, we look after some entries in ``/etc/passwd``.  This time, we don't provide the server list via an file but rather via a comma separated list directly on the command line. We also explore the `-before`, `-after` and `-max` flags.
 
 ```shell
-% dgrep --servers <(head -n 20 serverlist.txt) \
-    --files /etc/fstab \
-    --regex swap
+% dgrep --servers server1.example.org:2223 \
+    --files /etc/passwd \
+    --regex nologin
 ```
 
 ![dgrep](dgrep.gif "Grep example")
 
-You can also use the shorthand version:
-
-```shell
-% dgrep --servers <(head -n 20 serverlist.txt) \
-    /etc/fstab swap
-```
+Hint: `-regex` is an alias for `-grep`.
 
 # How to use ``dmap``
 
-- 
cgit v1.2.3


From d9baf981c567e61c57da49cc01f5e1ef2997769f Mon Sep 17 00:00:00 2001
From: Paul Buetow <paul@buetow.org>
Date: Sun, 7 Nov 2021 14:18:52 +0200
Subject: update dmap.gif example

---
 doc/examples.md | 20 ++++++--------------
 1 file changed, 6 insertions(+), 14 deletions(-)

(limited to 'doc/examples.md')

diff --git a/doc/examples.md b/doc/examples.md
index 1fb4f41..5dd898d 100644
--- a/doc/examples.md
+++ b/doc/examples.md
@@ -25,7 +25,7 @@ Hint: You can also use the shorthand version (omitting the `--files`):
 
 ## Aggregating logs
 
-To run ad-hoc MapReduce aggregations on newly written log lines, you also must add a query. The following example follows all remote log lines and prints out every few seconds the top 10 servers with the most average free memory. To run a MapReduce query across log lines written in the past, please use the ``dmap`` command instead.
+To run ad-hoc MapReduce aggregations on newly written log lines you must add a query. The following example follows all remote log lines and prints out every few seconds the top 10 servers with the most average free memory. To run a MapReduce query across log lines written in the past, please use the ``dmap`` command instead.
 
 ```shell
 % dtail --servers serverlist.txt \
@@ -88,22 +88,14 @@ Hint: `-regex` is an alias for `-grep`.
 
 # How to use ``dmap``
 
-To run a MapReduce aggregation over logs written in the past, the ``dmap`` command can be used. For example, the following command aggregates all MapReduce fields of all the records and calculates the average memory free grouped by day of the month, hour, minute and the server hostname. ``dmap`` will print interim results every few seconds. The final product, however, will be written to file ``mapreduce.csv``.
+To run a MapReduce aggregation over logs written in the past, the ``dmap`` command has be used. Fhe following example aggregates all MapReduce fields ``dmap`` will print interim results every few seconds. You can also write the result to an CSV file by adding `outfile result.csv` to the query.
 
 ```shell
-% dmap --servers serv-011.lan.example.org,serv-012.lan.example.org,serv-013.lan.example.org,serv-021.lan.example.org,serv-022.lan.example.org,serv-023.lan.example.org \
-    --query 'select avg(memfree), $day, $hour, $minute, $hostname from MCVMSTATS group by $day, $hour, $minute, $hostname order by avg(memfree) limit 10 outfile mapreduce.csv' \
-    --files "/var/log/service/*.log"
+% dmap --servers serverlist.txt \
+    --files '/var/log/dserver/*.log'
+    --query 'from STATS select $hostname,max($goroutines),max($cgocalls),$loadavg,lifetimeConnections group by $hostname order by max($cgocalls)'
 ```
 
-Remember: For that to work, you have to make sure that DTail supports your log format. You can either use the ones already defined in ``internal/mapr/log format`` or add an extension to support a custom log format.
+Remember: For that to work, you have to make sure that DTail supports your log format. You can either use the ones already defined in ``internal/mapr/logformat`` or add an extension to support a custom log format. Te example here works out of the box though, as DTail understands its own log format already. 
 
 ![dmap](dmap.gif "DMap example")
-
-You can also use the shorthand version:
-
-```shell
-% dmap --servers serv-011.lan.example.org,serv-012.lan.example.org,serv-013.lan.example.org,serv-021.lan.example.org,serv-022.lan.example.org,serv-023.lan.example.org \
-    'select avg(memfree), $day, $hour, $minute, $hostname from MCVMSTATS group by $day, $hour, $minute, $hostname order by avg(memfree) limit 10 outfile mapreduce.csv' \
-    "/var/log/service/*.log"
-```
-- 
cgit v1.2.3


From 84166ab05f72ed23ada3802fc0baf0cec5eb1233 Mon Sep 17 00:00:00 2001
From: Paul Buetow <paul@buetow.org>
Date: Sun, 7 Nov 2021 14:43:21 +0200
Subject: add serverless examples

---
 doc/examples.md | 102 +++++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 86 insertions(+), 16 deletions(-)

(limited to 'doc/examples.md')

diff --git a/doc/examples.md b/doc/examples.md
index 5dd898d..803b1af 100644
--- a/doc/examples.md
+++ b/doc/examples.md
@@ -1,31 +1,40 @@
 Examples
 ========
 
-This page demonstrates the primary usage of DTail. Please also see ``dtail --help`` for more available options.
+This page demonstrates the primary usage of DTail. Please also see `dtail --help` for more available options.
 
-# How to use ``dtail``
+## Table of contents
 
-## Tailing logs
+* How to use `dtail` to follow logs
+* How to use `dtail` to aggregate logs
+* How to use `dcat`
+* How to use `dgrep`
+* How to use `dmap`
+* How to use the DTail serverless mode
 
-The following example demonstrates how to follow logs of multiple servers at once. The server list is provided as a flat text file. The example filters all records containing the string ``INFO``. Any other Go compatible regular expression can be used instead of ``INFO``.
+## How to use `dtail`
+
+### Following logs
+
+The following example demonstrates how to follow logs of multiple servers at once. The server list is provided as a flat text file. The example filters all records containing the string `INFO` Any other Go compatible regular expression can be used instead of `INFO`
 
 ```shell
 % dtail --servers serverlist.txt --grep INFO --files "/var/log/dserver/*.log"
 ```
 
-Hint: you can also provide a comma separated server list, e.g.: `--servers server1.example.org,server2.example.org:PORT,...`.
+Hint: you can also provide a comma separated server list, e.g.: `servers server1.example.org,server2.example.org:PORT,...`
 
 ![dtail](dtail.gif "Tail example")
 
-Hint: You can also use the shorthand version (omitting the `--files`):
+Hint: You can also use the shorthand version (omitting the `files`
 
 ```shell
 % dtail --servers serverlist.txt --grep INFO "/var/log/dserver/*.log"
 ```
 
-## Aggregating logs
+### Aggregating logs
 
-To run ad-hoc MapReduce aggregations on newly written log lines you must add a query. The following example follows all remote log lines and prints out every few seconds the top 10 servers with the most average free memory. To run a MapReduce query across log lines written in the past, please use the ``dmap`` command instead.
+To run ad-hoc map-reduce aggregations on newly written log lines you must add a query. The following example follows all remote log lines and prints out every few seconds the top 10 servers with the most average free memory. To run a map-reduce query across log lines written in the past, please use the `dmap` command instead.
 
 ```shell
 % dtail --servers serverlist.txt \
@@ -33,7 +42,7 @@ To run ad-hoc MapReduce aggregations on newly written log lines you must add a q
     --query 'from STATS select sum($goroutines),sum($cgocalls),last($time),max(lifetimeConnections)'
 ```
 
-For MapReduce queries to work, you have to ensure that DTail supports your log format. You can either use the ones already defined in ``internal/mapr/log format`` or add an extension to support a custom log format.
+For map-reduce queries to work, you have to ensure that DTail supports your log format. You can either use the ones already defined in `internal/mapr/log format` or add an extension to support a custom log format.
 
 ![dtail-map](dtail-map.gif "Tail mapreduce example")
 
@@ -54,11 +63,11 @@ Here is yet another example:
 
 ![dtail-map](dtail-map2.gif "Tail mapreduce example 2")
 
-# How to use ``dcat``
+## How to use `dcat`
 
 The following example demonstrates how to cat files (display the full content of the files) of multiple servers at once.
 
-As you can see in this example, a DTail client also creates a local log file of all received data in `~/log`. You can also use the `-noColor` and `-plain` flags (they also work with other commands than `dcat`).
+As you can see in this example, a DTail client also creates a local log file of all received data in `log` You can also use the `noColor` and `-plain` flags (they also work with other commands than `dcat`).
 
 ```shell
 % dcat --servers serverlist.txt --files /etc/hostname
@@ -72,9 +81,9 @@ Hint: You can also use the shorthand version:
 % dcat --servers serverlist.txt /etc/hostname
 ```
 
-# How to use ``dgrep``
+## How to use `dgrep`
 
-The following example demonstrates how to grep files (display only the lines which match a given regular expression) of multiple servers at once. In this example, we look after some entries in ``/etc/passwd``.  This time, we don't provide the server list via an file but rather via a comma separated list directly on the command line. We also explore the `-before`, `-after` and `-max` flags.
+The following example demonstrates how to grep files (display only the lines which match a given regular expression) of multiple servers at once. In this example, we look after some entries in `etc/passwd`  This time, we don't provide the server list via an file but rather via a comma separated list directly on the command line. We also explore the `-before`, `-after` and `-max` flags.
 
 ```shell
 % dgrep --servers server1.example.org:2223 \
@@ -82,13 +91,15 @@ The following example demonstrates how to grep files (display only the lines whi
     --regex nologin
 ```
 
+Generally, this is also a very useful way to search historic application logs.
+
 ![dgrep](dgrep.gif "Grep example")
 
 Hint: `-regex` is an alias for `-grep`.
 
-# How to use ``dmap``
+## How to use `dmap`
 
-To run a MapReduce aggregation over logs written in the past, the ``dmap`` command has be used. Fhe following example aggregates all MapReduce fields ``dmap`` will print interim results every few seconds. You can also write the result to an CSV file by adding `outfile result.csv` to the query.
+To run a map-reduce aggregation over logs written in the past, the `dmap` command has be used. The following example aggregates all map-reduce fields `dmap` will print interim results every few seconds. You can also write the result to an CSV file by adding `outfile result.csv` to the query.
 
 ```shell
 % dmap --servers serverlist.txt \
@@ -96,6 +107,65 @@ To run a MapReduce aggregation over logs written in the past, the ``dmap`` comma
     --query 'from STATS select $hostname,max($goroutines),max($cgocalls),$loadavg,lifetimeConnections group by $hostname order by max($cgocalls)'
 ```
 
-Remember: For that to work, you have to make sure that DTail supports your log format. You can either use the ones already defined in ``internal/mapr/logformat`` or add an extension to support a custom log format. Te example here works out of the box though, as DTail understands its own log format already. 
+Remember: For that to work, you have to make sure that DTail supports your log format. You can either use the ones already defined in `internal/mapr/logformat` or add an extension to support a custom log format. Te example here works out of the box though, as DTail understands its own log format already. 
 
 ![dmap](dmap.gif "DMap example")
+
+## How to use the DTail serverless mode
+
+Until now, all examples so far assumed to have remote server(s) to connect to. That makes sense, as after all DTail is a *distributed* tool. However, there are circumstances where you don't really need to connect to a server remotely. For example, you already have a login shell open to the server an all what you want is to run some queries directly on local log files.
+
+All commands shown so far also work in a serverless mode. All what needs to be done is to omit a server list. The DTail client then starts in serverless mode. 
+
+### Serverless map-reduce query
+
+The following `dmap` example is the same as the previously shown one, but the difference is that it operates on a local log file directly:
+
+```shell
+% dmap --files /var/log/dserver/dserver.log
+    --query 'from STATS select $hostname,max($goroutines),max($cgocalls),$loadavg,lifetimeConnections group by $hostname order by max($cgocalls)'
+```
+
+As a shorthand version the following command can be used:
+
+```shell
+% dmap 'from STATS select $hostname,max($goroutines),max($cgocalls),$loadavg,lifetimeConnections group by $hostname order by max($cgocalls)' /var/log/dsever/dserver.log
+```
+
+You can also use a file input pipe as follows:
+
+```shell
+% cat /var/log/dserver/dserver.log | \
+    dmap 'from STATS select $hostname,max($goroutines),max($cgocalls),$loadavg,lifetimeConnections group by $hostname order by max($cgocalls)'
+```
+
+### Other serverless commands
+
+It works transparently with all other DTail commands. Here are some examples:
+
+```shell
+dtail /var/log/dserver/dserver.log
+```
+
+```shell
+dtail --logLevel trace /var/log/dserver/dserver.log
+```
+
+```shell
+dcat /etc/passwd
+```
+
+```shell
+dcat --plain /etc/passwd > /etc/test
+# Should show no differences.
+diff /etc/test /etc/passwd 
+```
+
+```shell
+dgrep --regex ERROR --files /var/log/dserver/dsever.log
+```
+
+```shell
+dgrep --before 10 --after 10 --max 10 --grep ERROR \
+  /var/log/dserver/dsever.log
+```
-- 
cgit v1.2.3


From 3e05d5657c7c26a8d73c7be2f83a1d701ba896c7 Mon Sep 17 00:00:00 2001
From: Paul Buetow <paul@buetow.org>
Date: Sun, 7 Nov 2021 14:58:13 +0200
Subject: Finetune example docs

---
 doc/examples.md | 35 +++++++++++++++++++----------------
 1 file changed, 19 insertions(+), 16 deletions(-)

(limited to 'doc/examples.md')

diff --git a/doc/examples.md b/doc/examples.md
index 803b1af..2d57cbf 100644
--- a/doc/examples.md
+++ b/doc/examples.md
@@ -1,7 +1,7 @@
 Examples
 ========
 
-This page demonstrates the primary usage of DTail. Please also see `dtail --help` for more available options.
+This page demonstrates the primary usage of DTail. Please also see `--help` for more available options.
 
 ## Table of contents
 
@@ -16,7 +16,7 @@ This page demonstrates the primary usage of DTail. Please also see `dtail --help
 
 ### Following logs
 
-The following example demonstrates how to follow logs of multiple servers at once. The server list is provided as a flat text file. The example filters all records containing the string `INFO` Any other Go compatible regular expression can be used instead of `INFO`
+The following example demonstrates how to follow logs of multiple servers at once. The server list is provided as a flat text file. The example filters all records containing the string `INFO`. Any other Go compatible regular expression can also be used instead of `INFO`.
 
 ```shell
 % dtail --servers serverlist.txt --grep INFO --files "/var/log/dserver/*.log"
@@ -26,7 +26,7 @@ Hint: you can also provide a comma separated server list, e.g.: `servers server1
 
 ![dtail](dtail.gif "Tail example")
 
-Hint: You can also use the shorthand version (omitting the `files`
+Hint: You can also use the shorthand version (omitting the `--files`)
 
 ```shell
 % dtail --servers serverlist.txt --grep INFO "/var/log/dserver/*.log"
@@ -34,7 +34,9 @@ Hint: You can also use the shorthand version (omitting the `files`
 
 ### Aggregating logs
 
-To run ad-hoc map-reduce aggregations on newly written log lines you must add a query. The following example follows all remote log lines and prints out every few seconds the top 10 servers with the most average free memory. To run a map-reduce query across log lines written in the past, please use the `dmap` command instead.
+To run ad-hoc map-reduce aggregations on newly written log lines you must add a query. The following example follows all remote log lines and prints out every few seconds the result to standard output.
+
+Hint: To run a map-reduce query across log lines written in the past, please use the `dmap` command instead.
 
 ```shell
 % dtail --servers serverlist.txt \
@@ -42,7 +44,7 @@ To run ad-hoc map-reduce aggregations on newly written log lines you must add a
     --query 'from STATS select sum($goroutines),sum($cgocalls),last($time),max(lifetimeConnections)'
 ```
 
-For map-reduce queries to work, you have to ensure that DTail supports your log format. You can either use the ones already defined in `internal/mapr/log format` or add an extension to support a custom log format.
+Beware: For map-reduce queries to work, you have to ensure that DTail supports your log format. You can either use the ones already defined in `internal/mapr/logformat` or add an extension to support a custom log format.
 
 ![dtail-map](dtail-map.gif "Tail mapreduce example")
 
@@ -53,7 +55,7 @@ Hint: You can also use the shorthand version:
     --files '/var/log/dserver/*.log' \
     'from STATS select sum($goroutines),sum($cgocalls),last($time),max(lifetimeConnections)'
 ```
-Here is yet another example:
+Here is another example:
 
 ```shell
 % dtail --servers serverlist.txt \
@@ -67,7 +69,7 @@ Here is yet another example:
 
 The following example demonstrates how to cat files (display the full content of the files) of multiple servers at once.
 
-As you can see in this example, a DTail client also creates a local log file of all received data in `log` You can also use the `noColor` and `-plain` flags (they also work with other commands than `dcat`).
+As you can see in this example, a DTail client also creates a local log file of all received data in `~/log`. You can also use the `noColor` and `-plain` flags (this all also work with other DTail commands than `dcat`).
 
 ```shell
 % dcat --servers serverlist.txt --files /etc/hostname
@@ -83,7 +85,7 @@ Hint: You can also use the shorthand version:
 
 ## How to use `dgrep`
 
-The following example demonstrates how to grep files (display only the lines which match a given regular expression) of multiple servers at once. In this example, we look after some entries in `etc/passwd`  This time, we don't provide the server list via an file but rather via a comma separated list directly on the command line. We also explore the `-before`, `-after` and `-max` flags.
+The following example demonstrates how to grep files (display only the lines which match a given regular expression) of multiple servers at once. In this example, we look after some entries in `/etc/passwd`  This time, we don't provide the server list via an file but rather via a comma separated list directly on the command line. We also explore the `-before`, `-after` and `-max` flags (see animation).
 
 ```shell
 % dgrep --servers server1.example.org:2223 \
@@ -91,7 +93,7 @@ The following example demonstrates how to grep files (display only the lines whi
     --regex nologin
 ```
 
-Generally, this is also a very useful way to search historic application logs.
+Generally, `dgrep` is also a very useful way to search historic application logs for certain content.
 
 ![dgrep](dgrep.gif "Grep example")
 
@@ -99,7 +101,7 @@ Hint: `-regex` is an alias for `-grep`.
 
 ## How to use `dmap`
 
-To run a map-reduce aggregation over logs written in the past, the `dmap` command has be used. The following example aggregates all map-reduce fields `dmap` will print interim results every few seconds. You can also write the result to an CSV file by adding `outfile result.csv` to the query.
+To run a map-reduce aggregation over logs written in the past, the `dmap` command can be used. The following example aggregates all map-reduce fields `dmap` will print interim results every few seconds. You can also write the result to an CSV file by adding `outfile result.csv` to the query.
 
 ```shell
 % dmap --servers serverlist.txt \
@@ -107,15 +109,17 @@ To run a map-reduce aggregation over logs written in the past, the `dmap` comman
     --query 'from STATS select $hostname,max($goroutines),max($cgocalls),$loadavg,lifetimeConnections group by $hostname order by max($cgocalls)'
 ```
 
-Remember: For that to work, you have to make sure that DTail supports your log format. You can either use the ones already defined in `internal/mapr/logformat` or add an extension to support a custom log format. Te example here works out of the box though, as DTail understands its own log format already. 
+Remember: For that to work, you have to make sure that DTail supports your log format. You can either use the ones already defined in `internal/mapr/logformat` or add an extension to support a custom log format. The example here works out of the box though, as DTail understands its own log format already. 
 
 ![dmap](dmap.gif "DMap example")
 
 ## How to use the DTail serverless mode
 
-Until now, all examples so far assumed to have remote server(s) to connect to. That makes sense, as after all DTail is a *distributed* tool. However, there are circumstances where you don't really need to connect to a server remotely. For example, you already have a login shell open to the server an all what you want is to run some queries directly on local log files.
+Until now, all examples so far required to have remote server(s) to connect to. That makes sense, as after all DTail is a *distributed* tool. However, there are circumstances where you don't really need to connect to a server remotely. For example, you already have a login shell open to the server an all what you want is to run some queries directly on local log files.
+
+The serverless mode does not require any `dserver` up and running and therefore there is no networking/SSH involved. 
 
-All commands shown so far also work in a serverless mode. All what needs to be done is to omit a server list. The DTail client then starts in serverless mode. 
+All commands shown so far also work in a serverless mode. All what needs to be done is to omit a server list. The DTail client then starts in serverless mode.
 
 ### Serverless map-reduce query
 
@@ -141,7 +145,7 @@ You can also use a file input pipe as follows:
 
 ### Other serverless commands
 
-It works transparently with all other DTail commands. Here are some examples:
+The serverless mode works transparently with all other DTail commands. Here are some examples:
 
 ```shell
 dtail /var/log/dserver/dserver.log
@@ -166,6 +170,5 @@ dgrep --regex ERROR --files /var/log/dserver/dsever.log
 ```
 
 ```shell
-dgrep --before 10 --after 10 --max 10 --grep ERROR \
-  /var/log/dserver/dsever.log
+dgrep --before 10 --after 10 --max 10 --grep ERROR /var/log/dserver/dsever.log
 ```
-- 
cgit v1.2.3


From 242d419f1b31755d1d1b3d1a1fd0e7bf61f7768e Mon Sep 17 00:00:00 2001
From: Paul Buetow <paul@buetow.org>
Date: Sun, 12 Dec 2021 21:21:14 +0000
Subject: link from example docs to query language and log format docs

---
 doc/examples.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/examples.md')

diff --git a/doc/examples.md b/doc/examples.md
index 2d57cbf..56744f5 100644
--- a/doc/examples.md
+++ b/doc/examples.md
@@ -44,7 +44,7 @@ Hint: To run a map-reduce query across log lines written in the past, please use
     --query 'from STATS select sum($goroutines),sum($cgocalls),last($time),max(lifetimeConnections)'
 ```
 
-Beware: For map-reduce queries to work, you have to ensure that DTail supports your log format. You can either use the ones already defined in `internal/mapr/logformat` or add an extension to support a custom log format.
+Beware: For map-reduce queries to work, you have to ensure that DTail supports your log format. Check out the [query language](./querylanguage.md) and [log formats](./logformats.md) for more information.
 
 ![dtail-map](dtail-map.gif "Tail mapreduce example")
 
-- 
cgit v1.2.3