In this recipe, we have seen how to extract the data directly from our application and via Graphite, and render it using the Dashing dashboard as well as pushing information directly to Dashing using their RESTful API. It is no secret that it is better to see something once than hear about it seven times. This is true when it comes to trying to get a holistic picture of the key metrics that represent how the systems behave at runtime and to be able to act on the data quickly.

Without going in to great detail about the internals of Dashing, it is still important to mention a few things about how data gets in to Dashing. This can happen in the following two ways:

• Scheduled jobs: This is used to pull data from the external sources
• RESTful API: This is used to push data to Dashing from outside

The scheduled jobs are defined in the jobs directory in the generated dashboard application. Each file has a piece of ruby code wrapped in the SCHEDULER.every block, which computes the data points and sends an event to an appropriate widget with the new data for an update.

In our recipe, we created a new job named repo_counters.rb where we used the httparty library in order to make a direct call to our application instance's /actuator/metrics/#{name} endpoint and extracted the counters for each of the predefined repositories. Looping over the metrics, we created a repo_counts collection with data for each repository containing a label display and a value count. The resulting collection was sent to the repositories widget for an update in the form of event: send_event('repositories', { items: repo_counts }).

We configured this job to get executed every 10 seconds, but if the rate of data change is not very frequent, the number can be changed to a few minutes or even hours. Every time the scheduler runs our job, the repositories widget is updated via the client-side websockets communication with the new data. Looking in dashboards/sample.erb, we can find the widget's definition using data-id="repositories".

Besides adding our own new job, we also changed the existing sample.rb job to pull data from Graphite using Graphite's RESTful API to populate the different types of widgets in order to display the memory heap data. As we were not pulling data directly from the application instance, it was a good idea not to put the code in the same job because the jobs could—and in our case, do—have different time intervals. As we send data to Graphite only once every minute, it does not make sense to pull it any less frequently than this.

To get the data out of Graphite, we used the following API call:

/render/?from=-11minutes&target= bookpub.app.jvm.memory.used.area.heap.id.PS_Eden_Space &target= bookpub.app.jvm.memory.used.area.heap.id.PS_Survivor_Space &target= bookpub.app.jvm.memory.used.area.heap.id.PS_Old_Gen &format=json&maxDataPoints=11
  

Take a look at the following parameters mentioned in the preceding code snippet:

• target: This parameter is a repeated value that defines a list of all the different metrics that we want to retrieve.
• from: This parameter specifies the time range; in our case, we asked for data going back 11 minutes to.
• format: This parameter configures the desired output format. We chose JSON but many others are available. Refer to http://graphite.readthedocs.org/en/latest/render_api.html#format.
• maxDataPoints: This parameter indicates how many entries we want to get.

The reason we asked for 11 entries and not 10 is due to a frequent occurrence where the last entry of short-ranged requests, which consist of only a few minutes, sometimes get returned as empty. We just use the first 10 entries and ignore the most recent ones to avoid weird data visualization.

Iterating over the target data, we will populate the appropriate widgets such as heap_eden, heap_survivor, and heap_oldgen, with their designated data, as follows:

• heap_eden: This is a Graph widget, as defined in the sample.erb template in the form of a data-view="Graph"  attribute, so it wants a data input in the form of the points collection containing a value for x and y. The x value represents a timestamp, which conveniently gets returned to us by Graphite and is automatically converted to the minutes display value by the Graph widget. The y value represents the memory pool utilization in bytes. As the value from Graphite is in the form of a decimal number, we will need to convert it to a whole number so as to make it look better.
• heap_survivor: This is a Meter widget, as defined in the sample.erb template in the form of a data-view="Meter" attribute, so it wants a data input as a simple value number between a template configured range. In our case, the range is set as the data-min="0" data-max="100" attribute. Even though we chose to round the number to two decimal positions, it could probably just be an integer as it is precise enough for the purpose of a dashboard display. You will also notice that inside sample.rb, we convert the raw value, which is in bytes, into megabytes, for better readability— current_survivor = current_survivor / 1048576.
• heap_oldgen: This is a Number widget, as defined in the sample.erb template in the form of a data-view="Number" attribute, so it wants a data input as a current value and optionally a last value; in this case, a percentage change with the change direction will be displayed as well. As we get the last 10 entries, we have no issues in retrieving both the current and last values so we can easily satisfy this requirement.

In this recipe, we also experimented with Dashing's RESTful API by trying to use a curl command to update the value of the welcome widget. This was a push operation and can be used in situations where there is no data API exposed, but you have the capability of creating some sort of a script or piece of code that could send the data to Dashing instead. To achieve this, we used the following command: curl -d '{ "auth_token": "YOUR_AUTH_TOKEN", "text": "My RESTful dashboard update!" }' http://localhost:3030/widgets/welcome.

The Dashing API accepts data in a JSON format, sent via a POST request that contains the following parameters needed for the widgets as well as the widget ID, which is a part of the URL path itself:

• auth_token: This allows for a secure data update and can be configured in the dashboard root directory in the config.ru file.
• text: This is a widget property that is being changed. As we are updating a Text widget, as defined in the sample.erb template in the form of a data-view="Text" attribute, we need to send it to text to update.
• /widgets/<widget id>: This URL path identifies the particular widget where the update is destined to. The id corresponds to a declaration in the sample.erb template. In our case, it looks like data-id="welcome".

The definition of the various widgets can also be manipulated and a very rich collection of the various widgets has been created by the community, which is available at https://github.com/Shopify/dashing/wiki/Additional-Widgets. The widgets get installed in the widgets directory in the dashboard and can be installed by simply running dashing install <GIST>, where GIST is the hash of the GitHub Gist entry.

The dashboard template files, similar to our sample.erb template, can be modified in order to create the desired layout for each particular dashboard as well as multiple dashboard templates, which can be rotated or directly loaded manually.

Each dashboard represents a grid in which the various widgets get placed. Each widget is defined by a <div> entry with the appropriate configuration attributes and it should be nested in the <li> grid element. We can use the data element attributes to control the positioning of each widget in the grid, which is as follows:

• data-row: This represents the row number where the widget should be positioned
• data-col: This represents the column number where the widget should be positioned
• data-sizex: This defines the number of columns the widget will span horizontally
• data-sizey: This defines the number of rows the widget will span vertically

The existing widgets can be modified to change their look and feel as well as extend their functionality; so the sky is the limit for what kind of information display we can have. You should definitely check out http://dashing.io for more details.