0
# System Services
1

2
CDAP provides access to various system services for metrics collection, service discovery, administrative operations, and security management. These services enable applications to integrate with the CDAP platform infrastructure.
3

4
## Capabilities
5

6
### Metrics Collection
7

8
Interface for collecting custom application metrics that integrate with CDAP's monitoring system.
9

10
```java { .api }
11
/**
12
 * Interface for collecting user-defined metrics in CDAP applications
13
 */
14
public interface Metrics {
15
    /**
16
     * Increases the value of a counter metric by the specified amount
17
     * @param metricName Name of the counter (use alphanumeric characters)
18
     * @param delta The value to increase by
19
     */
20
    void count(String metricName, int delta);
21
    
22
    /**
23
     * Sets a gauge metric to the provided value
24
     * @param metricName Name of the gauge (use alphanumeric characters) 
25
     * @param value The value to be set
26
     */
27
    void gauge(String metricName, long value);
28
}
29
```
30

31
### Service Discovery
32

33
Interface for discovering and accessing services within the CDAP environment.
34

35
```java { .api }
36
/**
37
 * Interface for discovering service endpoints within CDAP
38
 */
39
public interface ServiceDiscoverer {
40
    /**
41
     * Discover the base URL for a service in a specific application
42
     * @param applicationId Application name
43
     * @param serviceId Service name
44
     * @return URL for the discovered service or null if not found
45
     */
46
    @Nullable
47
    URL getServiceURL(String applicationId, String serviceId);
48
    
49
    /**
50
     * Discover the base URL for a service in the same application
51
     * @param serviceId Service name
52
     * @return URL for the discovered service or null if not found
53
     */
54
    @Nullable
55
    URL getServiceURL(String serviceId);
56
}
57
```
58

59
### Administrative Operations
60

61
Interface providing access to administrative operations for datasets, messaging, and security.
62

63
```java { .api }
64
/**
65
 * Interface for operational administrative calls within CDAP applications
66
 */
67
@Beta
68
public interface Admin extends DatasetManager, SecureStoreManager, MessagingAdmin {
69
    // Inherits methods for dataset management, secure storage, and messaging administration
70
}
71
```
72

73
### Runtime Metrics
74

75
Interface for accessing runtime metrics and performance information.
76

77
```java { .api }
78
/**
79
 * Interface providing access to runtime metrics
80
 */
81
public interface RuntimeMetrics {
82
    // Methods for accessing runtime performance metrics
83
}
84
```
85

86
### Metrics Collection
87

88
Interface for advanced metrics collection with additional capabilities.
89

90
```java { .api }
91
/**
92
 * Extended interface for metrics collection
93
 */
94
public interface MetricsCollector {
95
    // Advanced metrics collection methods
96
}
97
```
98

99
**Usage Examples:**
100

101
```java
102
import co.cask.cdap.api.metrics.Metrics;
103
import co.cask.cdap.api.ServiceDiscoverer;
104
import co.cask.cdap.api.Admin;
105

106
public class SystemServicesExample extends AbstractService {
107
    
108
    // Metrics collection example
109
    public void collectMetrics(Metrics metrics) {
110
        // Count events
111
        metrics.count("user.logins", 1);
112
        metrics.count("data.processed.records", 100);
113
        
114
        // Set gauge values  
115
        metrics.gauge("queue.size", getCurrentQueueSize());
116
        metrics.gauge("memory.usage.bytes", getMemoryUsage());
117
        
118
        // Error counting
119
        try {
120
            processData();
121
            metrics.count("operations.success", 1);
122
        } catch (Exception e) {
123
            metrics.count("operations.error", 1);
124
            throw e;
125
        }
126
    }
127
    
128
    // Service discovery example
129
    public void discoverServices(ServiceDiscoverer discoverer) {
130
        // Discover service in same application
131
        URL dataService = discoverer.getServiceURL("data-processor");
132
        if (dataService != null) {
133
            callDataService(dataService);
134
        }
135
        
136
        // Discover service in different application
137
        URL analyticsService = discoverer.getServiceURL("analytics-app", "analytics-service");
138
        if (analyticsService != null) {
139
            callAnalyticsService(analyticsService);
140
        }
141
    }
142
    
143
    // Administrative operations example
144
    public void performAdminOperations(Admin admin) {
145
        // Dataset management operations
146
        // Secure store operations  
147
        // Messaging administration
148
        // (Specific methods depend on inherited interfaces)
149
    }
150
    
151
    private void callDataService(URL serviceURL) {
152
        // Make HTTP calls to discovered service
153
        String endpoint = serviceURL.toString() + "/api/process";
154
        // HTTP client implementation
155
    }
156
    
157
    private void callAnalyticsService(URL serviceURL) {
158
        // Make HTTP calls to analytics service
159
        String endpoint = serviceURL.toString() + "/api/analyze";
160
        // HTTP client implementation
161
    }
162
    
163
    private int getCurrentQueueSize() {
164
        // Implementation to get current queue size
165
        return 42;
166
    }
167
    
168
    private long getMemoryUsage() {
169
        // Implementation to get memory usage
170
        return Runtime.getRuntime().totalMemory() - Runtime.getRuntime().freeMemory();
171
    }
172
    
173
    private void processData() throws Exception {
174
        // Data processing implementation
175
    }
176
}
177
```
178

179
## Service Access Patterns
180

181
### Metrics Integration
182
- **Built-in collection**: Metrics automatically integrate with CDAP monitoring
183
- **Custom metrics**: Applications can define domain-specific metrics
184
- **Aggregation**: Platform provides aggregation and reporting capabilities
185
- **Alerting**: Metrics can trigger alerts and notifications
186

187
### Service Communication
188
- **Dynamic discovery**: Services can be discovered at runtime
189
- **Load balancing**: Platform handles load balancing for discovered services
190
- **Health checking**: Automatic health monitoring of discovered services
191
- **Failover**: Built-in failover mechanisms for service communication
192

193
### Administrative Access
194
- **Dataset operations**: Create, update, and manage datasets programmatically
195
- **Security management**: Access secure storage and credential management
196
- **Messaging control**: Administrative control over messaging systems
197
- **Resource management**: Monitor and control application resources
198

199
### Best Practices
200

201
**Metrics Collection:**
202
- Use descriptive metric names with consistent naming conventions
203
- Avoid high-cardinality metrics that can impact performance
204
- Aggregate metrics appropriately for your monitoring needs
205
- Include error and success metrics for operational visibility
206

207
**Service Discovery:**
208
- Cache service URLs when appropriate to reduce discovery overhead
209
- Handle null returns gracefully when services are unavailable
210
- Implement retry logic for transient discovery failures
211
- Use circuit breaker patterns for external service calls
212

213
**Administrative Operations:**
214
- Use administrative interfaces sparingly and only when necessary
215
- Implement proper error handling for administrative operations
216
- Consider security implications of administrative access
217
- Log administrative operations for audit purposes