Improvements to formatting

Just some improvements to the formatting to help make the markdown
more readable.  Did not try to address correctness of any of the
content.

Change-Id: I323ae1a942ca48e63416421407345b32aa2da121
This commit is contained in:
Joseph Davis 2018-08-08 16:10:13 -07:00
parent 2273aef8ab
commit 9dc138cdbe
1 changed files with 93 additions and 66 deletions

View File

@ -245,7 +245,7 @@ Each plugin has a corresponding YAML configuration file with the same stem name
The configuration file has the following structure:
```
```yaml
init_config:
key1: value1
key2: value2
@ -427,7 +427,7 @@ This section documents the system metrics that are sent by the Agent.
The network check can be configured to submit its metrics in either bytes/sec or bits/sec. The default behavior is to submit bytes. To submit `net.in_bits_sec` and `net.out_bits_sec` rather than `net.in_bytes_sec` and `net.out_bytes_sec`, set the config option `use_bits` to true for the instance you want to configure.
Example configuration:
```
```yaml
init_config: null
instances:
- built_by: System
@ -476,7 +476,7 @@ By default, all metrics are enabled.
## A10
This section describes the A10 System Check.
```
```yaml
init_config:
instances:
@ -498,7 +498,7 @@ This section describes the Apache Web Server check that can be performed by the
Sample config:
```
```yaml
init_config:
instances:
@ -548,7 +548,7 @@ only have one instance defined under instances. (Example shown below)
Sample config (passing in cAdvisor url):
```
```yaml
init_config:
# Timeout on GET requests to the cAdvisor endpoints
connection_timeout: 3
@ -558,7 +558,7 @@ instances:
```
Sample config (setting Kubernetes detect cAdvisor url):
```
```yaml
init_config:
# Timeout on GET requests to the cAdvisor endpoints
connection_timeout: 3
@ -624,14 +624,16 @@ monasca-setup script is run:
##### Example Cassandra Metrics
| Component | Metric Name | Metric Type | Check Type | Dimensions | Plugin | Description |
| --------- | ----------- | ----------- | ---------- | ---- | ------ | ----------- | ----- |
| --------- | ----------- | ----------- | ---------- | ---------- | ------ | ----------- |
| cassandra | process_pid_count | Gauge | Passive | service=cassandra, component=cassandra, process_user=cassandra | process | cassandra process pid count |
| cassandra | directory.files_count | Gauge | Active | service=cassandra, component=cassandra, path=/var/cassandra/data | cassandra data directory file count |
| cassandra | directory.size_bytes | Gauge | Active | service=cassandra, component=cassandra, path=/var/cassandra/data | cassandra data directory size |
| cassandra | directory.files_count | Gauge | Active | service=cassandra, component=cassandra, path=/var/cassandra/commitlog | cassandra commit log directory file count |
| cassandra | directory.size_bytes | Gauge | Active | service=cassandra, component=cassandra, path=/var/cassandra/commitlog | cassandra commit log directory size |
## Check_MK_Local
The [Check_MK](http://mathias-kettner.com/check_mk.html) [Agent](http://mathias-kettner.com/checkmk_linuxagent.html) can be extended through a series of [local checks](http://mathias-kettner.com/checkmk_localchecks.html). This plugin parses the `<<<local>>>` output of `check_mk_agent` and converts them into Monasca metrics. It is installed by `monasca-setup` automatically when the `check_mk_agent` script is found to be installed on the system.
@ -664,7 +666,7 @@ and
The name of the metric starts with `check_mk.`, includes the check_mk item name, and is followed by either `status` for the Nagios status code (0, 1, 2, or 3), or the name of the performance metric. The free-form output from the check is included in the meta field of the check status.
You may override these defaults in the configuration, which by default is `/etc/monasca/agent/conf.d/check_mk_local.yaml`.
```
```yaml
init_config:
mk_agent_path: /usr/bin/check_mk_agent
@ -705,7 +707,7 @@ user to the `ceph` group which does not require using sudo.
Sample config:
```
```yaml
init_config:
instances:
@ -816,8 +818,9 @@ The Ceph checks return the following metrics:
An extension to the Agent provides the ability to determine the expiration date of the certificate for the URL. The metric is days until the certificate expires
default dimensions:
```
url: url
```
A YAML file (cert_check.yaml) contains the list of urls to check. It also contains
The configuration of the certificate expiration check is done in YAML, and consists of two keys:
@ -829,7 +832,7 @@ The init_config section lists the global configuration settings, such as the Cer
$ ls -l `which ping` -rwsr-xr-x 1 root root 35712 Nov 8 2011 /bin/ping
```
```yaml
init_config:
ca_certs: /etc/ssl/certs/ca-certificates.crt
ciphers: HIGH:-aNULL:-eNULL:-PSK:RC4-SHA:RC4-MD5
@ -839,7 +842,7 @@ init_config:
The instances section contains the urls to check.
```
```yaml
instances:
- built_by: CertificateCheck
url: https://somehost.somedomain.net:8333
@ -914,8 +917,8 @@ ecn congestion rate calculation.
the plugin runs against all computes.
Sample config (`congestion.yaml`):
```
---
```yaml
init_config:
auth_url: http://10.10.10.10/identity_admin
cache_dir: /dev/shm
@ -972,7 +975,7 @@ The `monasca-setup` program will configure the Crash plugin if a crash kernel is
Sample config:
```
```yaml
init_config:
crash_dir: /var/crash
@ -989,7 +992,7 @@ Similar to other checks, the configuration is done in YAML, and consists of two
Sample config:
```
```yaml
init_config: null
instances:
- built_by: Directory
@ -1018,7 +1021,7 @@ Sample config:
Without kubernetes dimensions
```
```yaml
init_config:
docker_root: /
socket_timeout: 5
@ -1027,7 +1030,7 @@ instances:
```
With kubernetes dimensions
```
```yaml
init_config:
docker_root: /
socket_timeout: 5
@ -1067,7 +1070,7 @@ This section describes the Elasticsearch check that can be performed by the Agen
Sample config:
```
```yaml
init_config:
instances:
- url: http://127.0.0.1:9200
@ -1193,7 +1196,7 @@ Similar to other checks, the configuration is done in YAML, and consists of two
Sample config:
```
```yaml
init_config: null
instances:
- built_by: FileSize
@ -1253,7 +1256,7 @@ The init_config section lists the global configuration settings, such as SSH por
$ ls -l `which ping` -rwsr-xr-x 1 root root 35712 Nov 8 2011 /bin/ping
```
```yaml
init_config:
ssh_port: 22
@ -1266,7 +1269,7 @@ init_config:
The instances section contains the hostname/IP to check, and the type of check to perform, which is either ssh or ping.
```
```yaml
# alive_test can be either "ssh" for an SSH banner test (port 22)
# or "ping" for an ICMP ping test instances:
- name: ssh to somehost
@ -1312,23 +1315,28 @@ The host alive checks return the following metrics
Also in the case of an error the value_meta contains an error message.
The default dimensions are:
```
observer_host: fqdn
hostname: fqdn | supplied
target_hostname: Set to target_hostname only if that is different than host_name
test_type: ping | ssh | Unrecognized alive_test
```
default value_meta
```
error: error_message
```
## HTTP (endpoint status)
This section describes the http endpoint check that can be performed by the Agent. Http endpoint checks are checks that perform simple up/down checks on services, such as HTTP/REST APIs. An agent, given a list of URLs, can dispatch an http request and report to the API success/failure as a metric.
default dimensions:
```
url: endpoint
```
default value_meta
```
error: error_message
```
The Agent supports additional functionality through the use of Python scripts. A YAML file (http_check.yaml) contains the list of URLs to check (among other optional parameters). A Python script (http_check.py) runs checks each host in turn, returning a 0 on success and a 1 on failure in the result sent through the Forwarder and on the Monitoring API.
Similar to other checks, the configuration is done in YAML, and consists of two
@ -1349,7 +1357,7 @@ DEPRECATED: providing Keystone configuration in each instance.
Sample config:
```
```yaml
init_config:
keystone_config:
keystone_url: http://endpoint.com/v3/
@ -1377,15 +1385,17 @@ The http_status checks return the following metrics:
This section describes the http metrics check that can be performed by the agent. Http metrics checks are checks that retrieve metrics from any url returning a json formatted response. An agent, given a list of URLs, can dispatch an http request and parse the desired metrics from the json response.
default dimensions:
```
url: endpoint
```
default value_meta
```
error: error_message
```
Similar to other checks, the configuration is done in YAML (http_metrics.yaml), and consists of two keys: init_config and instances. The former is not used by http_metrics, while the later contains one or more URLs to check, plus optional parameters like a timeout, username/password, whether or not to also record the response time, and a whitelist of metrics to collect. The whitelist should consist of a name, path, and type for each metric to be collected. The name is what the metric will be called when it is reported. The path is a string of keys separated by '/' where the metric value resides in the json response. The type is how you want the metric to be recorded (gauge, counter, histogram, rate, set). A gauge will store and report the value it find with no modifications. A counter will increment itself by the value it finds. A histogram will store values and return the calculated max, median, average, count, and percentiles. A rate will return the difference between the last two recorded samples divided by the interval between those samples in seconds. A set will record samples and return the number of unique values in the set.
If the endpoint being checked requires authentication, there are two options. First, a username and password supplied in the instance options will be used by the check for authentication. Alternately, the check can retrieve a keystone token for authentication. Specific keystone information can be provided for each check, otherwise the information from the agent config will be used.
```
```yaml
init_config:
instances:
@ -1495,7 +1505,7 @@ after writing new data to make sure the data is written to the file.
Example of writing metrics file:
```
```python
metric_data = [{"name": "metric1", "value": 10.1, "timestamp": time.time()}]
max_retries = 10
delay = 0.02
@ -1580,7 +1590,7 @@ This section describes the Kafka check that can be performed by the Agent. The
Sample config:
```yml
```yaml
init_config:
instances:
@ -1629,7 +1639,7 @@ Sample configs:
Without custom labels and host being manually set:
```
```yaml
init_config:
# Timeout on GET requests
connection_timeout: 3
@ -1643,7 +1653,7 @@ instances:
With custom labels and host being manually set:
```
```yaml
init_config:
# Timeout on GET requests
connection_timeout: 3
@ -1658,7 +1668,7 @@ instances:
With custom labels and derive host being set:
```
```yaml
instances:
# Set to the host that the plugin will use when connecting to the Kubernetes API
- host: "127.0.0.1"
@ -1668,7 +1678,7 @@ instances:
With custom labels and derive api url set to True:
```
```yaml
init_config:
# Timeout on GET requests
connection_timeout: 3
@ -1812,7 +1822,7 @@ There are two ways you can configure the plugin to connect to the kubernetes api
Sample configs:
```
```yaml
instances:
- derive api url: True
kubernetes_labels: ['k8s-app', 'version']
@ -1865,7 +1875,7 @@ Requirements:
Sample config:
```
```yaml
init_config:
instances:
@ -1950,7 +1960,7 @@ The configuration file (`/etc/monasca/agent/conf.d/mk_livestatus.yaml` by defaul
If *host_name* is not specified, metrics for all hosts will be reported.
This configuration example shows several ways to specify instances:
```
```yaml
init_config:
# Specify the path to the mk_livestatus socket
socket_path: /var/lib/icinga/rw/live
@ -2008,7 +2018,7 @@ Instance variables can be passed via command line arguments
to the monasca-setup -d mysql command.
The instance config files are built by the detection plugin.
```
```yaml
init_config:
Example clear connect:
instances:
@ -2071,22 +2081,31 @@ The mySQL checks return the following metrics:
| mysql.net.connections | hostname, mode, service=mysql | Corresponding to "Connections" of the server status variable. |
## Nagios Wrapper
The Agent can run Nagios plugins. A YAML file (nagios_wrapper.yaml) contains the list of Nagios checks to run, including the check name, command name with parameters, and desired interval between iterations. A Python script (nagios_wrapper.py) runs each command in turn, captures the resulting exit code (0 through 3, corresponding to OK, warning, critical and unknown), and sends that information to the Forwarder, which then sends the Monitoring API. Currently, the Agent can only send the exit code from a Nagios plugin. Any accompanying text is not sent.
The Agent can run Nagios plugins. A YAML file (nagios_wrapper.yaml) contains the list of Nagios checks to run,
including the check name, command name with parameters, and desired interval between iterations. A Python
script (nagios_wrapper.py) runs each command in turn, captures the resulting exit code (0 through 3,
corresponding to OK, warning, critical and unknown), and sends that information to the Forwarder, which then
sends to the Monitoring API. Currently, the Agent can only send the exit code from a Nagios plugin. Any
accompanying text is not sent.
default dimensions:
```
observer_host: fqdn
target_host: fqdn | supplied
```
default value_meta
```
0, 1, 2, 3, 4
OK, Warning, Critical, Unknown
error: error_message
```
Similar to all plugins, the configuration is done in YAML, and consists of two keys: init_config and instances.
init_config contains global configuration options:
*init_config* contains global configuration options:
```
```yaml
init_config:
# Directories where Nagios checks (scripts, programs) may live
check_path: /usr/lib/nagios/plugins:/usr/local/bin/nagios
@ -2095,9 +2114,9 @@ init_config:
temp_file_path: /dev/shm/
```
instances contains the list of checks to run
*instances* contains the list of checks to run.
```
```yaml
instances:
- name: load
check_command: check_load -r -w 2,1.5,1 -c 10,5,4
@ -2107,10 +2126,18 @@ instances:
check_interval: 300
```
* 'name' value is the name of the metric
* check_command is the full command to run. Specifying the full path is optional if the checks are located somewhere in check_path. These above examples are a copy-and-paste from existing service checks in /etc/cron.d/servicecheck-* files, so migration is fairly easy.
* `name` value is the name of the metric.
* check_interval (optional) If unspecified, the checks will be run at the regular collector interval, which is 60 seconds by default. You may not want to run some checks that frequently, especially if they are resource-intensive, so check_interval lets you force a delay, in seconds, between iterations of that particular check. The state for these are stored in temp_file_path with file names like nagios_wrapper_19fe42bc7cfdc37a2d88684013e66c7b.pck where the hash is an md5sum of the 'name' value (to accommodate odd characters that the filesystem may not like).
* `check_command` is the full command to run. Specifying the full path is optional if the checks are located
somewhere in check_path. These above examples are a copy-and-paste from existing service checks in
/etc/cron.d/servicecheck-* files, so migration is fairly easy.
* `check_interval` (optional) If unspecified, the checks will be run at the regular collector interval, which
is 60 seconds by default. You may not want to run some checks that frequently, especially if they are
resource-intensive, so check_interval lets you force a delay, in seconds, between iterations of that
particular check. The state for these are stored in temp_file_path with file names like
nagios_wrapper_19fe42bc7cfdc37a2d88684013e66c7b.pck where the hash is an md5sum of the 'name' value (to
accommodate odd characters that the filesystem may not like).
## Nginx
See [the example configuration](https://github.com/openstack/monasca-agent/blob/master/conf.d/nginx.yaml.example) for how to configure the Nginx plugin.
@ -2120,7 +2147,7 @@ This section describes the Network Time Protocol checks that can be performed by
Sample config:
```
```yaml
init_config:
instances:
@ -2149,7 +2176,7 @@ NOTE: The user running monasca-agent must have passwordless sudo access for the
Sample config:
```
```yaml
init_config:
instances:
@ -2172,7 +2199,7 @@ This section describes the PostgreSQL checks that can be performed by the Agent.
Sample config:
```
```yaml
init_config:
instances:
@ -2185,7 +2212,7 @@ instances:
If you want to track per-relation (table), you need to add relations keys and specify the list.
```
```yaml
relations:
- my_table
- my_other_table
@ -2252,7 +2279,7 @@ Using a yaml config file:
monasca-setup -d ProcessCheck -a "conf_file_path=/home/stack/myprocess.yaml"
```
Example yaml input file format for process check by process names:
```
```yaml
process_config:
- process_names:
@ -2262,7 +2289,7 @@ process_config:
service: monitoring
```
Example yaml input file format for multiple process_names entries:
```
```yaml
process_config:
- process_names:
@ -2282,7 +2309,7 @@ process_config:
component: thresh
```
Sample successfully built process.yaml:
```
```yaml
init_config: null
instances:
- built_by: ProcessCheck
@ -2320,7 +2347,7 @@ For Docker environment you can enable the process plugin by adding
to `/plugins.d/process.yaml`). Additionally you have to specify the path of the
host process filesystem. In this case mount host root directory `/` to
`/rootfs` in the container. Sample configuration:
```
```yaml
init_config:
process_fs_path: /rootfs/proc
instances:
@ -2364,7 +2391,7 @@ By default we grab the defined labels on each metric as dimensions.
Example yaml file:
```
```yaml
init_config:
# Timeout on connections to each endpoint
timeout: 3
@ -2397,7 +2424,7 @@ for metrics coming out. By default that will be set to "app"
Example yaml file (by pod):
```
```yaml
init_config:
timeout: 3
auto_detect_endpoints: True
@ -2408,7 +2435,7 @@ instances:
Example yaml file (by service):
```
```yaml
init_config:
timeout: 3
auto_detect_endpoints: True
@ -2442,7 +2469,7 @@ rabbitmq-plugins enable rabbitmq_management
```
Sample config:
```
```yaml
init_config:
instances:
@ -2530,13 +2557,13 @@ See [the example configuration](https://github.com/openstack/monasca-agent/blob/
The SolidFire checks require a matching solidfire.yaml to be present. Currently the checks report a mixture of cluster utilization and health metrics. Multiple clusters can be monitored via separate instance stanzas in the config file.
Sample config:
```yaml
instances:
- name: cluster_rack_d
username: cluster_admin
password: secret_password
mvip: 192.168.1.1
```
The SolidFire checks return the following metrics:
| Metric Name | Dimensions | Semantics |
@ -2584,7 +2611,7 @@ See [the example configuration](https://github.com/openstack/monasca-agent/blob/
This plugin provides metrics for VMware ESX clusters. It connects to vCenter server with its credentials and collects the configured cluster's performance data.
### Sample Config
```
```yaml
init_config: {}
instances:
- vcenter_ip: <vcenter-ip or fqdn>
@ -2625,7 +2652,7 @@ This plugin provides exclusively vm status metrics for VMware ESX clusters. Incl
In the example below, the resulting metrics will have a dimension of 'tenant_id' with the value from the 'project_id' annotation.
### Sample Config
```
```yaml
init_config:
vcenter_ip: "127.0.0.1"
vcenter_user: "joe"
@ -2652,7 +2679,7 @@ This section describes the vertica check that can be performed by the Agent. Th
Sample config:
```
```yaml
init_config:
instances:
@ -2688,7 +2715,7 @@ The Zookeeper check parses the result of zookeeper's `stat` admin command.
Sample config:
```
```yaml
init_config:
instances: