0
# Apache SkyWalking Server-Core
1

2
Apache SkyWalking server-core provides the foundational analysis engine, storage abstractions, and processing framework for the SkyWalking observability platform. It enables distributed tracing, metrics collection, and observability data analysis for microservices and cloud-native architectures.
3

4
## Package Information
5

6
- **Package Name**: org.apache.skywalking:server-core
7
- **Package Type**: Maven
8
- **Language**: Java 8+
9
- **Installation**: Add Maven dependency to your `pom.xml`
10

11
```xml
12
<dependency>
13
    <groupId>org.apache.skywalking</groupId>
14
    <artifactId>server-core</artifactId>
15
    <version>10.1.0</version>
16
</dependency>
17
```
18

19
## Core Imports
20

21
```java { .api }
22
// Core constants and utilities
23
import org.apache.skywalking.oap.server.core.Const;
24
import org.apache.skywalking.oap.server.core.RunningMode;
25
import org.apache.skywalking.oap.server.core.UnexpectedException;
26

27
// Analysis framework
28
import org.apache.skywalking.oap.server.core.analysis.Stream;
29
import org.apache.skywalking.oap.server.core.analysis.StreamProcessor;
30
import org.apache.skywalking.oap.server.core.analysis.SourceDispatcher;
31
import org.apache.skywalking.oap.server.core.analysis.IDManager;
32
import org.apache.skywalking.oap.server.core.analysis.TimeBucket;
33
import org.apache.skywalking.oap.server.core.analysis.DownSampling;
34

35
// Storage abstractions
36
import org.apache.skywalking.oap.server.core.storage.StorageDAO;
37
import org.apache.skywalking.oap.server.core.storage.IMetricsDAO;
38
import org.apache.skywalking.oap.server.core.storage.StorageData;
39

40
// Query services
41
import org.apache.skywalking.oap.server.core.query.MetricsQueryService;
42
import org.apache.skywalking.oap.server.core.query.TraceQueryService;
43
import org.apache.skywalking.oap.server.core.query.MetadataQueryService;
44

45
// Source processing
46
import org.apache.skywalking.oap.server.core.source.ISource;
47
import org.apache.skywalking.oap.server.core.source.SourceReceiver;
48

49
// Metrics and records
50
import org.apache.skywalking.oap.server.core.analysis.metrics.Metrics;
51
import org.apache.skywalking.oap.server.core.analysis.record.Record;
52
```
53

54
## Basic Usage
55

56
```java { .api }
57
// Example: Basic source processing
58
public class CustomSourceProcessor implements SourceDispatcher<CustomSource> {
59
    
60
    @Override
61
    public void dispatch(CustomSource source) {
62
        // Process incoming telemetry source
63
        source.prepare();
64
        
65
        // Generate entity ID using IDManager
66
        String serviceId = IDManager.ServiceID.buildId(source.getServiceName(), true);
67
        source.setEntityId(serviceId);
68
        
69
        // Set time bucket for metrics aggregation
70
        long timeBucket = TimeBucket.getMinuteTimeBucket(System.currentTimeMillis());
71
        source.setTimeBucket(timeBucket);
72
        
73
        // Forward to streaming process
74
        StreamProcessor.getInstance().in(source);
75
    }
76
}
77

78
// Example: Custom metrics implementation
79
@Stream(name = "custom_metrics", scopeId = 1, // DefaultScopeDefine.SERVICE = 1
80
        builder = CustomMetrics.Builder.class, processor = MetricsStreamProcessor.class)
81
public class CustomMetrics extends Metrics {
82
    
83
    @Getter @Setter private long value;
84
    
85
    @Override
86
    public boolean combine(Metrics metrics) {
87
        CustomMetrics custom = (CustomMetrics) metrics;
88
        this.value += custom.getValue();
89
        return true;
90
    }
91
    
92
    @Override
93
    public void calculate() {
94
        // Perform final calculations
95
    }
96
    
97
    @Override
98
    public Metrics toHour() {
99
        CustomMetrics hourMetrics = new CustomMetrics();
100
        hourMetrics.copyFrom(this);
101
        return hourMetrics;
102
    }
103
    
104
    @Override
105
    public Metrics toDay() {
106
        CustomMetrics dayMetrics = new CustomMetrics();
107
        dayMetrics.copyFrom(this);
108
        return dayMetrics;
109
    }
110
}
111
```
112

113
## Architecture
114

115
SkyWalking server-core is built around several key architectural components:
116

117
### Analysis Engine
118
The OAL (Observability Analysis Language) processing engine that transforms raw telemetry data into structured metrics and records.
119

120
### Stream Processing
121
High-performance streaming architecture for real-time data processing with configurable downsampling (minute, hour, day precision).
122

123
### Storage Abstraction Layer
124
Pluggable storage system supporting multiple backends (Elasticsearch, BanyanDB, MySQL, etc.) through unified DAO interfaces.
125

126
### Query Framework
127
Comprehensive query services providing APIs for metrics, traces, topology, logs, and metadata retrieval.
128

129
### Remote Communication
130
gRPC-based clustering and distributed processing capabilities for horizontal scaling.
131

132
## Capabilities
133

134
### Analysis Framework
135

136
Stream processing engine for telemetry data analysis with OAL language support.
137

138
```java { .api }
139
// Core stream processing
140
public interface StreamProcessor<STREAM> {
141
    void in(STREAM stream);
142
}
143

144
// Source dispatching
145
public interface SourceDispatcher<SOURCE> {
146
    void dispatch(SOURCE source);
147
}
148

149
// ID management for entities
150
public class IDManager {
151
    public static class ServiceID {
152
        public static String buildId(String name, boolean isNormal);
153
        public static ServiceIDDefinition analysisId(String id);
154
        public static String buildRelationId(ServiceRelationDefine define);
155
        public static ServiceRelationDefine analysisRelationId(String entityId);
156
    }
157
    
158
    public static class ServiceInstanceID {
159
        public static String buildId(String serviceId, String instanceName);
160
        public static InstanceIDDefinition analysisId(String id);
161
        public static String buildRelationId(ServiceInstanceRelationDefine define);
162
        public static ServiceInstanceRelationDefine analysisRelationId(String entityId);
163
    }
164
    
165
    public static class EndpointID {
166
        public static String buildId(String serviceId, String endpointName);
167
        public static EndpointIDDefinition analysisId(String id);
168
        public static String buildRelationId(EndpointRelationDefine define);
169
        public static EndpointRelationDefine analysisRelationId(String entityId);
170
    }
171
    
172
    public static class ProcessID {
173
        public static String buildId(String serviceInstanceId, String processName);
174
        public static String buildRelationId(ProcessRelationDefine define);
175
        public static ProcessRelationDefine analysisRelationId(String entityId);
176
    }
177
}
178
```
179

180
[Analysis Framework](./analysis-framework.md)
181

182
### Storage Layer
183

184
Pluggable storage abstractions supporting multiple backend implementations.
185

186
```java { .api }
187
// Storage DAO factory
188
public interface StorageDAO extends Service {
189
    IMetricsDAO newMetricsDao(StorageBuilder storageBuilder);
190
    IRecordDAO newRecordDao(StorageBuilder storageBuilder);
191
    INoneStreamDAO newNoneStreamDao(StorageBuilder storageBuilder);
192
}
193

194
// Metrics storage operations
195
public interface IMetricsDAO extends DAO {
196
    List<Metrics> multiGet(Model model, List<Metrics> metrics) throws IOException;
197
    InsertRequest prepareBatchInsert(Model model, Metrics metrics, 
198
                                   SessionCacheCallback callback) throws IOException;
199
}
200

201
// Storage entity interface
202
public interface StorageData {
203
    StorageID id();
204
    String TIME_BUCKET = "time_bucket";
205
}
206
```
207

208
[Storage Layer](./storage-layer.md)
209

210
### Query Services
211

212
Comprehensive query APIs for metrics, traces, topology and metadata.
213

214
```java { .api }
215
// Metrics querying
216
public class MetricsQueryService implements Service {
217
    public NullableValue readMetricsValue(MetricsCondition condition, Duration duration) 
218
        throws IOException;
219
    public MetricsValues readMetricsValues(MetricsCondition condition, Duration duration) 
220
        throws IOException;
221
    public List<MetricsValues> readLabeledMetricsValues(MetricsCondition condition, 
222
        List<KeyValue> labels, Duration duration) throws IOException;
223
}
224

225
// Trace querying  
226
public class TraceQueryService implements Service {
227
    // Query trace data and segments
228
}
229

230
// Metadata querying
231
public class MetadataQueryService implements Service {
232
    // Query services, instances, endpoints
233
}
234
```
235

236
[Query Services](./query-services.md)
237

238
### Remote Communication
239

240
gRPC-based inter-node communication for distributed processing.
241

242
```java { .api }
243
// Remote data transmission
244
public class RemoteSenderService implements Service {
245
    public void send(String nextWorkName, StreamData streamData, Selector selector);
246
}
247

248
// Serialization interfaces
249
public interface Serializable {
250
    // Marker for remote-serializable data
251
}
252

253
public interface Deserializable {
254
    // Marker for remote-deserializable data
255
}
256
```
257

258
[Remote Communication](./remote-communication.md)
259

260
### Configuration Management
261

262
Configuration services and component library management.
263

264
```java { .api }
265
// Configuration management
266
public class ConfigService implements Service {
267
    // General configuration management
268
}
269

270
// Component library catalog
271
public interface IComponentLibraryCatalogService extends Service {
272
    // Component library catalog management
273
}
274

275
// Naming control
276
public class NamingControl {
277
    // Entity naming rules and normalization
278
}
279
```
280

281
[Configuration](./configuration.md)
282

283
### Profiling Services
284

285
Trace profiling and performance analysis capabilities.
286

287
```java { .api }
288
// Profile task querying
289
public class ProfileTaskQueryService implements Service {
290
    // Query profiling task information
291
}
292

293
// Profile task management
294
public class ProfileTaskMutationService implements Service {
295
    // Create and manage profiling tasks
296
}
297

298
// Profile records
299
public class ProfileTaskRecord extends Record {
300
    // Storage record for profiling tasks
301
}
302
```
303

304
[Profiling](./profiling.md)
305

306
### Source Processing
307

308
Telemetry source handling and processing pipeline.
309

310
```java { .api }
311
// Base source interface
312
public interface ISource {
313
    int scope();
314
    long getTimeBucket();
315
    void setTimeBucket(long timeBucket);
316
    String getEntityId();
317
    void prepare();
318
}
319

320
// Source receiver
321
public interface SourceReceiver extends Service {
322
    // Receives and processes telemetry sources
323
}
324

325
// Source types
326
public class Service extends ISource { }
327
public class ServiceInstance extends ISource { }  
328
public class Endpoint extends ISource { }
329
public class DatabaseAccess extends ISource { }
330
```
331

332
[Source Processing](./source-processing.md)
333

334
## Core Types
335

336
```java { .api }
337
// Time bucket management
338
public class TimeBucket {
339
    public static long getRecordTimeBucket(long time);
340
    public static long getMinuteTimeBucket(long time);
341
    public static long getTimestamp(long timeBucket);
342
    public static long getTimestamp(long timeBucket, DownSampling downsampling);
343
    public static long getTimeBucket(long timestamp, DownSampling downsampling);
344
    public static boolean isSecondBucket(long timeBucket);
345
    public static boolean isMinuteBucket(long timeBucket);
346
    public static boolean isHourBucket(long timeBucket);
347
    public static boolean isDayBucket(long timeBucket);
348
}
349

350
// Downsampling precision levels
351
public enum DownSampling {
352
    None(0, ""),
353
    Second(1, "second"),
354
    Minute(2, "minute"),
355
    Hour(3, "hour"),
356
    Day(4, "day");
357
    
358
    public int getValue();
359
    public String getName();
360
}
361

362
// Storage identifier
363
public class StorageID {
364
    // Unique identifier in storage
365
}
366

367
// Stream definition
368
public class StreamDefinition {
369
    // Defines stream processing configurations
370
}
371

372
// Base metrics class
373
public abstract class Metrics extends StreamData implements StorageData {
374
    protected long timeBucket;
375
    protected long lastUpdateTimestamp;
376
    
377
    public abstract boolean combine(Metrics metrics);
378
    public abstract void calculate();
379
    public abstract Metrics toHour();
380
    public abstract Metrics toDay();
381
}
382

383
// Base record class  
384
public abstract class Record implements StorageData {
385
    protected long timeBucket;
386
}
387

388
// Default scope definitions for stream annotations
389
public class DefaultScopeDefine {
390
    public static final int SERVICE = 1;
391
    public static final int SERVICE_INSTANCE = 2;
392
    public static final int ENDPOINT = 3;
393
    public static final int SERVICE_RELATION = 4;
394
    public static final int SERVICE_INSTANCE_RELATION = 5;
395
    public static final int ENDPOINT_RELATION = 6;
396
    public static final int DATABASE_ACCESS = 7;
397
    public static final int ALL = 99;
398
}
399
```