Hawkular Inventory

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.

 

About Inventory

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.

Contributions

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.

Structure

The project is divided into several modules

• api: the Java API of Hawkular Inventory

• impl-tinkerpop: the default implementation of the API on top of Tinkerpop Gremlin 2.6.0.

• 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

Setup

Library

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

Web Application

The 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 $WILDFLY_HOME/standalone/data/hawkular-inventory.

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.

Configuration

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 support the TransactionalGraph interface.

Description of the API

Package org.hawkular.inventory.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 ReadInterface, WriteInterface and RelateInterface),

• ones that define the possible next steps on walk, divided into so-called Single or Multiple interfaces (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 Environments class defines the traversal interfaces Environments.Single and Environments.Multiple and the operation interfaces Environments.Read, Environments.ReadWrite and 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.

Package org.hawkular.inventory.api.model

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.

Package org.hawkular.inventory.filters

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.

Logger

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

Rest Tests

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

License

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 ./mvnw license:format.