youtubebeat/vendor/github.com/elastic/beats/metricbeat/docs/gettingstarted.asciidoc

311 lines
9.9 KiB
Text
Raw Normal View History

2018-11-18 11:08:38 +01:00
[id="{beatname_lc}-getting-started"]
== Getting started with {beatname_uc}
{beatname_uc} helps you monitor your servers and the services they host by
collecting metrics from the operating system and services.
include::../../libbeat/docs/shared-getting-started-intro.asciidoc[]
* <<{beatname_lc}-installation>>
* <<{beatname_lc}-configuration>>
* <<{beatname_lc}-template>>
* <<load-kibana-dashboards>>
* <<{beatname_lc}-starting>>
* <<view-kibana-dashboards>>
* <<setup-repositories>>
[id="{beatname_lc}-installation"]
=== Step 1: Install {beatname_uc}
You should install {beatname_uc} as close as possible to the service you want to
monitor. For example, if you have four servers with MySQL running, it's
recommended that you run {beatname_uc} on each server. This allows {beatname_uc} to
access your service from localhost and does not cause any additional network
traffic or prevent {beatname_uc} from collecting metrics when there are network
problems. Metrics from multiple {beatname_uc} instances will be combined on the
Elasticsearch server.
include::../../libbeat/docs/shared-download-and-install.asciidoc[]
[[deb]]
*deb:*
ifeval::["{release-state}"=="unreleased"]
Version {stack-version} of {beatname_uc} has not yet been released.
endif::[]
ifeval::["{release-state}"!="unreleased"]
["source","sh",subs="attributes"]
------------------------------------------------
curl -L -O https://artifacts.elastic.co/downloads/beats/{beatname_lc}/{beatname_lc}-{version}-amd64.deb
sudo dpkg -i {beatname_lc}-{version}-amd64.deb
------------------------------------------------
endif::[]
[[rpm]]
*rpm:*
ifeval::["{release-state}"=="unreleased"]
Version {stack-version} of {beatname_uc} has not yet been released.
endif::[]
ifeval::["{release-state}"!="unreleased"]
["source","sh",subs="attributes"]
------------------------------------------------
curl -L -O https://artifacts.elastic.co/downloads/beats/{beatname_lc}/{beatname_lc}-{version}-x86_64.rpm
sudo rpm -vi {beatname_lc}-{version}-x86_64.rpm
------------------------------------------------
endif::[]
[[mac]]
*mac:*
ifeval::["{release-state}"=="unreleased"]
Version {stack-version} of {beatname_uc} has not yet been released.
endif::[]
ifeval::["{release-state}"!="unreleased"]
["source","sh",subs="attributes"]
------------------------------------------------
curl -L -O https://artifacts.elastic.co/downloads/beats/{beatname_lc}/{beatname_lc}-{version}-darwin-x86_64.tar.gz
tar xzvf {beatname_lc}-{version}-darwin-x86_64.tar.gz
------------------------------------------------
endif::[]
[[docker]]
*docker:*
ifeval::["{release-state}"=="unreleased"]
Version {stack-version} of {beatname_uc} has not yet been released.
endif::[]
ifeval::["{release-state}"!="unreleased"]
["source", "shell", subs="attributes"]
------------------------------------------------
docker pull {dockerimage}
------------------------------------------------
endif::[]
[[win]]
*win:*
ifeval::["{release-state}"=="unreleased"]
Version {stack-version} of {beatname_uc} has not yet been released.
endif::[]
ifeval::["{release-state}"!="unreleased"]
. Download the {beatname_uc} Windows zip file from the
https://www.elastic.co/downloads/beats/{beatname_lc}[downloads page].
. Extract the contents of the zip file into `C:\Program Files`.
. Rename the +{beatname_lc}-<version>-windows+` directory to +{beatname_uc}+.
. Open a PowerShell prompt as an Administrator (right-click the PowerShell icon
and select *Run As Administrator*).
. From the PowerShell prompt, run the following commands to install {beatname_uc}
as a Windows service:
+
["source","sh",subs="attributes"]
----------------------------------------------------------------------
PS > cd 'C:{backslash}Program Files{backslash}{beatname_uc}'
PS C:{backslash}Program Files{backslash}{beatname_uc}> .{backslash}install-service-{beatname_lc}.ps1
----------------------------------------------------------------------
NOTE: If script execution is disabled on your system, you need to set the
execution policy for the current session to allow the script to run. For
example: +PowerShell.exe -ExecutionPolicy UnRestricted -File
.{backslash}install-service-{beatname_lc}.ps1+.
endif::[]
Before starting {beatname_uc}, you should look at the configuration options in the
configuration file, for example +C:{backslash}Program Files{backslash}{beatname_uc}{backslash}{beatname_lc}.yml+.
For more information about these options, see
<<configuring-howto-{beatname_lc}>>.
[id="{beatname_lc}-configuration"]
=== Step 2: Configure {beatname_uc}
include::../../libbeat/docs/shared-configuring.asciidoc[]
When you configure {beatname_uc}, you need to specify which
<<{beatname_lc}-modules,modules>> to run. {beatname_uc} uses modules to collect
metrics. Each module defines the basic logic for collecting data from a specific
service, such as Redis or MySQL. A module consists of metricsets that fetch and
structure the data. Read <<how-{beatname_lc}-works>> to learn more.
To configure {beatname_uc}:
. Enable the modules that you want to run. If you accept the default
configuration without enabling additional modules, {beatname_uc} collects system
metrics only.
+
You can either enable the default module configurations defined in the
`modules.d` directory (recommended), or add the module configs to the
+{beatname_lc}.yml+ file. The `modules.d` directory contains default
configurations for all available {beatname_uc} modules.
+
If you are using a Docker image, see <<running-on-docker>>.
+
The following examples enable the `apache` and `mysql` configs in the
`modules.d` directory :
+
*deb and rpm:*
+
["source","sh",subs="attributes"]
----
{beatname_lc} modules enable apache mysql
----
+
*mac:*
+
["source","sh",subs="attributes"]
----
./{beatname_lc} modules enable apache mysql
----
+
*win:*
+
["source","sh",subs="attributes"]
----
PS > .{backslash}{beatname_lc}.exe modules enable apache mysql
----
+
See the <<modules-command>> to learn more about this command.
+
To change the default module configurations, modify the `.yml` files in the
`modules.d` directory. See <<module-config-options>> for more about available
settings.
+
See <<configuration-{beatname_lc}>> if you want to add the module configs to the
+{beatname_lc}.yml+ file rather than using the `modules.d` directory.
include::../../libbeat/docs/step-configure-output.asciidoc[]
include::../../libbeat/docs/step-configure-kibana-endpoint.asciidoc[]
include::../../libbeat/docs/step-configure-credentials.asciidoc[]
include::../../libbeat/docs/step-test-config.asciidoc[]
include::../../libbeat/docs/step-look-at-config.asciidoc[]
[id="{beatname_lc}-template"]
=== Step 3: Load the index template in Elasticsearch
:allplatforms:
include::../../libbeat/docs/shared-template-load.asciidoc[]
[[load-kibana-dashboards]]
=== Step 4: Set up the Kibana dashboards
:allplatforms:
include::../../libbeat/docs/dashboards.asciidoc[]
[id="{beatname_lc}-starting"]
=== Step 5: Start {beatname_uc}
Run {beatname_uc} by issuing the appropriate command for your platform. If you
are accessing a secured Elasticsearch cluster, make sure you've configured
credentials as described in <<{beatname_lc}-configuration>>.
NOTE: If you use an init.d script to start {beatname_uc} on deb or rpm, you can't
specify command line flags (see <<command-line-options>>). To specify flags,
start {beatname_uc} in the foreground.
*deb:*
["source","sh",subs="attributes"]
----------------------------------------------------------------------
sudo service {beatname_lc} start
----------------------------------------------------------------------
*rpm:*
["source","sh",subs="attributes"]
----------------------------------------------------------------------
sudo service {beatname_lc} start
----------------------------------------------------------------------
*docker:*
See <<running-on-docker>>.
*mac:*
["source","sh",subs="attributes,callouts"]
----------------------------------------------------------------------
sudo chown root {beatname_lc}.yml <1>
sudo chown root modules.d/system.yml <1>
sudo ./{beatname_lc} -e -c {beatname_lc}.yml -d "publish"
----------------------------------------------------------------------
<1> You'll be running {beatname_uc} as root, so you need to change ownership of the
configuration file and any configurations enabled in the `modules.d` directory,
or run {beatname_uc} with `--strict.perms=false` specified. See
{libbeat}/config-file-permissions.html[Config File Ownership and Permissions]
in the _Beats Platform Reference_.
*win:*
["source","sh",subs="attributes"]
----------------------------------------------------------------------
PS C:{backslash}Program Files{backslash}{beatname_uc}> Start-Service {beatname_lc}
----------------------------------------------------------------------
By default the log files are stored in +C:{backslash}ProgramData{backslash}{beatname_lc}{backslash}Logs+.
NOTE: On Windows, statistics about system load and swap usage are currently
not captured.
==== Test the {beatname_uc} installation
To verify that your server's statistics are present in Elasticsearch, issue
the following command:
["source","sh",subs="attributes"]
----------------------------------------------------------------------
curl -XGET 'http://localhost:9200/{beatname_lc}-*/_search?pretty'
----------------------------------------------------------------------
Make sure that you replace `localhost:9200` with the address of your
Elasticsearch instance.
On Windows, if you don't have cURL installed, simply point your browser to the
URL.
[[view-kibana-dashboards]]
=== Step 6: View the sample Kibana dashboards
To make it easier for you to start monitoring your servers in Kibana,
we have created example {beatname_uc} dashboards. You loaded the dashboards
earlier when you ran the `setup` command.
include::../../libbeat/docs/opendashboards.asciidoc[]
The dashboards are provided as examples. We recommend that you
{kibana-ref}/dashboard.html[customize] them to meet your needs.
[role="screenshot"]
image:./images/{beatname_lc}_system_dashboard.png[{beatname_uc} Dashboard]