0
# Health
1

2
The Health API provides health check endpoints for monitoring API and database availability.
3

4
## Capabilities
5

6
### HealthClient
7

8
Client for checking API and database health.
9

10
```java { .api }
11
/**
12
 * Check health of API and database
13
 *
14
 * @param requestOptions Optional request configuration
15
 * @return Health status response
16
 * @throws ServiceUnavailableError if service is unavailable (503)
17
 */
18
HealthResponse health();
19
HealthResponse health(RequestOptions requestOptions);
20
```
21

22
**Usage Examples:**
23

24
```java
25
import com.langfuse.client.LangfuseClient;
26
import com.langfuse.client.resources.health.types.*;
27
import com.langfuse.client.resources.health.errors.*;
28

29
LangfuseClient client = LangfuseClient.builder()
30
    .url("https://cloud.langfuse.com")
31
    .credentials("pk-lf-...", "sk-lf-...")
32
    .build();
33

34
try {
35
    HealthResponse health = client.health().health();
36
    System.out.println("Status: " + health.getStatus());
37
    System.out.println("Version: " + health.getVersion());
38
} catch (ServiceUnavailableError e) {
39
    System.err.println("Service unavailable: " + e.statusCode());
40
}
41
```
42

43
## Response Types
44

45
### HealthResponse
46

47
```java { .api }
48
/**
49
 * Health check response
50
 */
51
public final class HealthResponse {
52
    String getStatus();   // Health status (e.g., "ok")
53
    String getVersion();  // API version
54

55
    static Builder builder();
56
}
57
```
58

59
## Error Handling
60

61
### ServiceUnavailableError
62

63
The health endpoint may throw a `ServiceUnavailableError` (503 status code) when the service is unavailable.
64

65
```java
66
import com.langfuse.client.resources.health.errors.ServiceUnavailableError;
67

68
try {
69
    HealthResponse health = client.health().health();
70
    // Service is healthy
71
} catch (ServiceUnavailableError e) {
72
    // Service is unavailable
73
    System.err.println("Service unavailable: " + e.getMessage());
74
    System.err.println("Status code: " + e.statusCode());
75
}
76
```
77

78
## Monitoring Example
79

80
```java
81
import com.langfuse.client.LangfuseClient;
82
import com.langfuse.client.resources.health.types.*;
83
import com.langfuse.client.resources.health.errors.*;
84
import java.util.concurrent.*;
85

86
public class HealthMonitor {
87
    private final LangfuseClient client;
88
    private final ScheduledExecutorService scheduler;
89

90
    public HealthMonitor(LangfuseClient client) {
91
        this.client = client;
92
        this.scheduler = Executors.newScheduledThreadPool(1);
93
    }
94

95
    public void startMonitoring(int intervalSeconds) {
96
        scheduler.scheduleAtFixedRate(
97
            this::checkHealth,
98
            0,
99
            intervalSeconds,
100
            TimeUnit.SECONDS
101
        );
102
    }
103

104
    public void stopMonitoring() {
105
        scheduler.shutdown();
106
    }
107

108
    private void checkHealth() {
109
        try {
110
            HealthResponse health = client.health().health();
111
            System.out.println(
112
                "[" + java.time.Instant.now() + "] " +
113
                "Health: " + health.getStatus() +
114
                ", Version: " + health.getVersion()
115
            );
116
        } catch (ServiceUnavailableError e) {
117
            System.err.println(
118
                "[" + java.time.Instant.now() + "] " +
119
                "Service unavailable (503)"
120
            );
121
            // Trigger alert
122
        } catch (Exception e) {
123
            System.err.println(
124
                "[" + java.time.Instant.now() + "] " +
125
                "Health check failed: " + e.getMessage()
126
            );
127
        }
128
    }
129

130
    public static void main(String[] args) {
131
        LangfuseClient client = LangfuseClient.builder()
132
            .url("https://cloud.langfuse.com")
133
            .credentials("pk-lf-...", "sk-lf-...")
134
            .build();
135

136
        HealthMonitor monitor = new HealthMonitor(client);
137

138
        // Check health every 30 seconds
139
        monitor.startMonitoring(30);
140

141
        // Keep running
142
        try {
143
            Thread.sleep(Long.MAX_VALUE);
144
        } catch (InterruptedException e) {
145
            monitor.stopMonitoring();
146
        }
147
    }
148
}
149
```
150

151
## Best Practices
152

153
1. **Regular Checks**: Implement periodic health checks for monitoring
154
2. **Error Handling**: Handle ServiceUnavailableError gracefully
155
3. **Logging**: Log health check results for debugging
156
4. **Alerting**: Set up alerts for repeated failures
157
5. **Timeout**: Use reasonable timeout for health checks
158
6. **Startup**: Check health on application startup
159
7. **Dependencies**: Health endpoint checks both API and database
160

161
## Use Cases
162

163
### Application Startup
164

165
```java
166
public void initializeApplication() {
167
    LangfuseClient client = LangfuseClient.builder()
168
        .url("https://cloud.langfuse.com")
169
        .credentials("pk-lf-...", "sk-lf-...")
170
        .build();
171

172
    // Check health before starting
173
    try {
174
        HealthResponse health = client.health().health();
175
        System.out.println("Langfuse is available (version: " + health.getVersion() + ")");
176
    } catch (ServiceUnavailableError e) {
177
        System.err.println("WARNING: Langfuse is unavailable, starting in degraded mode");
178
    }
179
}
180
```
181

182
### Load Balancer Health Check
183

184
```java
185
@RestController
186
public class HealthController {
187
    private final LangfuseClient langfuseClient;
188

189
    @GetMapping("/health/langfuse")
190
    public ResponseEntity<String> checkLangfuseHealth() {
191
        try {
192
            HealthResponse health = langfuseClient.health().health();
193
            return ResponseEntity.ok("Langfuse: " + health.getStatus());
194
        } catch (ServiceUnavailableError e) {
195
            return ResponseEntity.status(503).body("Langfuse unavailable");
196
        }
197
    }
198
}
199
```
200

201
### Circuit Breaker Pattern
202

203
```java
204
import io.github.resilience4j.circuitbreaker.CircuitBreaker;
205

206
public class LangfuseHealthCircuitBreaker {
207
    private final LangfuseClient client;
208
    private final CircuitBreaker circuitBreaker;
209

210
    public boolean isHealthy() {
211
        return circuitBreaker.executeSupplier(() -> {
212
            try {
213
                HealthResponse health = client.health().health();
214
                return "ok".equals(health.getStatus());
215
            } catch (ServiceUnavailableError e) {
216
                return false;
217
            }
218
        });
219
    }
220
}
221
```
222

223
## Related Documentation
224

225
- [Exceptions](./exceptions.md) - Error types and handling
226
- [Client Configuration](./client-configuration.md) - Timeout configuration
227