Hofund is a tool set to monitor applications, connections and discover current state of components of the system. Exposed metric are gathered by prometheus and provides information about system health.

pronunciation in Old Norse also you can pronunce it asho fund

Hǫfuð ("man-head," Norwegian hoved, Danish hoved, Swedish huvud and Icelandic höfuð) 
is the sword of Heimdallr.

"Where’s the sword? That sword is the key to opening the Bifrost." ― Hela

Hofund, often simply referred as the Bifrost Sword, was an Asgardian sword used 
by Heimdall and, during his exile, Skurge. 
It also served as a key to activate the switch that opens the Bifrost Bridge.

You can check following requirements by running mvn dependency:tree, but if you are using spring-boot in version at least 2.2.0 everything should be alright.

Your project has to contain:

• spring-framework in version at least 5.2.12.RELEASE
• spring-boot in version at least 2.2.0
• micrometer-io in version at least 1.3.0
• slf4j in version at least 1.7.28

<project>
   ...
   <dependencies>
      ...
       <dependency>
           <groupId>dev.logchange.hofund</groupId>
           <artifactId>hofund-spring-boot-starter</artifactId>
           <version>1.0.0</version>
       </dependency>
      ...
   </dependencies>
   
   <build>
       ...
       <plugins>
          ...
         <groupId>io.github.git-commit-id</groupId>
         <artifactId>git-commit-id-maven-plugin</artifactId>
         <version>7.0.0</version> 
         <!-- 
         For older version of java (f.e. 8) see https://github.com/git-commit-id/git-commit-id-maven-plugin 
         And https://github.com/logchange/hofund/tree/0.6.0?tab=readme-ov-file#1-add-to-your-pomxml 
          -->
         <executions>
           <execution>
             <id>get-the-git-infos</id>
             <goals>
               <goal>revision</goal>
             </goals>
             <phase>initialize</phase>
           </execution>
         </executions>
         <configuration>
           <generateGitPropertiesFile>true</generateGitPropertiesFile>
           <failOnNoGitDirectory>false</failOnNoGitDirectory>
           <injectAllReactorProjects>true</injectAllReactorProjects>
         </configuration>
          ...
       </plugins>
       ...
   </build>
   ...
</project>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>

    <dependency>
        <groupId>io.micrometer</groupId>
        <artifactId>micrometer-registry-prometheus</artifactId>
    </dependency>
</dependencies>

And your application should have the following configuration:

management.endpoints.web.exposure.include=prometheus

or

management:
  endpoints:
    web:
      exposure:
        include: "prometheus"

To define basic information about our application in hofund metric we need some configuration. For maven project add to your application.properties following entries, but you can define it as you wish:

hofund.info.application.name=@project.name@
hofund.info.application.version=@project.version@

or

hofund:
  info:
    application:
      name: @project.name@
      version: @project.version@

You can also overrride custom values for GitInfo metrics

hofund.git-info.commit.id=someid  # default value is equal to git.commit.id property from git.properties file generated by git-commit-id-maven-plugin
hofund.git-info.commit.id-abbrev=someAbbrevId # default value is equal to git.commit.id.abbrev
hofund.git-info.dirty=true # default value is equal to git.dirty
hofund.git-info.branch=feature-1 # default value is equal to git.branch
hofund.git-info.build.host=someHost # default value is equal to git.build.host
hofund.git-info.build.time=11:12:13T11-11-2023 # default value is equal to git.build.time

# HELP hofund_info Basic information about application
# TYPE hofund_info gauge
hofund_info{application_name="cart",application_version="1.0.4-SNAPSHOT",id="cart",} 1.0
# HELP hofund_connection Current status of given connection
# TYPE hofund_connection gauge
hofund_connection{id="cart-cart_database",source="cart",target="cart_database",type="database",} 1.0
# HELP hofund_git_info Basic information about application based on git
# TYPE hofund_git_info gauge
hofund_git_info{branch="master",build_host="DESKTOP-AAAAA",build_time="2023-02-19T11:22:34+0100",commit_id="0d32d0f",dirty="true",} 1.0

You can define your own HofundConnectionsProvider but if you want to test HTTP connection the easiest way is to configure SimpleHofundHttpConnection or extend AbstractHofundBasicHttpConnection. If your project is based on spring you can extend it like below:

package dev.logchange.hofund.testapp.stats.health;
import dev.logchange.hofund.connection.SimpleHofundHttpConnection;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Bean;

@Configuration
public class SimpleHofundHttpConnectionConfiguration {
    
    @Bean 
    public SimpleHofundHttpConnection paymentApiSimpleHofundHttpConnection(){
        return new SimpleHofundHttpConnection("payment-api", "http://host.docker.internal:18083/actuator/health/info");
    }

    @Bean
    public SimpleHofundHttpConnection cartApiSimpleHofundHttpConnection(){
        return new SimpleHofundHttpConnection("car-api", "http://host.docker.internal:18084/actuator/health/info");
    }
}

package dev.logchange.hofund.testapp.stats.health;

import dev.logchange.hofund.connection.AbstractHofundBasicHttpConnection;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;

@Component
public class PaymentsHealthCheck extends AbstractHofundBasicHttpConnection {


    @Value("${hofund.connection.payment.target:payment}")
    private String target;

    @Value("${hofund.connection.payment.url:http://host.docker.internal:18083/}")
    private String basicUrl;

    @Value("${hofund.connection.payment.url.suffix:actuator/health/info}")
    private String urlSuffix;

    @Override
    protected String getTarget() {
        return target;
    }

    @Override
    protected String getUrl() {
        return basicUrl + urlSuffix;
    }

}

Extending AbstractHofundBasicHttpConnection is really simple, you only have to overrider getTarget() and getUrl() methods. The example above allows you to change values through spring application properties.

If you want to use f.e POST method, you can use new SimpleHofundHttpConnection("abc", "some_url", RequestMethod.POST) or override getRquestMethod().

If you don't want to test connection in some conditions, you can use new SimpleHofundHttpConnection("abc", "some_url", CheckingStatus.INACTIVE) or override getCheckingStatus().

• hofund_info - used to detect if application is running and what version is used. Application name and id in the metric is always lowercase to make easier creation of connection graph.

• hofund_connection - used to examine connection status to given services such as databases, rest apis etc. Source is a name of the current application (lowercase) and target is a name of service that we want to connect to joint with target type(also lowercase). Id is created by joining this two properties. Values:

  • 1 - Connection is okay (UP)
  • 0 - Connection is broken (DOWN)
  • -1 - Connection is not tested (INACTIVE)

• hofund_git_info - used to inform about build and git-based information such as: commit id(short), dirtiness(dirty - uncommitted changes), build machine name and time, branch. This information is useful for sandbox environments, where everything is changing really fast.

- PostgreSQL
- Oracle

This simple functionality allows to print connections status in logger during booting up!

+----------+--------------+----------+----------------------------------------------+
| TYPE     | NAME         | STATUS   | URL                                          |
+----------+--------------+----------+----------------------------------------------+
| DATABASE | mydb         | UP       | jdbc:postgresql://localhost:5432/mydb        |
| DATABASE | mydb2        | UP       | jdbc:mysql://localhost:3306/mydb2            |
| DATABASE | orcl         | DOWN     | jdbc:oracle:thin:@localhost:1521:orcl        |
| HTTP     | external-api | UP       | https://api.external-service.com             |
| HTTP     | internal-api | UP       | https://api.internal-service.local           |
| HTTP     | public-API   | INACTIVE | https://api.public-service.com               |
+----------+--------------+----------+----------------------------------------------+

You can achieve this by creating simple class:

@Slf4j
@Component
public class PrintHofundConnectionsTabel {

    @Autowired
    public PrintHofundConnectionsTabel(HofundConnectionsTable connectionsTable) {
        log.info(connectionsTable.print());
    }
}

Import hofund-node-graph.json

Node colors:

• $\textcolor{green}{\text{green}}$ - node is working correctly
• $\textcolor{red}{\text{red}}$ - node is down, does not respond
• $\textcolor{blue}{\text{blue}}$ - node is not tracked by hofund, it can be external service or database.

Node values (inside):

• Upper value: 0 or 1 - 0 node is down and 1 node is up.
• Lower value: from 0 to 1 - % of node is up during week.

Node title (under node):

• title: name of the node.
• subtitle: version (for monitored nodes) and type for external nodes.

Edge values (when hovered):

• Upper value: -1 or 0 or 1 - 0 connection is down and 1 connection is ok, -1 connection is inactive
• Lower value: from 0 to 1 - % of connection is ok during week (without time when connection is inactive)