This is the inventory module for Hawkular - basically "the registry" of stuff in Hawkular.
Hawkular is a modular systems monitoring suite, that consists of several sub-projects for storing of metrics, alerting on incoming events and more. Those projects are developed in their own GitHub repositories and integrated in this project.
Inventory stores "entities" and relationships between them. There are several types of entities that the inventory understands and a handful of predefined relationship types. While one cannot declare a new type of entity, one can create arbitrary relationships between the entities, not just the predefined ones.
We gladly accept pull requests here on github. If you find a bug or have a feature you would like to see implemented, please file an issue in our issue tracking system here.
The project is divided into several modules
api: the Java API of Hawkular Inventory
rest-servlet: A JAX-RS servlet implementation that provides a gateway to the Java API. It creates a .war file that contain the Java API and implementation to be deployed into a WildFly server.
rest-test: Integration tests of the rest-api above
You can either use the inventory as a library - just depend on the
api module and have the
impl-tinkerpop module on
you class path. You can then start using the inventory by calling:
Inventory inventory = InventoryFactory.newInstance(); Configuration cfg = Configuration.builder()....build(); inventory.initialize(cfg); //off you go
rest-servlet module builds a web application archive
WAR which is by out-of-the-box deployable to a
Wildfly server. Additional libraries might be required on the classpath if deployed into other
containers (please inspect the
pom.xml file for the dependencies).
Once deployed to the Wildfly server, the application by default uses an in-memory graph database that is persisted to
a file on the default location of
The web application passes all system properties as the configuration of the inventory and hence it is possible to use the system properties to override those defaults. See the Configuration chapter for details.
It is possible to use other graph database that supports the Tinkerpop Blueprints API by providing the necessary
implementation configuration (i.e. use the
Configuration.Builder.withConfiguration() method or
Configuration.Builder.addConfigurationProperty() method. E.g. for the tinkerpop implementation of the inventory
(well, there is no other ATM ;) ) use the
blueprints.graph property to set the graph implementation class to use and
other properties that are specific to the chosen implementation to configure it. The supplied implementation must
Description of the API
Contains the interfaces that comprise the API + the entity and filtering classes. The API is not tied in any form to the underlying storage mechanism but expresses the graph nature of the inventory. The main idea of the API is that it
is highly regular
needs to express the "walk" through the inventory graph easily.
There are therefore 2 kinds of interfaces:
ones that express the common operations on various entities (expressed by the generic
ones that define the possible next steps on walk, divided into so-called
Multipleinterfaces (specific to each type of the entity) that support traversing from a single entity or from multiple entities respectively.
There is a bunch of final uninstantiable classes in this package with names in the plural of the various entity types.
These "wrap" the definition of the traversal and operation interfaces for given type of entity. I.e. the
class defines the traversal interfaces
Environments.Multiple and the operation interfaces
Environments.ReadRelate as its inner classes.
This pattern is followed for all the other entity types.
While the interfaces might look a bit impenetrable and hard to follow, they provide for a (IMHO) very nice flow when composing a traversal through the inventory, which can be illustrated by the following example:
Set<Metric> metrics = inventory.tenants().get("com.acme.tenant").environments().get("production").resources() .get("host").metrics().getAll(Related.asTargetWith(metricDefinition, Relationships.Wellknown.defines)).entities();
This will find all the metrics with the type defined by the metricDefinition which are associated with the "host" resource in the "production" environment of the "com.acme.tenant" tenant.
Contains the POJOs for various entities understood by the inventory. The POJO entity classes are immutable but should be
JAXB-friendly. Some of the classes define a
Blueprint inner class. Such blueprint classes are used when creating
an entity. You generally don’t need to provide all the data that the entity requires because some of it can be deduced
from the position in the traversal of the graph from where the
create method is being called.
There is a finite set of possible filter types which are captured by the various classes in this package. The base class
is surprisingly called
Filter and is basically only a marker class (with some builder-like facilities but no actual
filtering definitions possible). Other classes express the filtering by various relations in the inventory (with 1
generic relationship filter -
Related) or filtering by id or type - the
With class and its inner classes.
The idea of these filters is that the implementations of the API are not forced to provide some generic filtering mechanism but are only required to provide support for this small set of predefined filter types.
Hawkular-Inv uses Logger prefix
HAWKINV for logging with JBoss-Logging.
Code ranges are api: 1-999 impl-tinkerpop: 1000-1999 rest-api : 2000-2999
The rest-tests are not run by default as they need a running WildFly server with
rest-servlet web application
deployed. To run them manually you can specify not to skip them
./mvnw -Dmaven.test.skip=false test
Hawkular-Inventory is released under Apache License, Version 2.0 as described in the LICENSE document
Copyright 2015 Red Hat, Inc. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
During build if you are getting
Some files do not have the expected license header just run