home/docs/help/http_sd.md
HertzBeat integrates with custom HTTP APIs to automatically discover service instances and create monitoring tasks for them.
HTTP Service Discovery allows HertzBeat to discover service instances by calling your custom HTTP API. This is the most flexible service discovery method, suitable for any system that can expose service instance information via HTTP API. You only need to provide an HTTP endpoint that returns a list of target addresses in the specified format.
You need to provide or develop an HTTP API that meets the following requirements:
target field (note: singular), which is a string array. Each string is a service instance address in the format host:port[
{
"target": [
"192.168.1.101:8080",
"192.168.1.102:8080",
"192.168.1.103:8080",
"api.example.com:443"
]
}
]
| Parameter name | Parameter help description |
|---|---|
| Target Name | Identify the name of this monitoring. The name needs to be unique. |
| Service Discovery Url | HTTP API address for service discovery. Must start with http:// or https://. Example: http://api.example.com/services |
| Auth Type | Authentication method, optional values: Bearer Token, Basic Auth, Digest Auth. Default: None |
| Access Token | Token for authentication when Auth Type is Bearer Token. |
| Username | Username for authentication when Auth Type is Basic Auth or Digest Auth. |
| Password | Password for authentication when Auth Type is Basic Auth or Digest Auth. |
| Collection interval | Interval time of monitor periodic data collection, unit: second, and the minimum interval that can be set is 30 seconds. |
| Description remarks | For more information about identifying and describing this monitoring, users can note information here. |
Prepare HTTP API
Create Service Discovery Monitoring
Configure Monitoring Template
Automatic Discovery
Suppose you have a service management API:
API URL: http://service-manager.example.com/api/v1/services
Response:
[
{
"target": [
"10.0.1.10:8080",
"10.0.1.11:8080",
"10.0.1.12:8080"
]
}
]
Configuration example:
HTTP-Service-Discoveryhttp://service-manager.example.com/api/v1/services60 secondsPort monitoringIf your API requires Bearer Token authentication:
https://api.example.com/servicesBearer Tokenyour-bearer-token-hereConfiguration example:
Secure-API-Discoveryhttps://api.example.com/servicesBearer TokenHTTP monitoringIf your API requires Basic authentication:
http://api.internal.com/discoverBasic Authadminpassword123Configuration example:
Basic-Auth-Discoveryhttp://api.internal.com/discoverBasic Authadminpassword123target field (note: singular, string array)host:port, for example:
192.168.1.100:8080api.example.com:443localhost:3000| Metric name | Metric unit | Metric help description |
|---|---|---|
| target | none | Discovered service instance target |
| host | none | Service instance host address |
| port | none | Service instance port number |
While the basic requirement is just the target field, your API can include additional metadata for future extensions:
[
{
"target": [
"192.168.1.10:8080"
],
"labels": {
"env": "production",
"version": "1.0.0"
}
}
]
Note: Currently, only the target field is used for service discovery, but future versions may support using label information.
@RestController
@RequestMapping("/api/v1")
public class ServiceDiscoveryController {
@GetMapping("/services")
public List<Map<String, Object>> getServices() {
List<String> targets = Arrays.asList(
"192.168.1.10:8080",
"192.168.1.11:8080",
"192.168.1.12:8080"
);
Map<String, Object> response = new HashMap<>();
response.put("target", targets);
return Collections.singletonList(response);
}
}
app.get('/api/services', (req, res) => {
const targets = [
'192.168.1.10:8080',
'192.168.1.11:8080',
'192.168.1.12:8080'
];
res.json([{
target: targets
}]);
});