Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
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: 4 days 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 2 years ago)
- Default Branch: master
- Last Pushed: 2024-11-30T07:11:20.000Z (23 days ago)
- Last Synced: 2024-12-11T11:39:03.160Z (12 days 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
1.0.0
...
...
...
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
[email protected]@
[email protected]@
```
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 cartApiSimpleHofundHttpConnection(){
return new SimpleHofundHttpConnection("car-api", "http://host.docker.internal:18084/actuator/health/info");
}
}
```
```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. 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.
### 6. Currently supported spring datasource's for auto-detection and providing `hofund_connection`:
- PostgreSQL
- Oracle
### 7. Connection Tabel
This simple functionality allows to print connections status in logger during booting up!
```txt
+----------+--------------+----------+----------------------------------------------+
| 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:
```java
@Slf4j
@Component
public class PrintHofundConnectionsTabel {
@Autowired
public PrintHofundConnectionsTabel(HofundConnectionsTable connectionsTable) {
log.info(connectionsTable.print());
}
}
```
# 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)