0
# Heartbeat System
1

2
The heartbeat system provides periodic communication between Sentinel applications and dashboard servers to maintain connectivity and report application status. It includes automatic failover between multiple dashboard addresses and comprehensive application metadata reporting.
3

4
## Capabilities
5

6
### SimpleHttpHeartbeatSender
7

8
Main heartbeat sender implementation that manages communication with dashboard servers.
9

10
```java { .api }
11
/**
12
 * The heartbeat sender provides basic API for sending heartbeat request to provided target.
13
 * This implementation is based on a trivial HTTP client.
14
 */
15
public class SimpleHttpHeartbeatSender implements HeartbeatSender {
16
    
17
    /**
18
     * Constructor that initializes with default dashboard addresses.
19
     * Retrieves dashboard server list from TransportConfig.
20
     */
21
    public SimpleHttpHeartbeatSender();
22
    
23
    /**
24
     * Send heartbeat to Sentinel Dashboard. Each invocation of this method will send
25
     * heartbeat once. Sentinel core is responsible for invoking this method
26
     * at every intervalMs() interval.
27
     * @return whether heartbeat is successfully sent
28
     */
29
    public boolean sendHeartbeat() throws Exception;
30
    
31
    /**
32
     * Default interval in milliseconds of the sender. It would take effect only when
33
     * the heartbeat interval is not configured in Sentinel config property.
34
     * @return default interval of the sender in milliseconds (10000ms)
35
     */
36
    public long intervalMs();
37
}
38
```
39

40
**Usage Examples:**
41

42
```java
43
import com.alibaba.csp.sentinel.transport.heartbeat.SimpleHttpHeartbeatSender;
44
import com.alibaba.csp.sentinel.transport.HeartbeatSender;
45

46
// Create heartbeat sender
47
HeartbeatSender heartbeatSender = new SimpleHttpHeartbeatSender();
48

49
// Send single heartbeat
50
try {
51
    boolean success = heartbeatSender.sendHeartbeat();
52
    if (success) {
53
        System.out.println("Heartbeat sent successfully");
54
    } else {
55
        System.out.println("Failed to send heartbeat");
56
    }
57
} catch (Exception e) {
58
    System.err.println("Error sending heartbeat: " + e.getMessage());
59
}
60

61
// Get heartbeat interval
62
long interval = heartbeatSender.intervalMs(); // Returns 10000ms (10 seconds)
63

64
// Note: Sentinel core automatically manages periodic heartbeat sending
65
// Manual invocation is typically not needed in production
66
```
67

68
### HeartbeatMessage
69

70
Container for heartbeat message data that includes application metadata and system information.
71

72
```java { .api }
73
/**
74
 * Heart beat message entity.
75
 * The message consists of key-value pair parameters.
76
 */
77
public class HeartbeatMessage {
78
    
79
    /**
80
     * Constructor that auto-populates basic system information:
81
     * - hostname: system hostname
82
     * - ip: configured heartbeat client IP
83
     * - app: application name
84
     * - app_type: application type
85
     * - port: transport port
86
     */
87
    public HeartbeatMessage();
88
    
89
    /**
90
     * Register additional custom information in the heartbeat
91
     * @param key information key
92
     * @param value information value
93
     * @return this HeartbeatMessage for method chaining
94
     */
95
    public HeartbeatMessage registerInformation(String key, String value);
96
    
97
    /**
98
     * Generate the current message map with timestamp and version info.
99
     * Adds dynamic fields:
100
     * - v: Sentinel version
101
     * - version: current timestamp (via TimeUtil.currentTimeMillis())
102
     * - port: current transport port (updated from TransportConfig.getPort())
103
     * @return Map of all heartbeat parameters including static and dynamic fields
104
     */
105
    public Map<String, String> generateCurrentMessage();
106
}
107
```
108

109
**Usage Examples:**
110

111
```java
112
import com.alibaba.csp.sentinel.transport.heartbeat.HeartbeatMessage;
113

114
// Create heartbeat message with default system info
115
HeartbeatMessage heartbeat = new HeartbeatMessage();
116

117
// Add custom application information
118
heartbeat.registerInformation("environment", "production")
119
         .registerInformation("version", "1.0.0")
120
         .registerInformation("instance_id", "app-001");
121

122
// Generate complete message for sending
123
Map<String, String> messageData = heartbeat.generateCurrentMessage();
124

125
// The message will include:
126
// - hostname, ip, app, app_type, port (from constructor)
127
// - environment, version, instance_id (custom additions)
128
// - v, version (timestamp), port (from generateCurrentMessage)
129

130
System.out.println("Heartbeat data: " + messageData);
131
```
132

133
### Heartbeat Configuration
134

135
The heartbeat system automatically configures itself based on system settings:
136

137
**Default Values:**
138
- **Interval**: 10000ms (10 seconds)
139
- **HTTP Status Success**: 200 OK
140
- **Request Path**: Retrieved from TransportConfig.getHeartbeatApiPath()
141
- **Client IP**: Retrieved from TransportConfig.getHeartbeatClientIp()
142
- **Dashboard Addresses**: Retrieved from TransportConfig.getConsoleServerList()
143

144
**Address Failover:**
145
The heartbeat sender cycles through configured dashboard addresses. If one address fails, it automatically tries the next address in the list on subsequent heartbeat attempts.
146

147
**Automatic Information:**
148
Each heartbeat automatically includes:
149
- **hostname**: System hostname
150
- **ip**: Configured client IP address
151
- **app**: Application name from AppNameUtil
152
- **app_type**: Application type from SentinelConfig
153
- **port**: Current transport port
154
- **v**: Sentinel framework version
155
- **version**: Current timestamp (for tracking message freshness)
156

157
### Error Handling and Logging
158

159
The heartbeat system handles various error conditions gracefully:
160

161
**Connection Errors:**
162
- Network connectivity issues are logged and cause failover to next dashboard address
163
- Socket timeouts are handled with appropriate logging
164

165
**HTTP Errors:**
166
- Client errors (4xx): Logged as warnings with status code details
167
- Server errors (5xx): Logged as warnings with status code details
168
- Successful responses (200): Heartbeat considered successful
169

170
**Configuration Errors:**
171
- Missing dashboard addresses: Logged as warning, heartbeat disabled
172
- Invalid port configuration: Heartbeat skipped until port is initialized
173

174
All error conditions are logged using RecordLog with appropriate severity levels and do not throw exceptions to calling code.