Skip to content

Commit

Permalink
Cleanup Agent docs (#22510) (#22559)
Browse files Browse the repository at this point in the history
* Remove unnecessary anchor

* Remove enroll widget that's no longer used

* Break dynamic input config docs into several files

* Make sure standalone content is moved over

* Indicate that systemd is required on Linux

* Update note to reflect cloud UI change

* Fix enrollment command on deb/rpm

* Correct uninstall docs

* Commenting out upgrade command because it's not supported in 7.10

* Add upgrade CLI content back in

* Fix upgrade content to show fleet steps

* Add upgrade image
  • Loading branch information
dedemorton authored Nov 11, 2020
1 parent d242a6d commit be4f938
Show file tree
Hide file tree
Showing 19 changed files with 899 additions and 1,154 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -185,7 +185,8 @@ elastic-agent inspect output --output default --program filebeat

Install {agent} permanently on the system and manage it by using the system's
service manager. The agent will start automatically after installation is
complete.
complete. On Linux, this command requires a system and service manager like
systemd.

You must run this command as the root user (or Administrator on Windows)
to write files to the correct locations. This command overwrites the
Expand Down
101 changes: 101 additions & 0 deletions x-pack/elastic-agent/docs/elastic-agent-conditions.asciidoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
[[conditions]]
== Conditions

A condition is a boolean expression that you can specify in your agent policy
to control whether a configuration is applied to the running {agent}. You can
set a condition on inputs, streams, or even processors.

In this example, the input is applied if the host platform is Linux:

[source,yaml]
----
inputs:
- type: logfile
streams:
- paths:
- /var/log/syslog
condition: ${host.platform} == 'linux'
----

In this example, the stream is applied if the host platform is not Windows:

[source,yaml]
----
inputs:
- type: system/metrics
streams:
- metricset: load
data_stream.dataset: system.cpu
condition: ${host.platform} != 'windows'
----

In this example, the processor is applied if the host platform is not Windows:

[source,yaml]
----
inputs:
- type: system/metrics
streams:
- metricset: load
data_stream.dataset: system.cpu
processors:
- add_fields:
fields:
platform: ${host.platform}
to: host
condition: ${host.platform} != 'windows'
----

[[condition-syntax]]
=== Condition syntax

The conditions supported by {agent} are based on {ref}/eql-syntax.html[EQL]'s
boolean syntax, but add support for variables from providers and functions to
manipulate the values.

**Supported operators:**

* Full PEMDAS math support for `+ - * / %`.
* Relational operators `< <= >= > == !=`
* Logical operators `and` and `or`


**Functions:**

* Array functions <<arrayContains-function,`arrayContains`>>
* Dict functions <<hasKey-function,`hasKey`>> (not in EQL)
* Length functions <<length-function,`length`>>
* Math functions <<add-function,`add`>>, <<subtract-function,`subtract`>>,
<<multiply-function,`multiply`>>, <<divide-function,`divide`>>, <<modulo-function,`modulo`>>
* String functions <<concat-function,`concat`>>, <<endsWith-function,`endsWith`>>,
<<indexOf-function,`indexOf`>>, <<match-function,`match`>>, <<number-function,`number`>>,
<<startsWith-function,`startsWith`>>, <<string-function,`string`>>,
<<stringContains-function,`stringContains`>>

**Types:**

* Booleans `true` and `false`

[[condition-examples]]
=== Condition examples

Run only when a specific label is included.

[source,eql]
----
arrayContains(${docker.labels}, 'monitor')
----

Skip on Linux platform or macOS.

[source,eql]
----
${host.platform} != "linux" and ${host.platform} != "darwin"
----

Run only for specific labels.

[source,eql]
----
arrayContains(${docker.labels}, 'monitor') or arrayContains(${docker.label}, 'production')
----
139 changes: 139 additions & 0 deletions x-pack/elastic-agent/docs/elastic-agent-debug-input-configs.asciidoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,139 @@
[[debug-configs]]
== Debugging

To debug configurations that include variable substitution and conditions, use
the `inspect` command. This command shows the configuration that's generated
after variables are replaced and conditions are applied.

First run the {agent}. For this example, we'll use the following agent policy:


[source,yaml]
----
outputs:
default:
type: elasticsearch
hosts: [127.0.0.1:9200]
username: elastic
password: changeme
providers:
local_dynamic:
items:
- vars:
key: value1
processors:
- add_fields:
fields:
custom: match1
target: dynamic
- vars:
key: value2
processors:
- add_fields:
fields:
custom: match2
target: dynamic
- vars:
key: value3
processors:
- add_fields:
fields:
custom: match3
target: dynamic
inputs:
- type: logfile
enabled: true
streams:
- paths:
- /var/log/{{local_dynamic.key}}
----

Then run `elastic-agent inspect` to see the generated configuration. For
example:

[source,shell]
----
$ ./elastic-agent inspect output -o default
[default] filebeat:
filebeat:
inputs:
- index: logs-generic-default
paths:
- /var/log/value1
processors:
- add_fields:
fields:
custom: match1
target: dynamic
- add_fields:
fields:
dataset: generic
namespace: default
type: logs
target: data_stream
- add_fields:
fields:
dataset: generic
target: event
type: log
- index: logs-generic-default
paths:
- /var/log/value2
processors:
- add_fields:
fields:
custom: match2
target: dynamic
- add_fields:
fields:
dataset: generic
namespace: default
type: logs
target: data_stream
- add_fields:
fields:
dataset: generic
target: event
type: log
- index: logs-generic-default
paths:
- /var/log/value3
processors:
- add_fields:
fields:
custom: match3
target: dynamic
- add_fields:
fields:
dataset: generic
namespace: default
type: logs
target: data_stream
- add_fields:
fields:
dataset: generic
target: event
type: log
output:
elasticsearch:
hosts:
- 127.0.0.1:9200
password: changeme
username: elastic
---
[default] FLEET_MONITORING:
output:
elasticsearch:
hosts:
- 127.0.0.1:9200
password: changeme
type: elasticsearch
username: elastic
programs:
- filebeat
---
----
Loading

0 comments on commit be4f938

Please sign in to comment.