How to develop on Hawkular

Hacking on Hawkular

Developing Hawkular

Hawkular is a set of projects and sub-projects developed together and than assembled in the Hawkular integration project.

The biggest part of the Hawkular server code is written in Java 8. Project assembly is run via Apache Maven.

The UI code consists mostly of AngularJS directives written in Typescript and then translated into JavaScript.

Source code all lives on GitHub at https://github.com/hawkular/

Components

The following table lists the components and their respective repository and issue trackers.

Name GitHub Bug tracking (JIRA) Description

Hawkular

…​/hawkular

HAWKULAR

The “glue” use all components to build the hawkular solution, this is the project that users would build and run, it consumes all the components. It also houses the UI console (ui/console) that is based on hawt.io (v2) Angular.js framework for integration with OpenShift Origin (v3) and Fabric8 consoles. Additional UI development documentation can be found at Hawkular UI Docs…​

Hawkular-Alerting

…​/hawkular-alerts

HWKALERTS

Model and services to model and define alerts. It also runs the engine to tell when an alert needs to be triggered. Hawkular Alerts Developer Guide…​

Hawkular-Metrics

…​/hawkular-metrics

HWKMETRICS

Model and service for metrics and availability storage.

Hawkular-Bus

…​/hawkular-bus

HAWKULAR

Communication back bone

Hawkular-Inventory

…​/hawkular-inventory

HWKINVENT

In charge of modeling the various components to monitor and their relationships.

Hawkular-Build-Tools

…​/hawkular-build-tools

HAWKULAR

Various tools to help for the build, contains checkstyle definitions for instance

Hawkular-Accounts

…​/hawkular-accounts

HAWKULAR

Authorization framework for Hawkular components. More…​

Hawkular-BTM

…​/hawkular-btm

HWKBTM

Business transaction management. Capture and analyse the flow of business transaction instances end to end, across server, tier, on-premises and cloud boundaries.

Component Dependencies

Component Dependencies
Figure 1. Component Dependencies

Terms

As Hawkular sometimes uses terms that not everyone is familiar with, we have assembled a list of terms.

Let us know what you think is missing.

Building

Each hawkular component should be buildable on its own, but may have dependencies on other components. We regularly publish snapshots into the JBoss Nexus snapshot repository.

Full distribution

To build the full distribution, you need to check out the main hawkular repo

git clone https://github.com/hawkular/hawkular.git
cd hawkular
mvn install
cd dist/target
unzip hawkular-1.0.0.Alpha13-SNAPSHOT.zip
cd hawkular-1.0.0.Alpha13-SNAPSHOT
bin/standalone.sh

When the server is running you can hit the UI at http://localhost:8080/

When you build Hawkular, all sub-components are deployed to modules/org/hawkular/nest/main/deployments/ inside the WildFly server.

If you want to hot-deploy your component during development, you need to enable the deployment scanner. You can do this via the JBoss CLI by running this command:

bin/jboss-cli.sh --connect --command='/subsystem=deployment-scanner/scanner=default/:write-attribute(name=scan-enabled,value=true)'

You can set this manually by editing standalone/configuration/standalone.xml and setting <deployment-scanner scan-enabled="true" …​. Once the scanner is enabled, you need to remove the respective component from the above modules directory. Now you can copy your component’s deployment into the scanner’s deployment directory at standalone/deployments/.

If you want to attach a remote debugger, you can start the server with --debug option like this: bin/standalone.sh --debug

Hack the code

When you decide you want to start coding on Hawkular and/or one of the sub-projects mentioned above, please visit the ide-configs section of the build-tools repository and download the respective settings file for your IDE. This settings file will help you applying the coding standards that are checked on mvn install runs.

To work on the code, it is best to fork the Hawkular repository and then work there on your changes.

Try to work in branches even inside your own repository, as this will make syncing with upstream much easier.

Once you have made a change ready to go, go to the respective GitHub repository and open a pull-request (see below).

make sure to run a full mvn clean install run on your code changes without any other options and fix any errors that appear.
If you work with Snapshot dependencies of other projects, it can be helpful to force check for updates with maven option -U

Submitting Pull-Requests

GitHub has the beautiful feature of Pull-Requests (PR). Once you are done with coding, commit and push the change to a a new branch in your personal fork. Then go to the fork on GitHub and your branch and open a Pull-Request. Please describe your change before submitting. GitHub has documentation on pull-requests

When the Pull-Request has been submitted, expect some reviews, questions and suggestions. If this leads to updated code, just push the additional commits to the branch you used to open the Pull-Request.

After the Pull-Request got merged into your branch you can delete it on GitHub with the "Delete branch button" on the PR itself. To also remove it from the local repo, you can run git fetch --prune like this:

$ git fetch --prune
From https://github.com/hawkular/hawkular
 x [deleted]         (none)     -> origin/pinger-update
Even if you have enough rights to directly commit to the target Hawkular repository, use a pull-request, so that peer-review and automatic checking (see next paragraph) can happen.

Reviewing/merging Pull-Requests

Before merging a Pull-Request, make sure that it builds when merged. The Hawkular repositories have been set up to run continuous integration (CI) on Pull-Requests.

Detail of a pull-request

In above detail view of a pull-request, you can see that the first commit (e44f90a) failed CI by the red cross next to the commit id. The commit after it then passed as you can see by the green check mark. Those markers are shown for commits on the Conversation and Commits tab in the GitHub UI.

Only merge Pull-Requests that have successfully passed CI

The Files Changed tab allow to review the commits as difference to the reference branch (usually master). It is possible to comment on individual lines by hovering the mouse cursor on the line separator between lne numbers and code until a little white plus on blue appears. Click on it and add your comment.

Add a line comment

If you have opened a comment, allow the submitter (and others) to reply and potentially update the code.

Do not merge your own PRs, but have someone else look over them

Criteria for merging

As a code-reviewer, try to apply these criteria before merging:

  • Code clean and understandable

  • Enough JavaDoc + other docs

  • Enough test coverage

After everything looks good, press the big green merge button :-)

Code Style

As already mentioned above, there are some coding conventions enforced by checkstyle. Please follow them. Using one of the IDE setup files will help you. Other than that there are other conventions we should follow

  • DO not throw NullPointerException when method arguments are null. Throw IllegalArgumentException instead.

  • Always use the loggers from org.jboss.logging

  • Use Java-standard package names, all lower case as in org.hawkular.my.coolpackage, org.hawkular.mycoolpackage or org.hawkular.my.cool.package. Do not use camelCase. Use underscores only if the name would otherwise be illegal.

Logging conventions

Hawkular components should use the JBoss Logging API. Logging configuration is delegated to the Wildfly server. Standalone components (not running on top of Wildfly) have to choose a logging backend. While not mandatory, logback is recommended as it is very flexible from a configuration standpoint.

When working with the JBoss Logging API:

  • Put message logger interfaces into a package named log

  • In message logger interfaces, method names should start with the log level (void infoServiceStarting())

  • Name logger instances log (private static final Logger log = …​)

  • Only put messages which need an id (level INFO and above) in message logger interfaces

Documentation

Documentation such as these pages, but also all the README files are written in AsciiDoc and use a file suffix of .adoc.

Jax-RS Rest-Interfaces are to be commented / annotated via Swagger Annotations, that allow for automatic creation of API documentation from the annotations and the Java elements they are applied to.

redhatlogo-white

© 2016 | Hawkular is released under Apache License v2.0