[[configuration]]
== Configuring Marvel

[float]
[[stats-export]]
=== Controlling Marvel Data Collection

You can set `marvel.agent` options in a node's `elasticsearch.yml` file to control how Marvel data
is collected from the node. 

`marvel.agent.enabled`::

Controls whether or not data is collected from the node. Enabled by default. Set 
`marvel.agent.enabled` to `false` to disable data collection. Use to disable data collection
on the monitoring nodes when you use a separate monitoring cluster. 

`marvel.agent.exporter.es.hosts`::

Specifies where the collected Marvel data should be stored. Defaults to the address of the 
local node (typically `localhost:9200`). To send data to a monitoring cluster, 
set to a comma-seprarated list of nodes in `hostname:port` format . Marvel attempts to send data
to the hosts in the order they are listed--if the first node is unreachable, the second node is 
tried, and so on. added[1.3.0, before the default was `localhost:9200`] 
+
You can update this setting through the Cluster Update Settings API.
+
added[1.0.2] - HTTP Basic authentication credentials can be specified as part of the host name,
 i.e., ["user:pwd@host:9200"]
+
added[1.3.0] - next to the host and port, you can specify a protocol to use,
 i.e., ["https://host:9200"] (defaults to "http")
+
added[1.3.0] - the `hostname:port` part can be extended with a base path
 i.e., ["host:9200/monitor1"]

`marvel.agent.indices`::

Controls which indices Marvel collects data for. Defaults to all indices. Specify the index names 
as a comma-separated list, for example `test1,test2,test3`. Names can include wildcards, for 
example `test*`. You can explicitly include or exclude indices by prepending
`+` to include the index, or `-` to exclude the index. For example, to include all indices that 
start with `test` except `test3`, you could specify `+test*,-test3`. 
+
You can update this setting through the Cluster Update Settings API.

`marvel.agent.interval`::

Controls how often data samples are collected from the node. Defaults to `10s`. Set to 
`-1` to temporarily disable data collection.
+
You can update this setting through the Cluster Update Settings API.

`marvel.agent.exporter.es.index.timeformat`::

Controls the time component in the index name to  which data is exported.
Defaults to `"YYYY.MM.dd"`, which produces index names such as
`.marvel-2015.08.23`. Supports date formats as explained
http://joda-time.sourceforge.net/api-release/org/joda/time/format/DateTimeFormat.html[here].

`marvel.agent.exporter.es.timeout`::

Sets the connection timeout for sending data. Defaults to `6s`.
+
You can update this setting through the Cluster Update Settings API.

`marvel.agent.stats.timeout`::

added[1.3.1]

Sets the timeout when collecting statistics from the master node. Defaults to `10m`.

`marvel.agent.exporter.es.ssl.truststore.path`::

added[1.3.0]

The location of the truststore to use for HTTPS connections. Specified as an absolute path.

`marvel.agent.exporter.es.ssl.truststore.password`::

The password to use to access the truststore.

`marvel.agent.exporter.es.ssl.truststore.algorithm`::

The truststore format. Defaults to SunX509.

`marvel.agent.exporter.es.ssl.hostname_verification`::
+
added[1.3.1]

Controls whether or not the hostname is verified when using HTTPS. Set to `false` to disable 
hostname verification when sending data to a remote host.
+
You can update this setting through the Cluster Update Settings API.

[float]
[[marvel-indices]]
=== Configuring Marvel Indices

Marvel stores it's data using time-based indices. By default, Marvel generates
an index per day, with one shard and one replica. We expect this to be a good
default for most use cases. For very large clusters, you might need to make changes
by overriding the settings in the default Marvel index template.

[[config-marvel-indices]]

Marvel uses an {ref}/indices-templates.html[index template] to preconfigure newly created indices. 
You can retrieve it with:

[source,sh]
----------------------------------
GET /_template/marvel
----------------------------------

You can override the default settings by adding your own template. Make sure your template uses
the `.marvel-*` matching pattern and has an order of 1 or higher. For example, the following 
template increases the number of shards to 5:

[source,json]
----------------------------------
PUT /_template/custom_marvel
{
    "template": ".marvel*",
    "order": 1,
    "settings": {
        "number_of_shards": 5
    }
}
----------------------------------

IMPORTANT: We recommend only changing the `settings` section. Other sections are
important for the correct operation of the dashboards.

For reference, the following snippet shows the `settings` section of the default template.

[source,json]
----------------------------------
{
    "template": ".marvel*",
    "settings": {
        "number_of_shards": 1,
        "number_of_replicas": 1,
        "analysis": {
            "analyzer": {
                "default": {
                    "type": "standard",
                    "stopwords": "_none_"
                }
            }
        },
        "mapper.dynamic": true,
        "marvel.index_format": 1
    }
    .....
}
----------------------------------

[float]
[[relevant-settings]]
=== Enabling Automatic Index Creation

Marvel relies on Elasticsearch's ability to automatically create new indices
when indexing documents. If you have disabled automatic index creation, you
need to configure the `action.auto_create_index` setting to allow the
creation of Marvel indices:

[source,yaml]
----------------------
action.auto_create_index: .marvel-*
----------------------

For more information see {ref}/docs-index_.html#index-creation[Index Creation] in the Elasticsearch 
Reference.