[DOCS] Creates a data frame examples page

docs/en/stack/data-frames/dataframe-examples.asciidoc

@@ -0,0 +1,161 @@
+[role="xpack"]
+[testenv="basic"]
+[[dataframe-examples]]
+== {dataframe-cap} examples
+++++
+<titleabbrev>Examples</titleabbrev>
+++++
+
+beta[]
+
+This page provides examples of how to use {dataframe-transforms} to derive useful 
+insights from your data. For a more detailed, step-by-step example, see 
+<<ecommerce-dataframes,Transforming your data with {dataframes}>>.
+
+* <<example-clientips>>
+
+
+[float]
+[[example-clientips]]
+=== Finding suspicious client IPs by using scripted metrics
+
+With {dataframe-transforms}, you can use 
+{ref}/search-aggregations-metrics-scripted-metric-aggregation.html[scripted 
+metric aggregations] on your data. These aggregations are flexible and make 
+it possible to perform very complex processing. Let's use scripted metrics to 
+identify suspicious client IPs in the web log 
+{kibana-ref}/add-sample-data.html[{kib} sample dataset].
+
+The example below transforms web log data into an entity-centric index where the 
+entity is `clientip`.
+
+[source,js]
+----------------------------------
+POST _data_frame/transforms/_preview
+{
+  "source": {
+    "index": "kibana_sample_data_logs",
+    "query": { <1>
+      "range" : {
+        "timestamp" : {
+          "gte" : "now-30d/d"
+        }
+      }
+    }
+  },
+  "dest" : {
+    "index" : "sample_weblogs_by_clientip"
+  },  
+  "pivot": {
+    "group_by": {  <2>
+      "clientip": { "terms": { "field": "clientip" } }
+      },
+    "aggregations": {
+      "url_dc": { "cardinality": { "field": "url.keyword" }},
+      "bytes_sum": { "sum": { "field": "bytes" }},
+      "geo.src_dc": { "cardinality": { "field": "geo.src" }},
+      "agent_dc": { "cardinality": { "field": "agent.keyword" }},
+      "geo.dest_dc": { "cardinality": { "field": "geo.dest" }},
+      "responses.total": { "value_count": { "field": "timestamp" }},
+      "responses.counts": { <3>
+        "scripted_metric": { 
+          "init_script": "state.responses = ['error':0L,'success':0L,'other':0L]",
+          "map_script": """
+            def code = doc['response.keyword'].value;
+            if (code.startsWith('5') || code.startsWith('4')) {
+              state.responses.error += 1 ;
+            } else if(code.startsWith('2')) {
+              state.responses.success += 1;
+            } else {
+              state.responses.other += 1;
+            }
+            """,
+          "combine_script": "state.responses",
+          "reduce_script": """
+            def counts = ['error': 0L, 'success': 0L, 'other': 0L];
+            for (responses in states) {
+              counts.error += responses['error'];
+              counts.success += responses['success'];
+              counts.other += responses['other'];
+            }
+            return counts;
+            """
+          }
+        },
+      "timestamp.min": { "min": { "field": "timestamp" }},
+      "timestamp.max": { "max": { "field": "timestamp" }},
+      "timestamp.duration_ms": { <4>
+        "bucket_script": {
+          "buckets_path": {
+            "min_time": "timestamp.min.value",
+            "max_time": "timestamp.max.value"
+          },
+          "script": "(params.max_time - params.min_time)"
+        }
+      }
+    }
+  }
+}
+----------------------------------
+// CONSOLE
+// TEST[skip:SETUP]
+
+<1> This range query limits the transform to documents that are within the 
+last 30 days at the point in time the {dataframe-transform} is started.
+<2> The data is grouped by the `clientip` field. 
+<3> This `scripted_metric` performs a distributed operation on the web log data 
+to count specific types of HTTP responses (error, success, and other).
+<4> This `bucket_script` calculates the duration of the `clientip` access based 
+on the results of the aggregation.
+
+In this example, the API returns the following response (note that this example 
+contains the response partially and shows only the first document object):
+
+[source,js]
+----------------------------------
+{
+  "preview" : [
+    {
+      "geo" : {
+        "src_dc" : 12.0,
+        "dest_dc" : 9.0
+      },
+      "clientip" : "0.72.176.46",
+      "agent_dc" : 3.0,
+      "responses" : {
+        "total" : 14.0,
+        "counts" : {
+          "other" : 0,
+          "success" : 14,
+          "error" : 0
+        }
+      },
+      "bytes_sum" : 74808.0,
+      "timestamp" : {
+        "duration_ms" : 4.919943239E9,
+        "min" : "2019-06-17T07:51:57.333Z",
+        "max" : "2019-08-13T06:31:00.572Z"
+      },
+      "url_dc" : 11.0
+    },
+    ...
+  }
+----------------------------------  
+// CONSOLE
+// TEST[skip:SETUP]
+
+This {dataframe-transform} makes it easier to answer questions such as:
+
+* Which client IPs are transferring the most amounts of data?
+  (Based on the `"bytes_sum": { "sum": { "field": "bytes" }},` aggregation.)
+
+* Which client IPs are interacting with a high number of different URLs?
+  (Based on the `"url_dc": { "cardinality": { "field": "url.keyword" }},` 
+  aggregation.)
+
+* Which client IPs have high error rates?
+  (Based on the `scripted_metric` aggregation.)
+
+* Which client IPs are interacting with a high number of destination countries?
+  (Based on the `"geo.dest_dc": { "cardinality": { "field": "geo.dest" }},` 
+  aggregation.)

docs/en/stack/data-frames/index.asciidoc

@@ -1,3 +1,4 @@
 include::dataframes.asciidoc[]
 include::ecommerce-example.asciidoc[]
-include::api-quickref.asciidoc[]
+include::api-quickref.asciidoc[]
+include::dataframe-examples.asciidoc[]