[[metricbeat-getting-started]]
== Getting Started With Metricbeat

Metricbeat helps you monitor your servers and the services they host by
collecting metrics from the operating system and services.

To get started with your own Metricbeat setup, install and configure these
related products:

 * Elasticsearch for storage and indexing the data.
 * Kibana for the UI.
 * Logstash (optional) for inserting data into Elasticsearch.

See {libbeat}/getting-started.html[Getting Started with Beats and the Elastic Stack] for more information.

After installing the Elastic Stack, read the following topics to learn how to install, configure, and run Metricbeat:

* <<metricbeat-installation>>
* <<metricbeat-configuration>>
* <<metricbeat-template>>
* <<metricbeat-starting>>
* <<metricbeat-sample-dashboards>>
* <<command-line-options>>
* <<directory-layout>>

[[metricbeat-installation]]
=== Step 1: Installing Metricbeat

You should install Metricbeat 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 Metricbeat on each service. This allows Metricbeat to
access your service from localhost and does not cause any additional network
traffic or prevent Metricbeat from collecting metrics when there are network
problems. Metrics from multiple Metricbeat 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,callouts"]
------------------------------------------------
curl -L -O https://artifacts.elastic.co/downloads/beats/metricbeat/metricbeat-{version}-amd64.deb
sudo dpkg -i metricbeat-{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,callouts"]
------------------------------------------------
curl -L -O https://artifacts.elastic.co/downloads/beats/metricbeat/metricbeat-{version}-x86_64.rpm
sudo rpm -vi metricbeat-{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,callouts"]
------------------------------------------------
curl -L -O https://artifacts.elastic.co/downloads/beats/metricbeat/metricbeat-{version}-darwin-x86_64.tar.gz
tar xzvf metricbeat-{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 Metricbeat Windows zip file from the
https://www.elastic.co/downloads/beats/metricbeat[downloads page].

. Extract the contents of the zip file into `C:\Program Files`.

. Rename the `metricbeat-<version>-windows` directory to `Metricbeat`.

. Open a PowerShell prompt as an Administrator (right-click the PowerShell icon
and select *Run As Administrator*). If you are running Windows XP, you may need
to download and install PowerShell.

. From the PowerShell prompt, run the following commands to install Metricbeat
as a Windows service:
+
[source,shell]
----------------------------------------------------------------------
PS > cd 'C:\Program Files\Metricbeat'
PS C:\Program Files\Metricbeat> .\install-service-metricbeat.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
.\install-service-metricbeat.ps1`.

endif::[]

Before starting Metricbeat, you should look at the configuration options in the
configuration file, for example `C:\Program Files\Metricbeat\metricbeat.yml`.
For more information about these options, see
<<metricbeat-configuration-options>>.

[[metricbeat-configuration]]
=== Step 2: Configuring Metricbeat

include::../../libbeat/docs/shared-configuring.asciidoc[]

Metricbeat uses <<metricbeat-modules,modules>> to collect metrics. You configure
each module individually. The following example shows the default configuration
in the `metricbeat.yml` file. The system status module is enabled by default to
collect metrics about your server, such as CPU usage, memory usage, network IO
metrics, and process statistics:

[source, shell]
-------------------------------------
metricbeat.modules:
- module: system
  metricsets:
    - cpu
    - filesystem
    - memory
    - network
    - process
  enabled: true
  period: 10s
  processes: ['.*']
  cpu_ticks: false
-------------------------------------

The following example shows how to configure two modules: the system module
and the Apache HTTPD module:

[source, shell]
-------------------------------------
metricbeat.modules:
- module: system
  metricsets:
    - cpu
    - filesystem
    - memory
    - network
    - process
  enabled: true
  period: 10s
  processes: ['.*']
  cpu_ticks: false
- module: apache
  metricsets: ["status"]
  enabled: true
  period: 1s
  hosts: ["http://127.0.0.1"]
-------------------------------------

To configure Metricbeat:

. Define the Metricbeat modules that you want to enable. For each module, specify
the metricsets that you want to collect. See <<configuring-howto-metricbeat>> for
more details about configuring modules.
+
If you accept the default configuration without specifying additional modules,
Metricbeat will collect system metrics only.

. If you are sending output to Elasticsearch, set the IP address and port where
Metricbeat can find the Elasticsearch installation:
+
[source,yaml]
----------------------------------------------------------------------
output.elasticsearch:
  hosts: ["192.168.1.42:9200"]
----------------------------------------------------------------------
+
If you are sending output to Logstash, see <<config-metricbeat-logstash>>
instead.

[[metricbeat-template]]
=== Step 3: Loading the Index Template in Elasticsearch

:allplatforms:
include::../../libbeat/docs/shared-template-load.asciidoc[]

[[metricbeat-starting]]
=== Step 4: Starting Metricbeat

Run Metricbeat by issuing the appropriate command for your platform.

NOTE: If you use an init.d script to start Metricbeat on deb or rpm, you can't
specify command line flags (see <<command-line-options>>). To specify flags,
start Metricbeat in the foreground.

*deb:*

[source,shell]
----------------------------------------------------------------------
sudo /etc/init.d/metricbeat start
----------------------------------------------------------------------

*rpm:*

[source,shell]
----------------------------------------------------------------------
sudo /etc/init.d/metricbeat start
----------------------------------------------------------------------

*docker:*

["source", "shell", subs="attributes"]
----------------------------------------------------------------------
docker run {dockerimage}
----------------------------------------------------------------------

*mac:*

[source,shell]
----------------------------------------------------------------------
sudo chown root metricbeat.yml <1>
sudo ./metricbeat -e -c metricbeat.yml -d "publish"
----------------------------------------------------------------------
<1> You'll be running Metricbeat as root, so you need to change ownership
of the configuration file (see
{libbeat}/config-file-permissions.html[Config File Ownership and Permissions]
in the _Beats Platform Reference_).

*win:*

[source,shell]
----------------------------------------------------------------------
PS C:\Program Files\Metricbeat> Start-Service metricbeat
----------------------------------------------------------------------

By default the log files are stored in `C:\ProgramData\metricbeat\Logs`.

NOTE: On Windows, statistics about system load and swap usage are currently
not captured.

==== Testing the Metricbeat Installation

To verify that your server's statistics are present in Elasticsearch, issue
the following command:

[source,shell]
----------------------------------------------------------------------
curl -XGET 'http://localhost:9200/metricbeat-*/_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.

[[metricbeat-sample-dashboards]]
=== Step 5: Loading Sample Kibana Dashboards

To make it easier for you to start monitoring your servers in Kibana,
we have created sample Metricbeat dashboards. The dashboards are provided as
examples. We recommend that you
http://www.elastic.co/guide/en/kibana/current/dashboard.html[customize] them
to meet your needs.

image:./images/metricbeat_system_dashboard.png[Metricbeat Dashboard]

:allplatforms:
include::../../libbeat/docs/dashboards.asciidoc[]
