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.
| Version | SpringBoot Version | Java Version |
|---|---|---|
| 2.X.X | from 3.3.0 | 17 (hofund-core 8) |
| 1.0.X (deprecated) | from 2.2.0 to 3.2.X | 8 |
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>2.7.2</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
-->
<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=prometheusor
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[email protected]@
hofund.info.application.version[email protected]@or
hofund:
info:
application:
name: @project.name@
version: @project.version@You can also override 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 carApiSimpleHofundHttpConnection() {
return new SimpleHofundHttpConnection("car-api", "http://host.docker.internal:18084/actuator/health/info");
}
@Bean
public SimpleHofundHttpConnection cartApiSimpleHofundHttpConnection() {
return new SimpleHofundHttpConnection("cart-api", "http://host.docker.internal:18085/actuator/health/info").withRequiredVersion("1.0.1"); // you can also define a required version of service
}
}
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().
You can also disable connection checks for specific targets using environment variables. Set environment variable named HOFUND_CONNECTION_<TARGET>_DISABLED (where <TARGET> is the uppercase value of the target name) is set to either true (case-insensitive) or 1. For example, to disable connection checks for a target named "payment-api", you would set the environment variable HOFUND_CONNECTION_PAYMENT_API_DISABLED=true.
If you need to create a HofundConnection manually, you must define a ConnectionFunction that will query the service you're interested in. The ConnectionFunction interface has a single method getConnection() that returns a HofundConnectionResult object.
The HofundConnectionResult stores:
- The connection status (UP, DOWN, or INACTIVE)
- The version of the connected service
// Example of manually creating a HofundConnection with a custom ConnectionFunction
new HofundConnection(
"my-service", // target name
"https://my-service.example.com/api", // URL
Type.HTTP, // connection target type (HTTP, DATABASE, QUEUE etc.)
new AtomicReference<>(() -> { // ConnectionFunction as lambda
// Your custom logic to check connection and get version
try {
// Query the service and determine status
return HofundConnectionResult.http(Status.UP, "1.2.3");
} catch (Exception e) {
return HofundConnectionResult.http(Status.DOWN, HofundConnectionResult.UNKNOWN);
}
}),
"Optional description" // description
);- UNKNOWN (
"UNKNOWN"): Used when it was not possible to retrieve version information from the service. - NOT_APPLICABLE (
"N/A"): Used when version information is not applicable for this connection type (e.g., database connections) or cannot be retrieved.
For database connections, you can use the factory method:
// For database connections, version is automatically set to NOT_APPLICABLE
HofundConnectionResult.db(Status.UP);For HTTP connections, you can specify the version or use HttpURLConnection:
// Specify status and version directly
HofundConnectionResult.http(Status.UP, "1.2.3");
// Or let HofundConnectionResult extract version from open HttpURLConnection
HofundConnectionResult.http(Status.UP, httpUrlConnection);By default, when using SimpleHofundHttpConnection or AbstractHofundBasicHttpConnection, hofund will attempt to retrieve version information from the target application. This requires the target application to expose version information at the provided endpoint URL in the following JSON format:
{
"application": {
"name": "AppName",
"version": "25.3.1-SNAPSHOT"
}
}-
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
- H2
This simple functionality allows printing connection statuses in the logger during booting up!
+----------+--------------+----------+----------------------------------------------+---------+------------------+
| TYPE | NAME | STATUS | URL | VERSION | REQUIRED VERSION |
+----------+--------------+----------+----------------------------------------------+---------+------------------+
| DATABASE | mydb | UP | jdbc:postgresql://localhost:5432/mydb | N/A | N/A |
| DATABASE | mydb2 | UP | jdbc:mysql://localhost:3306/mydb2 | N/A | N/A |
| DATABASE | orcl | DOWN | jdbc:oracle:thin:@localhost:1521:orcl | N/A | N/A |
| HTTP | external-api | UP | https://api.external-service.com | UNKNOWN | UNKNOWN |
| HTTP | internal-api | UP | https://api.internal-service.local | 1.0.0 | 1.0.1 |
| HTTP | public-API | INACTIVE | https://api.public-service.com | N/A | N/A |
+----------+--------------+----------+----------------------------------------------+---------+------------------+You can achieve this by creating simple class:
@Configuration
public class PrintHofundConnectionsTabel {
private static final Logger log = getLogger(PrintHofundConnectionsTabel.class);
@Bean
public CommandLineRunner printHofundTable(HofundConnectionsTable connectionsTable) {
return (_) -> log.info(connectionsTable.print());
}
}If you specified a required service version using SimpleHofundHttpConnection or AbstractHofundBasicHttpConnection, this method may log an error indicating that the current version of the service is lower than the required version.
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)
