https://github.com/logchange/hofund
🗡️💥 hofund is a tool set to monitor applications, connections and discover current state of components of the system 💥🗡️
https://github.com/logchange/hofund
connections discovery grafana hofund metrics micrometer monitoring prometheus spring-boot tool
Last synced: about 2 months ago
JSON representation
🗡️💥 hofund is a tool set to monitor applications, connections and discover current state of components of the system 💥🗡️
- Host: GitHub
- URL: https://github.com/logchange/hofund
- Owner: logchange
- License: apache-2.0
- Created: 2022-05-29T20:14:37.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2024-11-30T07:11:20.000Z (11 months ago)
- Last Synced: 2024-12-11T11:39:03.160Z (10 months ago)
- Topics: connections, discovery, grafana, hofund, metrics, micrometer, monitoring, prometheus, spring-boot, tool
- Language: Java
- Homepage:
- Size: 1.36 MB
- Stars: 55
- Watchers: 4
- Forks: 2
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# 🗡️💥 hofund 💥🗡️
# Introduction
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.
## Project name and pronunciation
[pronunciation in Old Norse](https://forvo.com/word/h%C7%ABfu%C3%B0/) also you can pronunce it as`ho` `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.
```
## Compatibility
| 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 |
## Requirements
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
# Usage
## SpringBoot based projects
### 1. Add to your pom.xml:
```xml
...
...
dev.logchange.hofund
hofund-spring-boot-starter
2.7.2
...
...
...
io.github.git-commit-id
git-commit-id-maven-plugin
7.0.0
get-the-git-infos
revision
initialize
true
false
true
...
...
...
```
### 2. Check if your project already contains SpringBoot Actuator with Micrometer or add it:
```xml
org.springframework.boot
spring-boot-starter-actuator
io.micrometer
micrometer-registry-prometheus
```
And your application should have the following configuration:
```properties
management.endpoints.web.exposure.include=prometheus
```
or
```yaml
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:
```properties
hofund.info.application.name=@project.name@
hofund.info.application.version=@project.version@
```
or
```yaml
hofund:
info:
application:
name: @project.name@
version: @project.version@
```
You can also override custom values for `GitInfo` metrics
```properties
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
```
### 3. Now you can start your application and verify exposed prometheus metric:
```text
# 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
```
### 4. Testing connections
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:
```java
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
}
}
```
```java
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()`.
### 5. Manually creating HofundConnection
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
```java
// 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
);
```
#### Special values in HofundConnectionResult
- **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:
```java
// 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:
```java
// 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:
```json
{
"application": {
"name": "AppName",
"version": "25.3.1-SNAPSHOT"
}
}
```
### 6. Metrics description
- `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.
### 7. Currently supported spring datasource's for auto-detection and providing `hofund_connection`:
- PostgreSQL
- Oracle
- H2
### 8. Connection Tabel
This simple functionality allows printing connection statuses in the logger during booting up!
```txt
+----------+--------------+----------+----------------------------------------------+---------+------------------+
| 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:
```java
@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.
# Grafana Dashboards
## [hofund-node-graph.json](https://github.com/logchange/hofund/raw/master/grafana-dashboards/hofund-node-graph.json)
Import [hofund-node-graph.json](https://github.com/logchange/hofund/raw/master/grafana-dashboards/hofund-node-graph.json)
### Explanation
**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)
# Contribution
[](https://gitpod.io/#https://github.com/logchange/hofund)