[DOCS] EQL: Add collapsible sections to EQL tutorial docs (#56235)

Adds collapsible sections to the snippet examples of the EQL tutorial
docs.

Also adds a leading slash to EQL API snippet examples.
This commit is contained in:
James Rodewig 2020-05-05 16:29:11 -04:00
parent e7df8b388e
commit dac4ed282e
2 changed files with 36 additions and 18 deletions

View File

@ -16,7 +16,7 @@ In {es}, EQL assumes each document in an index corresponds to an event.
////
[source,console]
----
PUT my_index/_bulk?refresh
PUT /my_index/_bulk?refresh
{"index":{"_index" : "my_index", "_id" : "1"}}
{ "@timestamp": "2020-12-06T11:04:05.000Z", "agent": { "id": "8a4f500d" }, "event": { "category": "process" }, "process": { "name": "cmd.exe", "path": "C:\\Windows\\System32\\cmd.exe" } }
{"index":{"_index" : "my_index", "_id" : "2"}}
@ -44,9 +44,9 @@ GET my_index/_eql/search
[[eql-search-api-request]]
==== {api-request-title}
`GET <index>/_eql/search`
`GET /<index>/_eql/search`
`POST <index>/_eql/search`
`POST /<index>/_eql/search`
[[eql-search-api-prereqs]]
==== {api-prereq-title}

View File

@ -6,8 +6,13 @@
experimental::[]
To start using EQL in {es}, first ensure your event data meets
<<eql-requirements,EQL requirements>>. Then ingest or add the data to an {es}
index.
<<eql-requirements,EQL requirements>>. You can then use the <<eql-search-api,EQL
search API>> to search event data stored in one or more {es} indices.
.*Example*
[%collapsible]
====
To get started, ingest or add the data to an {es} index.
The following <<docs-bulk,bulk API>> request adds some example log data to the
`sec_logs` index. This log data follows the {ecs-ref}[Elastic Common Schema
@ -15,7 +20,7 @@ The following <<docs-bulk,bulk API>> request adds some example log data to the
[source,console]
----
PUT sec_logs/_bulk?refresh
PUT /sec_logs/_bulk?refresh
{"index":{"_index" : "sec_logs", "_id" : "1"}}
{ "@timestamp": "2020-12-06T11:04:05.000Z", "agent": { "id": "8a4f500d" }, "event": { "category": "process" }, "process": { "name": "cmd.exe", "path": "C:\\Windows\\System32\\cmd.exe" } }
{"index":{"_index" : "sec_logs", "_id" : "2"}}
@ -30,13 +35,13 @@ PUT sec_logs/_bulk?refresh
// TESTSETUP
[TIP]
====
=====
You also can set up {beats-ref}/getting-started.html[{beats}], such as
{auditbeat-ref}/auditbeat-getting-started.html[{auditbeat}] or
{winlogbeat-ref}/winlogbeat-getting-started.html[{winlogbeat}], to automatically
send and index your event data in {es}. See
{beats-ref}/getting-started.html[Getting started with {beats}].
====
=====
You can now use the EQL search API to search this index using an EQL query.
@ -46,7 +51,7 @@ specified in the `query` parameter. The EQL query matches events with an
[source,console]
----
GET sec_logs/_eql/search
GET /sec_logs/_eql/search
{
"query": """
process where process.name == "cmd.exe"
@ -122,6 +127,7 @@ https://en.wikipedia.org/wiki/Unix_time[Unix epoch], in ascending order.
}
----
// TESTRESPONSE[s/"took": 60/"took": $body.took/]
====
[discrete]
[[eql-search-specify-event-category-field]]
@ -131,12 +137,15 @@ The EQL search API uses `event.category` as the required
<<eql-required-fields,event category field>> by default. You can use the
`event_category_field` parameter to specify another event category field.
For example, the following request specifies `file.type` as the event category
.*Example*
[%collapsible]
====
The following request specifies `file.type` as the event category
field.
[source,console]
----
GET sec_logs/_eql/search
GET /sec_logs/_eql/search
{
"event_category_field": "file.type",
"query": """
@ -144,6 +153,7 @@ GET sec_logs/_eql/search
"""
}
----
====
[discrete]
[[eql-search-specify-timestamp-field]]
@ -153,12 +163,15 @@ The EQL search API uses `@timestamp` as the required <<eql-required-fields,event
timestamp field>> by default. You can use the `timestamp_field` parameter to
specify another timestamp field.
For example, the following request specifies `file.accessed` as the event
.*Example*
[%collapsible]
====
The following request specifies `file.accessed` as the event
timestamp field.
[source,console]
----
GET sec_logs/_eql/search
GET /sec_logs/_eql/search
{
"timestamp_field": "file.accessed",
"query": """
@ -166,23 +179,27 @@ GET sec_logs/_eql/search
"""
}
----
====
[discrete]
[[eql-search-filter-query-dsl]]
=== Filter using query DSL
You can use the `filter` parameter to specify an additional query using
<<query-dsl,query DSL>>. This query filters the documents on which the EQL query
runs.
You can use the EQL search API's `filter` parameter to specify an additional
query using <<query-dsl,query DSL>>. This query filters the documents on which
the EQL query runs.
For example, the following request uses a `range` query to filter the `sec_logs`
.*Example*
[%collapsible]
====
The following request uses a `range` query to filter the `sec_logs`
index down to only documents with a `file.size` value greater than `1` but less
than `1000000` bytes. The EQL query in `query` parameter then runs on these
filtered documents.
[source,console]
----
GET sec_logs/_eql/search
GET /sec_logs/_eql/search
{
"filter": {
"range" : {
@ -197,3 +214,4 @@ GET sec_logs/_eql/search
"""
}
----
====