openstack
/
monasca-agent
Code Issues Proposed changes

Add prefix "$" for command examples 

This commits adds "$" as a prefix for command examples and align
with 4 whitespaces.

Change-Id: I8c90c8f16b819f0ec141dbf3f6fb99fbce7c5a0c
This commit is contained in:
Yushiro FURUKAWA 2016-09-28 20:53:26 +09:00
parent 04e11b1bf6
commit 672db5b26b
6 changed files with 45 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
docs/Agent.md
View File

@ -44,23 +44,17 @@ The Agent is composed of the following components:
# Installing # Installing
The Agent (monasca-agent) is available for installation from the Python Package Index (PyPI). To install it, you first need `pip` installed on the node to be monitored. Instructions on installing pip may be found at https://pip.pypa.io/en/latest/installing.html. The Agent will NOT run under any flavor of Windows or Mac OS at this time but has been tested thoroughly on Ubuntu and should work under most flavors of Linux. Support may be added for Mac OS and Windows in the future. Example of an Ubuntu or Debian based install: The Agent (monasca-agent) is available for installation from the Python Package Index (PyPI). To install it, you first need `pip` installed on the node to be monitored. Instructions on installing pip may be found at https://pip.pypa.io/en/latest/installing.html. The Agent will NOT run under any flavor of Windows or Mac OS at this time but has been tested thoroughly on Ubuntu and should work under most flavors of Linux. Support may be added for Mac OS and Windows in the future. Example of an Ubuntu or Debian based install:
``` $ sudo apt-get install python-pip
sudo apt-get install python-pip
```
To ensure you are running the latest version of pip To ensure you are running the latest version of pip
``` $ sudo pip install --upgrade pip
sudo pip install --upgrade pip
```
Warning, the Agent is known to not install properly under python-pip version 1.0, which is packaged with Ubuntu 12.04 LTS (Precise Pangolin). Warning, the Agent is known to not install properly under python-pip version 1.0, which is packaged with Ubuntu 12.04 LTS (Precise Pangolin).
The Agent can be installed using pip as follows: The Agent can be installed using pip as follows:
``` $ sudo pip install monasca-agent
sudo pip install monasca-agent
```
# Configuring # Configuring
The Agent requires configuration in order to run. There are two ways to configure the agent, either using the [monasca-setup](#monasca-setup) script or manually. The Agent requires configuration in order to run. There are two ways to configure the agent, either using the [monasca-setup](#monasca-setup) script or manually.
@ -74,9 +68,10 @@ The plugin configuration files are located in /etc/monasca/agent/conf.d.
monasca-setup is located in `[installed prefix dir]/bin/monasca-setup` and can be run as follows: monasca-setup is located in `[installed prefix dir]/bin/monasca-setup` and can be run as follows:
``` $ sudo monasca-setup --username KEYSTONE_USERNAME \
sudo monasca-setup --username KEYSTONE_USERNAME --password KEYSTONE_PASSWORD --project_name KEYSTONE_PROJECT_NAME --keystone_url http://URL_OF_KEYSTONE_API:35357/v3 --password KEYSTONE_PASSWORD --project_name KEYSTONE_PROJECT_NAME \
``` --keystone_url http://URL_OF_KEYSTONE_API:35357/v3
It is also possible to skip most detection plugins in monasca-setup with the `--system_only` flag. You can then come back later and run individual detection plugins without additional arguments, It is also possible to skip most detection plugins in monasca-setup with the `--system_only` flag. You can then come back later and run individual detection plugins without additional arguments,
for example `monasca-setup -d mysql`. This allows a base install to setup the agent and required credentials then later easily add additional services and monitoring. for example `monasca-setup -d mysql`. This allows a base install to setup the agent and required credentials then later easily add additional services and monitoring.
@ -127,12 +122,12 @@ This is not the recommended way to configure the agent but if you are having tro
Start by creating an agent.yaml file. An example configuration file can be found in <install_dir>/share/monasca/agent/. Start by creating an agent.yaml file. An example configuration file can be found in <install_dir>/share/monasca/agent/.
sudo mkdir -p /etc/monasca/agent $ sudo mkdir -p /etc/monasca/agent
sudo cp /usr/local/share/monasca/agent/agent.yaml.template /etc/monasca/agent/agent.yaml $ sudo cp /usr/local/share/monasca/agent/agent.yaml.template /etc/monasca/agent/agent.yaml
and then edit the file with your favorite text editor (vi, nano, emacs, etc.) and then edit the file with your favorite text editor (vi, nano, emacs, etc.)
sudo nano /etc/monasca/agent/agent.yaml $ sudo nano /etc/monasca/agent/agent.yaml
In particular, replace any values that have curly braces. In particular, replace any values that have curly braces.
Example: Example:
@ -158,7 +153,7 @@ You must replace all of the curly brace values and you can also optionally tweak
Once the configuration file has been updated and saved, monasca-agent must be restarted. Once the configuration file has been updated and saved, monasca-agent must be restarted.
sudo service monasca-agent restart $ sudo service monasca-agent restart
## Dimension Precedence ## Dimension Precedence
If a dimension is specified in /etc/monasca/agent/agent.yaml with the same name (e.g. service) If a dimension is specified in /etc/monasca/agent/agent.yaml with the same name (e.g. service)
@ -192,12 +187,13 @@ Agent plugins are activated by placing a valid configuration file in the /etc/mo
For example, to activate the http_check plugin: For example, to activate the http_check plugin:
sudo mkdir -p /etc/monasca/agent/conf.d $ sudo mkdir -p /etc/monasca/agent/conf.d
sudo cp /usr/local/share/monasca/agent/conf.d/http_check.yaml.example /etc/monasca/agent/conf.d/http_check.yaml $ sudo cp /usr/local/share/monasca/agent/conf.d/http_check.yaml.example \
/etc/monasca/agent/conf.d/http_check.yaml
and then edit the file as needed for your configuration. and then edit the file as needed for your configuration.
sudo nano /etc/monasca/agent/conf.d/http_check.yaml $ sudo nano /etc/monasca/agent/conf.d/http_check.yaml
The plugins are annotated and include the possible configuration parameters. In general, though, configuration files are split into two sections: The plugins are annotated and include the possible configuration parameters. In general, though, configuration files are split into two sections:
init_config init_config

12
docs/DeveloperDocs/agent_internals.md
View File

@ -38,10 +38,8 @@ old_config:
monasca-setup arguments: monasca-setup arguments:
``` $ monasca-setup -d 'HttpCheck' -a 'url=http://192.168.10.6:8070
monasca-setup -d 'HttpCheck' -a 'url=http://192.168.10.6:8070 match_pattern= match_pattern=.*OK.* name=monasca dimensions=service:monitoring'
.*OK.* name=monasca dimensions=service:monitoring'
```
input_config generated from monasca-setup: input_config generated from monasca-setup:
@ -102,10 +100,8 @@ old_config:
monasca-setup arguments: monasca-setup arguments:
``` $ monasca-setup -d 'HttpCheck' -a 'url=https://192.168.10.6:8070
monasca-setup -d 'HttpCheck' -a 'url=https://192.168.10.6:8070 match_pattern=.*VERSION.* dimensions=service:logging'
match_pattern=.*VERSION.* dimensions=service:logging'
```
input_config generated from monasca-setup: input_config generated from monasca-setup:

11
docs/Libvirt.md
View File

@ -326,9 +326,9 @@ The process of looking for namespaces and security rules occurs each time the in
#### Client Configuration #### Client Configuration
The VM owner would need to add a security rule to allow ICMP access to their VM. The simplest implementation would be to allow ICMP globally: The VM owner would need to add a security rule to allow ICMP access to their VM. The simplest implementation would be to allow ICMP globally:
```
nova secgroup-add-rule default icmp -1 -1 0.0.0.0/0 $ nova secgroup-add-rule default icmp -1 -1 0.0.0.0/0
```
However, more security-conscious customers may not want the world to ping their VM, so at a minimum, ICMP needs to be allowed for the subnet gateway IP address. However, more security-conscious customers may not want the world to ping their VM, so at a minimum, ICMP needs to be allowed for the subnet gateway IP address.
#### Troubleshooting #### Troubleshooting
@ -338,9 +338,8 @@ To limit false negative, ping checks will not be performed unless all the requir
"network" : [ { "ip" : "10.0.0.3", "namespace" : "qrouter-ae714057-4453-48c4-81cb-15f8db9434a8" } ], "network" : [ { "ip" : "10.0.0.3", "namespace" : "qrouter-ae714057-4453-48c4-81cb-15f8db9434a8" } ],
``` ```
You can attempt to ping the IP address through the given namespace with a command like You can attempt to ping the IP address through the given namespace with a command like
```
sudo ip netns exec qrouter-ae714057-4453-48c4-81cb-15f8db9434a8 ping 10.0.0.3 $ sudo ip netns exec qrouter-ae714057-4453-48c4-81cb-15f8db9434a8 ping 10.0.0.3
```
Other questions you could ask, if ping checks are not configured, are: Other questions you could ask, if ping checks are not configured, are:
* Do _any_ VMs have the "network" section in `/dev/shm/libvirt_instances.json`? If so, security rules for the VM in question may be the cause. * Do _any_ VMs have the "network" section in `/dev/shm/libvirt_instances.json`? If so, security rules for the VM in question may be the cause.

13
docs/MonascaMetrics.md
View File

@ -111,15 +111,12 @@ If the owner of the VM is to receive his or her own metrics, the Agent needs to
In the below example, the Agent's Keystone username is "monasca-agent" and the Agent's Keystone project name is "mini-mon". In the below example, the Agent's Keystone username is "monasca-agent" and the Agent's Keystone project name is "mini-mon".
Example commands to add the Agent user/project to the monitoring-delegate role: Example commands to add the Agent user/project to the monitoring-delegate role:
```
keystone role-create --name=monitoring-delegate
user_id=`keystone user-list |grep monasca-agent |cut -d'|' -f2` $ keystone role-create --name=monitoring-delegate
role_id=`keystone role-list |grep monitoring-delegate |cut -d'|' -f2` $ user_id=`keystone user-list |grep monasca-agent |cut -d'|' -f2`
tenant_id=`keystone tenant-list |grep mini-mon |cut -d'|' -f2` $ role_id=`keystone role-list |grep monitoring-delegate |cut -d'|' -f2`
$ tenant_id=`keystone tenant-list |grep mini-mon |cut -d'|' -f2`
keystone user-role-add --user=${user_id// /} --role=${role_id// /} --tenant_id=${tenant_id// /} $ keystone user-role-add --user=${user_id// /} --role=${role_id// /} --tenant_id=${tenant_id// /}
```
Once the Agent's user and project are assigned to the `monitoring-delegate` group, the Agent can submit metrics for other tenants. Once the Agent's user and project are assigned to the `monitoring-delegate` group, the Agent can submit metrics for other tenants.

16
docs/Plugins.md
View File

@ -419,9 +419,9 @@ It is possible to reduce the number of system metrics with certain configuration
| send_io_stats | true/false | If true, sends I/O metrics for each disk device. If false, sends only disk space metrics. | | send_io_stats | true/false | If true, sends I/O metrics for each disk device. If false, sends only disk space metrics. |
These parameters may added to `instances` in the plugin `.yaml` configuration file, or added via `monasca-setup` like this: These parameters may added to `instances` in the plugin `.yaml` configuration file, or added via `monasca-setup` like this:
```
monasca-setup -d system -a 'cpu_idle_only=true net_bytes_only=true send_io_stats=false' --overwrite $ monasca-setup -d system -a 'cpu_idle_only=true net_bytes_only=true send_io_stats=false' --overwrite
```
By default, all metrics are enabled. By default, all metrics are enabled.
## Apache ## Apache
@ -532,9 +532,7 @@ The configuration of the certificate expiration check is done in YAML, and consi
The init_config section lists the global configuration settings, such as the Certificate Authority Certificate file, the ciphers to use, the period at which to output the metric and the url connection timeout (in seconds, floating-point number) The init_config section lists the global configuration settings, such as the Certificate Authority Certificate file, the ciphers to use, the period at which to output the metric and the url connection timeout (in seconds, floating-point number)
``` $ ls -l `which ping` -rwsr-xr-x 1 root root 35712 Nov 8 2011 /bin/ping
ls -l `which ping` -rwsr-xr-x 1 root root 35712 Nov 8 2011 /bin/ping
```
``` ```
init_config: init_config:
@ -563,7 +561,7 @@ The certicate expiration checks return the following metrics
There is a detection plugin that should be used to configure this extension. It is invoked as: There is a detection plugin that should be used to configure this extension. It is invoked as:
monasca-setup -d CertificateCheck -a urls=https://somehost.somedomain.net:8333,https://somehost.somedomain.net:9696 $ monasca-setup -d CertificateCheck -a urls=https://somehost.somedomain.net:8333,https://somehost.somedomain.net:9696
The urls option is a comma separated list of urls to check. The urls option is a comma separated list of urls to check.
@ -829,9 +827,7 @@ The configuration of the host alive check is done in YAML, and consists of two k
The init_config section lists the global configuration settings, such as SSH port, SSH connection timeout (in seconds, floating-point number), and ping timeout (in seconds, integer). The init_config section lists the global configuration settings, such as SSH port, SSH connection timeout (in seconds, floating-point number), and ping timeout (in seconds, integer).
``` $ ls -l `which ping` -rwsr-xr-x 1 root root 35712 Nov 8 2011 /bin/ping
ls -l `which ping` -rwsr-xr-x 1 root root 35712 Nov 8 2011 /bin/ping
```
``` ```
init_config: init_config:

20
docs/index.md
View File

@ -7,34 +7,34 @@ For full Monasca documentation visit [wiki.openstack.org/wiki/Monasca](https://w
# Working with document updates # Working with document updates
##### Install mkdocs ##### Install mkdocs
sudo pip install mkdocs $ sudo pip install mkdocs
##### Install Nodejs Package Manager NPM ##### Install Nodejs Package Manager NPM
https://nodejs.org/download/ https://nodejs.org/download/
##### Install doctoc ##### Install doctoc
npm install -g doctoc $ npm install -g doctoc
##### Create a mkdocs project structure ##### Create a mkdocs project structure
cd source/openstack/monasca/monasca-agent $ cd source/openstack/monasca/monasca-agent
mkdocs new . $ mkdocs new .
##### Edit the mkdocs yaml ##### Edit the mkdocs yaml
site_name: monasca-agent site_name: monasca-agent
repo_url: https://github.com/openstack/monasca-agent repo_url: https://github.com/openstack/monasca-agent
##### Move the existing README.md ##### Move the existing README.md
mv README.md docs $ mv README.md docs
##### Copy/create custom docs to the new docs structure ##### Copy/create custom docs to the new docs structure
cp README_CUSTOMIZE.md source/openstack/monasca/monasca-agent/docs $ cp README_CUSTOMIZE.md source/openstack/monasca/monasca-agent/docs
##### Update the document table of contents on all docs ##### Update the document table of contents on all docs
cd source/openstack/monasca/monasca-agent $ cd source/openstack/monasca/monasca-agent
find docs/ -name \*.md -exec doctoc {} \; $ find docs/ -name \*.md -exec doctoc {} \;
##### View the results ##### View the results
cd source/openstack/monasca/monasca-agent $ cd source/openstack/monasca/monasca-agent
mkdocs serve $ mkdocs serve
http://127.0.0.1:8000/ http://127.0.0.1:8000/