ceph/src/brag/README.md

   1 # Ceph-brag
   2
   3 `ceph-brag` is going to be an anonymized cluster reporting tool designed to collect a "registry" of Ceph clusters for community knowledge.
   4 This data will be displayed on a public web page using UUID by default, but users can claim their cluster and publish information about ownership if they so desire.
   5
   6 For more information please visit:
   7
   8 * [Blueprint](http://wiki.ceph.com/Planning/Blueprints/Firefly/Ceph-Brag)
   9 * [CDS Etherpad](http://pad.ceph.com/p/cdsfirefly-ceph-brag)
  10
  11 # Client
  12
  13 ## How to use:
  14
  15 ### Pre-requisites:
  16 ceph-brag uses 'ceph' python script. Hence, before executing ceph-brag script ensure that ceph services are all running and 'ceph' script is in 'PATH' environment
  17
  18 ### Runtime instructions:
  19 Run 'ceph-brag -h' to get the usage information of this tool.
  20
  21 ### Sample output:
  22
  23     {
  24       "cluster_creation_date": "2014-01-16 13:38:41.928551",
  25       "uuid": "20679d0e-04b1-4004-8ee9-45ac271510e9",
  26       "components_count": {
  27         "num_data_bytes": 0,
  28         "num_bytes_total": 1209312904,
  29         "num_osds": 1,
  30         "num_objects": 0,
  31         "num_pgs": 192,
  32         "num_pools": 3,
  33         "num_mdss": 1,
  34         "num_mons": 1
  35       },
  36       "crush_types": [
  37         {
  38           "type": "osd"
  39           "count": 2,
  40         },
  41         {
  42           "type": "rack"
  43           "count": 1,
  44         },
  45         {
  46           "type": "host"
  47           "count": 1,
  48         },
  49         {
  50           "type": "root"
  51           "count": 1,
  52         }
  53       ],
  54       "ownership": {
  55         "organization": "eNovance",
  56         "description": "Use case1",
  57         "email": "mail@enovance.com",
  58         "name": "Cluster1"
  59       },
  60       "pool_metadata": [
  61         {
  62           "size": 3,
  63           "id": 0,
  64           "type": 1
  65         },
  66         {
  67           "size": 3,
  68           "id": 1,
  69           "type": 1
  70         },
  71         {
  72           "size": 3,
  73           "id": 2,
  74           "name": 1
  75         }
  76       ],
  77       "sysinfo": {
  78         "kernel_types": [
  79           {
  80             "count": 1,
  81             "type": "#36-Ubuntu SMP Tue Apr 10 22:29:03 UTC 2012"
  82           }
  83         ],
  84         "cpu_archs": [
  85           {
  86             "count": 1,
  87             "arch": "x86_64"
  88           }
  89         ],
  90         "cpus": [
  91           {
  92             "count": 1,
  93             "cpu": "Intel Xeon E312xx (Sandy Bridge)"
  94           }
  95         ],
  96         "kernel_versions": [
  97           {
  98             "count": 1,
  99             "version": "3.2.0-23-virtual"
 100           }
 101         ],
 102         "ceph_versions": [
 103           {
 104             "count": 1,
 105             "version": "0.75-229-g4050eae(4050eae32cd77a1c210ca11d0f12c74daecb1bd3)"
 106           }
 107         ],
 108         "os_info": [
 109           {
 110             "count": 1,
 111             "os": "Linux"
 112           }
 113         ],
 114         "distros": [
 115           {
 116             "count": 1,
 117             "distro": "Ubuntu 12.04 precise (Ubuntu 12.04 LTS)"
 118           }
 119         ]
 120       }
 121     }
 122
 123
 124 # Server
 125
 126 ## Info
 127 The ceph-brag server code is a python based web application.
 128
 129 ## How to use
 130
 131 ### Prerequisites
 132 * [pecan](http://pecanpy.org) is the web framework that is used by this application.
 133 * [sqlalchemy](www.sqlalchemy.org) is the ORM that is used by this application
 134
 135 ### How to deploy
 136 * [Common recipes to deploy](http://pecan.readthedocs.org/en/latest/deployment.html#common-recipes)
 137 * Modify server/config.py:sqlalchemy['url'] to point the correct database connection
 138
 139 ## URLs
 140 Following are the REST urls that are implemented with 'url-prefix' being the mount point for the WSGI script
 141
 142 ### GET
 143
 144 ##### * GET /url-prefix/
 145 Returns the list of clusters that are registered so far.
 146 Outputs - On success application/json of the following format is returned
 147
 148     [
 149       {
 150        "num_versions": 3,
 151        "cluster_creation_date": "2014-01-16 13:38:41.928551",
 152        "uuid": "20679d0e-04b1-4004-8ee9-45ac271510e9",
 153        "cluster_name": "Cluster1",
 154        "organization": "eNovance",
 155        "email": "mail@enovance.com"
 156       },
 157       ...
 158     ]
 159
 160 ##### * GET /url-prefix/UUID
 161 Returns the list of version information for a particular UUID.
 162 Outputs - On success application/json of the following format is returned
 163
 164     [
 165       {
 166         "version_number": 1,
 167         "version_date": "2014-02-10 10:17:56.283499"
 168       },
 169       ...
 170     ]
 171
 172 ##### * GET /url-prefix/UUID/version\_number
 173 Returns the entire brag report as mentioned in client's sample output for a particular version of a UUID
 174
 175 ### PUT
 176
 177 ##### * PUT /url-prefix
 178 Uploads the brag report and creates a new version for the UUID mentioned in the payload
 179
 180 ### DELETE
 181
 182 ##### * DELETE /url-prefix?uuid=xxxx
 183 Deletes all the versions of a cluster whose UUID is sent as a parameter
 184
 185