TorqueBox BackStage

BackStage is a Sinatra application that when deployed into a TorqueBox server gives you visibility into the apps, queues, topics, message processors, jobs, and services, allowing you to browse settings and stats, and exposes some actions to allow you to change the operational state of the components:

• pause/resume queues and topics
• stop/start message processors, services, and jobs
• execute debug ruby code inside a runtime pool
• view stats on all of the above

In addition, BackStage allows you to browse messages on a queue, and hides some of the underlying complexity of how topics are implemented in HornetQ.

It basically acts as an friendly overlay for JMX, so is very easy to extend if there is more data you want to see. The data/actions that are available from BackStage are also available from /jmx-console (with the exception of queue message browsing), but are more accessible in BackStage.

Authentication

By default, access to BackStage is wide open. You can secure it by setting REQUIRE_AUTHENTICATION: true in the environment section of torquebox.yml:

environment:
  REQUIRE_AUTHENTICATION: true

This will enable basic JAAS authentication through TorqueBox. Use the rake task to add usernames and password:

$ rake torquebox:auth:adduser CREDENTIALS=username:password

Installation

BackStage can either be installed and deployed as a gem, or deployed from the application source.

As A Gem

First, install the gem:

jruby -S gem install torquebox-backstage

Then, deploy backstage using the backstage command. You can deploy with security disabled:

jruby -S backstage deploy

Or enable security by providing a username/password pair:

jruby -S backstage deploy --secure=username:password

From Source

Clone the git repo, then run bundler to install the needed gems (listed in the Gemfile):

jruby -S gem install bundler # if you haven't done so already
jruby -S bundle install

Once that's done, you can either deploy a deployment descriptor pointing at the checked out repo:

jruby -S rake torquebox:deploy

or archive and deploy it as a .knob (zipfile):

jruby -S rake torquebox:deploy:archive

By default, BackStage is deployed to the /backstage context (see the context: setting in torquebox.yml).

API

BackStage also provides a RESTful API that allows you to access almost any of the data or actions of the web UI (browsing messages via the API is not yet available). The API provides a top level entry point at /api that returns a list of collection urls. The data is returned as JSON, and you must either pass format=json as a query parameter, or set the Accept: header to application/json. /api always returns JSON, no matter what Accept: header or format param you use, and all of the urls returned in the JSON include the format=json parameter.

Example

First, we retrieve the API entry point:

curl http://localhost:8080/backstage/api 

Returns:

{
  "collections":{
    "apps":"http://localhost:8080/backstage/apps?format=json",
    "queues":"http://localhost:8080/backstage/queues?format=json",
    "topics":"http://localhost:8080/backstage/topics?format=json",
    "message_processors":"http://localhost:8080/backstage/message_processors?format=json",
    "jobs":"http://localhost:8080/backstage/jobs?format=json",
    "services":"http://localhost:8080/backstage/services?format=json",
    "pools":"http://localhost:8080/backstage/pools?format=json",
    "logs":"http://localhost:8080/backstage/logs?format=json"
  }
}

Then, we'll use the url for services to retrieve the service index:

curl http://localhost:8080/backstage/services?format=json

Returns:

[
  {
    "resource":"http://localhost:8080/backstage/service/dG9ycXVlYm94LnNlcnZpY2VzOmFwcD1raXRjaGVuLXNpbmsudHJxLG5hbWU9QVNlcnZpY2U=?format=json",
    "name":"AService",
    "app":"http://localhost:8080/backstage/app/dG9ycXVlYm94LmFwcHM6YXBwPWtpdGNoZW4tc2luay50cnE=?format=json",
    "app_name":"kitchen-sink",
    "status":"Started",
    "actions":{
      "stop":"http://localhost:8080/backstage/service/dG9ycXVlYm94LnNlcnZpY2VzOmFwcD1raXRjaGVuLXNpbmsudHJxLG5hbWU9QVNlcnZpY2U=/stop?format=json"
    }
  }
]

Each index entry contains the full contents of the entry, along with URL to access the resource itself. URLs to associated resources are included as well (the app in this case).

If a resource has actions that can be performed on it, they will appear in the results under actions. Action urls must be called via POST, and return the JSON encoded resource:

curl -X POST http://localhost:8080/backstage/service/dG9ycXVlYm94LnNlcnZpY2VzOmFwcD1raXRjaGVuLXNpbmsudHJxLG5hbWU9QVNlcnZpY2U=/stop?format=json

Returns:

{
  "resource":"http://localhost:8080/backstage/service/dG9ycXVlYm94LnNlcnZpY2VzOmFwcD1raXRjaGVuLXNpbmsudHJxLG5hbWU9QVNlcnZpY2U=?format=json",
  "name":"AService",
  "app":"http://localhost:8080/backstage/app/dG9ycXVlYm94LmFwcHM6YXBwPWtpdGNoZW4tc2luay50cnE=?format=json",
  "app_name":"kitchen-sink",
  "status":"Stopped",
  "actions":{
    "start'":"http://localhost:8080/backstage/service/dG9ycXVlYm94LnNlcnZpY2VzOmFwcD1raXRjaGVuLXNpbmsudHJxLG5hbWU9QVNlcnZpY2U=/start'?format=json"
  }
}

Contributing

Bug reports, feature requests, and patches are always welcome! See http://torquebox.org/community/ on how to get in touch with the TorqueBox crew.

License

Copyright 2011 Red Hat, Inc.

Licensed under the Apache Software License version 2. See http://www.apache.org/licenses/LICENSE-2.0 for details.