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
```