Improved ceilometer content

Closes-bug: #1405252 Co-Authored-By: Matt Kassawara <mkassawara@gmail.com> backport: juno Change-Id: Iccbea43eea85ad78910f86c81d7f32383c5d4440
2015-01-15 18:48:11 +05:30 · 2015-01-15 18:48:11 +05:30 · f6268ba315
commit f6268ba315
parent 6c8ce32ea1
4 changed files with 98 additions and 58 deletions
--- a/doc/install-guide/section_ceilometer-controller.xml
+++ b/doc/install-guide/section_ceilometer-controller.xml
@ -40,7 +40,7 @@ Key Expires: Sat Dec 20 20:08:39 2014</programlisting>
      <para>Install the MongoDB package:</para>
      <screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>yum install mongodb-server mongodb</userinput></screen>
      <screen os="opensuse;sles"><prompt>#</prompt> <userinput>zypper install mongodb</userinput></screen>
-      <screen os="ubuntu"><prompt>#</prompt> <userinput>apt-get install mongodb-server</userinput></screen>
+      <screen os="ubuntu"><prompt>#</prompt> <userinput>apt-get install mongodb-server mongodb-clients python-pymongo</userinput></screen>
    </step>
    <step>
      <para>Edit the <filename>/etc/mongodb.conf</filename> file and
@ -83,8 +83,8 @@ Key Expires: Sat Dec 20 20:08:39 2014</programlisting>
 <prompt>#</prompt> <userinput>systemctl start mongodb.service</userinput></screen>
      <!-- NB: The use of mongod, and not mongodb, in the below screen is
      intentional. -->
-          <screen os="centos;fedora;rhel"><prompt>#</prompt> <userinput>service mongod start</userinput>
-<prompt>#</prompt> <userinput>chkconfig mongod on</userinput></screen>
+          <screen os="centos;fedora;rhel"><prompt>#</prompt> <userinput>systemctl enable mongod.service</userinput>
+<prompt>#</prompt> <userinput>systemctl start mongod.service</userinput></screen>
        </step>
      </substeps>
    </step>
@ -94,7 +94,19 @@ Key Expires: Sat Dec 20 20:08:39 2014</programlisting>
  db = db.getSiblingDB("ceilometer");
  db.addUser({user: "ceilometer",
  pwd: "<replaceable>CEILOMETER_DBPASS</replaceable>",
-  roles: [ "readWrite", "dbAdmin" ]})'</userinput></screen>
+  roles: [ "readWrite", "dbAdmin" ]})'</userinput>
+
+<computeroutput>MongoDB shell version: X.Y.Z
+connecting to: controller:27017/test
+{
+ "user" : "ceilometer",
+ "pwd" : "72f25aeee7ad4be52437d7cd3fc60f6f",
+ "roles" : [
+  "readWrite",
+  "dbAdmin"
+ ],
+ "_id" : ObjectId("5489c22270d7fad1ba631dc3")
+}</computeroutput></screen>
      <para>Replace <replaceable>CEILOMETER_DBPASS</replaceable> with a
        suitable password.</para>
    </step>
@ -126,7 +138,7 @@ Key Expires: Sat Dec 20 20:08:39 2014</programlisting>
      </substeps>
    </step>
    <step>
-      <para>Create the Telemetry service API endpoints:</para>
+      <para>Create the Telemetry module API endpoints:</para>
      <screen><prompt>$</prompt> <userinput>keystone endpoint-create \
  --service-id $(keystone service-list | awk '/ metering / {print $2}') \
  --publicurl http://<replaceable>controller</replaceable>:8777 \
@ -206,7 +218,9 @@ Key Expires: Sat Dec 20 20:08:39 2014</programlisting>
 ...
 connection = mongodb://ceilometer:<replaceable>CEILOMETER_DBPASS</replaceable>@<replaceable>controller</replaceable>:27017/ceilometer</programlisting>
          <para>Replace <replaceable>CEILOMETER_DBPASS</replaceable> with
-            the password you chose for the Telemetry module database.</para>
+            the password you chose for the Telemetry module database. MongoDB
+            connection string requires escaping special characters as per
+            RFC2396.</para>
        </step>
        <step>
          <para>In the <literal>[DEFAULT]</literal> section, configure
@ -267,13 +281,6 @@ metering_secret = <replaceable>METERING_SECRET</replaceable></programlisting>
          <para>Replace <replaceable>METERING_SECRET</replaceable> with the
            metering secret that you generated in a previous step.</para>
        </step>
-        <step os="ubuntu">
-          <para>In the <literal>[DEFAULT]</literal> section, configure the log
-            directory:</para>
-          <programlisting language="ini">[DEFAULT]
-...
-log_dir = /var/log/ceilometer</programlisting>
-        </step>
        <step os="opensuse;sles">
          <para>In the <literal>[collector]</literal> section, configure the
            dispatcher:</para>
@ -282,6 +289,14 @@ log_dir = /var/log/ceilometer</programlisting>
 ...
 dispatcher = database</programlisting>
        </step>
+        <step>
+          <para>(Optional) To assist with troubleshooting,
+            enable verbose logging in the <literal>[DEFAULT]</literal>
+            section:</para>
+          <programlisting language="ini">[DEFAULT]
+...
+verbose = True</programlisting>
+        </step>
      </substeps>
    </step>
  </procedure>
--- a/doc/install-guide/section_ceilometer-glance.xml
+++ b/doc/install-guide/section_ceilometer-glance.xml
@ -6,28 +6,35 @@
  xml:id="ceilometer-agent-glance">
  <title>Configure the Image Service for Telemetry</title>
  <procedure>
+    <title>To configure prerequisites</title>
+    <para>To retrieve image samples, you must configure the Image
+      Service to send notifications to the message broker. Edit the
+      <filename>/etc/glance/glance-api.conf</filename> and
+      <filename>/etc/glance/glance-registry.conf</filename> files and
+      complete the following actions:</para>
    <step>
-      <para>To retrieve image samples, you must configure the Image
-        Service to send notifications to the bus.</para>
-        <para>Edit
-        <filename>/etc/glance/glance-api.conf</filename> and modify the
-        <literal>[DEFAULT]</literal> section:</para>
-        <programlisting language="ini">notification_driver = messaging
+      <para>In the <literal>[DEFAULT]</literal> section, configure
+      notifications and RabbitMQ message broker access:</para>
+      <programlisting language="ini">[DEFAULT]
+...
+notification_driver = messaging
 rpc_backend = rabbit
 rabbit_host = <replaceable>controller</replaceable>
 rabbit_password = <replaceable>RABBIT_PASS</replaceable></programlisting>
+      <para>Replace <replaceable>RABBIT_PASS</replaceable> with the
+        password you chose for the <literal>guest</literal> account in
+        <application>RabbitMQ</application>.</para>
    </step>
    <step>
-        <para>Restart the Image Services with their new
-          settings:</para>
-        <screen os="ubuntu;debian"><prompt>#</prompt> <userinput>service glance-registry restart</userinput>
+      <para>Restart the Image Service:</para>
+      <screen os="ubuntu;debian"><prompt>#</prompt> <userinput>service glance-registry restart</userinput>
 <prompt>#</prompt> <userinput>service glance-api restart</userinput></screen>
-        <screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>systemctl restart openstack-glance-api.service openstack-glance-registry.service</userinput></screen>
-        <para os="sles">On SLES:</para>
-        <screen os="sles"><prompt>#</prompt> <userinput>service openstack-glance-api restart</userinput>
+      <screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>systemctl restart openstack-glance-api.service openstack-glance-registry.service</userinput></screen>
+      <para os="sles">On SLES:</para>
+      <screen os="sles"><prompt>#</prompt> <userinput>service openstack-glance-api restart</userinput>
 <prompt>#</prompt> <userinput>service openstack-glance-registry restart</userinput></screen>
-        <para os="opensuse">On openSUSE:</para>
-        <screen os="opensuse"><prompt>#</prompt> <userinput>systemctl restart openstack-glance-api.service openstack-glance-registry.service</userinput></screen>
+      <para os="opensuse">On openSUSE:</para>
+      <screen os="opensuse"><prompt>#</prompt> <userinput>systemctl restart openstack-glance-api.service openstack-glance-registry.service</userinput></screen>
    </step>
  </procedure>
 </section>
--- a/doc/install-guide/section_ceilometer-nova.xml
+++ b/doc/install-guide/section_ceilometer-nova.xml
@ -19,7 +19,7 @@
    </step>
    <step>
      <para>Edit the <filename>/etc/nova/nova.conf</filename> file and
-        add the following lines to the <literal>[DEFAULT]</literal>
+        configure notifications in the <literal>[DEFAULT]</literal>
        section:</para>
      <programlisting language="ini">[DEFAULT]
 ...
@ -44,18 +44,19 @@ notification_driver = ceilometer.compute.nova_notifier</programlisting>
    <para>Edit the <filename>/etc/ceilometer/ceilometer.conf</filename>
      file and complete the following actions:</para>
    <step>
-      <para>In the <literal>[publisher]</literal> section, set the
-        metering secret for Telemetry service nodes:</para>
+      <para>In the <literal>[publisher]</literal> section, configure the
+        metering secret:</para>
      <programlisting language="ini">[publisher]
-# Secret value for signing metering messages (string value)
+...
 metering_secret = <replaceable>METERING_SECRET</replaceable></programlisting>
      <para>Replace <replaceable>METERING_SECRET</replaceable> with
-        the metering secret that you created previously.</para>
+        the metering secret you chose for the Telemetry module.</para>
    </step>
    <step os="centos;fedora;opensuse;rhel;sles;ubuntu">
      <para>In the <literal>[DEFAULT]</literal> section, configure
-        RabbitMQ broker access:</para>
+        <application>RabbitMQ</application> message broker access:</para>
      <programlisting language="ini">[DEFAULT]
+...
 rabbit_host = <replaceable>controller</replaceable>
 rabbit_password = <replaceable>RABBIT_PASS</replaceable></programlisting>
      <para>Replace <replaceable>RABBIT_PASS</replaceable> with the password
@ -65,6 +66,7 @@ rabbit_password = <replaceable>RABBIT_PASS</replaceable></programlisting>
        <para>In the <literal>[keystone_authtoken]</literal> section,
          configure Identity service access:</para>
      <programlisting language="ini">[keystone_authtoken]
+...
 auth_uri = http://<replaceable>controller</replaceable>:5000/v2.0
 identity_uri = http://<replaceable>controller</replaceable>:35357
 admin_tenant_name = service
@ -83,29 +85,34 @@ admin_password = <replaceable>CEILOMETER_PASS</replaceable></programlisting>
      <para>In the <literal>[service_credentials]</literal> section,
        configure service credentials:</para>
      <programlisting language="ini">[service_credentials]
+...
 os_auth_url = http://<replaceable>controller</replaceable>:5000/v2.0
 os_username = ceilometer
 os_tenant_name = service
 os_password = <replaceable>CEILOMETER_PASS</replaceable>
-os_endpoint_type = internalURL</programlisting>
-    <para>Replace <replaceable>CEILOMETER_PASS</replaceable> with the password you chose for the
-      ceilometer user in the Identity service.</para>
+os_endpoint_type = internalURL
+os_region_name = regionOne</programlisting>
+    <para>Replace <replaceable>CEILOMETER_PASS</replaceable> with the password
+      you chose for the <literal>ceilometer</literal> user in the Identity
+      service.</para>
    </step>
-    <step os="ubuntu">
-      <para>In the <literal>[DEFAULT]</literal> section, configure the
-        log directory:</para>
-       <programlisting language="ini">[DEFAULT]
-log_dir = /var/log/ceilometer</programlisting>
+    <step>
+      <para>(Optional) To assist with troubleshooting,
+        enable verbose logging in the <literal>[DEFAULT]</literal>
+        section:</para>
+      <programlisting language="ini">[DEFAULT]
+...
+verbose = True</programlisting>
    </step>
  </procedure>
  <procedure>
-    <title>To finish installation</title>
+    <title>To finalize installation</title>
    <step os="ubuntu;debian">
-      <para>Restart the service with its new settings:</para>
+      <para>Restart the Telemetry service:</para>
      <screen><prompt>#</prompt> <userinput>service ceilometer-agent-compute restart</userinput></screen>
    </step>
    <step os="rhel;centos;fedora;sles;opensuse">
-      <para>Start the service and configure it to start when the
+      <para>Start the Telemetry service and configure it to start when the
        system boots:</para>
      <screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>systemctl enable openstack-ceilometer-compute.service</userinput>
 <prompt>#</prompt> <userinput>systemctl start openstack-ceilometer-compute.service</userinput></screen>
--- a/doc/install-guide/section_ceilometer-verify.xml
+++ b/doc/install-guide/section_ceilometer-verify.xml
@ -5,30 +5,40 @@
  version="5.0"
  xml:id="ceilometer-verify">
  <title>Verify the Telemetry installation</title>
-  <para>To test the Telemetry installation, download an image from the
-    Image Service, and use the <command>ceilometer</command> command to display usage statistics.</para>
-
+  <para>This section describes how to verify operation of the Telemetry
+    module.</para>
  <procedure>
+    <note>
+      <para>Perform these commands on the controller node.</para>
+    </note>
    <step>
-      <para>Use the <literal>ceilometer meter-list</literal> command to test
-        the access to Telemetry:</para>
-      <screen><prompt>$</prompt> <userinput>ceilometer meter-list</userinput></screen>
-      <screen><computeroutput>+------------+-------+-------+--------------------------------------+---------+----------------------------------+
+      <para>Source the <literal>admin</literal> credentials to gain access to
+        admin-only CLI commands:</para>
+      <screen><prompt>$</prompt> <userinput>source admin-openrc.sh</userinput></screen>
+    </step>
+    <step>
+      <para>List available meters:</para>
+      <screen><prompt>$</prompt> <userinput>ceilometer meter-list</userinput>
+<computeroutput>+------------+-------+-------+--------------------------------------+---------+----------------------------------+
 | Name       | Type  | Unit  | Resource ID                          | User ID | Project ID                       |
 +------------+-------+-------+--------------------------------------+---------+----------------------------------+
 | image      | gauge | image | acafc7c0-40aa-4026-9673-b879898e1fc2 | None    | efa984b0a914450e9a47788ad330699d |
 | image.size | gauge | B     | acafc7c0-40aa-4026-9673-b879898e1fc2 | None    | efa984b0a914450e9a47788ad330699d |
 +------------+-------+-------+--------------------------------------+---------+----------------------------------+</computeroutput></screen>
+      <note>
+        <para>Some meters might not appear until after you successfully launch
+          at least one instance.</para>
+      </note>
    </step>
    <step>
      <para>Download an image from the Image Service:</para>
      <screen><prompt>$</prompt> <userinput>glance image-download "cirros-0.3.3-x86_64" > cirros.img</userinput></screen>
    </step>
    <step>
-      <para>Call the <literal>ceilometer meter-list</literal> command again to
-        validate that the download has been detected and stored by the Telemetry:</para>
-      <screen><prompt>$</prompt> <userinput>ceilometer meter-list</userinput></screen>
-      <screen><computeroutput>+----------------+-------+-------+--------------------------------------+---------+----------------------------------+
+      <para>List available meters again to validate detection of the image
+        download:</para>
+      <screen><prompt>$</prompt> <userinput>ceilometer meter-list</userinput>
+<computeroutput>+----------------+-------+-------+--------------------------------------+---------+----------------------------------+
 | Name           | Type  | Unit  | Resource ID                          | User ID | Project ID                       |
 +----------------+-------+-------+--------------------------------------+---------+----------------------------------+
 | image          | gauge | image | acafc7c0-40aa-4026-9673-b879898e1fc2 | None    | efa984b0a914450e9a47788ad330699d |
@ -38,9 +48,10 @@
 +----------------+-------+-------+--------------------------------------+---------+----------------------------------+</computeroutput></screen>
    </step>
    <step>
-      <para>You can now get usage statistics for the various meters:</para>
-      <screen><prompt>$</prompt> <userinput>ceilometer statistics -m image.download -p 60</userinput></screen>
-      <screen><computeroutput>+--------+---------------------+---------------------+-------+------------+------------+------------+------------+----------+----------------------------+----------------------------+
+      <para>Retrieve usage statistics from the <literal>image.download</literal>
+        meter:</para>
+      <screen><prompt>$</prompt> <userinput>ceilometer statistics -m image.download -p 60</userinput>
+<computeroutput>+--------+---------------------+---------------------+-------+------------+------------+------------+------------+----------+----------------------------+----------------------------+
 | Period | Period Start        | Period End          | Count | Min        | Max        | Sum        | Avg        | Duration | Duration Start             | Duration End               |
 +--------+---------------------+---------------------+-------+------------+------------+------------+------------+----------+----------------------------+----------------------------+
 | 60     | 2013-11-18T18:08:50 | 2013-11-18T18:09:50 | 1     | 13167616.0 | 13167616.0 | 13167616.0 | 13167616.0 | 0.0      | 2013-11-18T18:09:05.334000 | 2013-11-18T18:09:05.334000 |