tessl/maven-org-apache-skywalking--server-core
Core analysis engine and storage abstractions for Apache SkyWalking observability platform
—
Pending
configuration.mddocs/
Configuration
The SkyWalking configuration system provides centralized management of server settings, component library catalogs, entity naming rules, downsampling configurations, and service hierarchies. It supports dynamic configuration updates and pluggable configuration sources.
Core Configuration Services
ConfigService
Central service for general configuration management and dynamic updates.
public class ConfigService implements Service {
/**
* Gets configuration value by key
* @param key Configuration key
* @return Configuration value or null if not found
*/
public String getConfigValue(String key);
/**
* Gets configuration value with default fallback
* @param key Configuration key
* @param defaultValue Default value if key not found
* @return Configuration value or default
*/
public String getConfigValue(String key, String defaultValue);
/**
* Gets integer configuration value
* @param key Configuration key
* @param defaultValue Default integer value
* @return Integer configuration value
*/
public int getIntValue(String key, int defaultValue);
/**
* Gets boolean configuration value
* @param key Configuration key
* @param defaultValue Default boolean value
* @return Boolean configuration value
*/
public boolean getBooleanValue(String key, boolean defaultValue);
/**
* Gets long configuration value
* @param key Configuration key
* @param defaultValue Default long value
* @return Long configuration value
*/
public long getLongValue(String key, long defaultValue);
/**
* Sets configuration value dynamically
* @param key Configuration key
* @param value Configuration value
*/
public void setConfigValue(String key, String value);
/**
* Registers configuration change listener
* @param key Configuration key to monitor
* @param listener Change listener callback
*/
public void registerConfigListener(String key, ConfigChangeListener listener);
/**
* Unregisters configuration change listener
* @param key Configuration key
* @param listener Listener to remove
*/
public void unregisterConfigListener(String key, ConfigChangeListener listener);
/**
* Reloads configuration from source
* @throws ConfigException If reload fails
*/
public void reload() throws ConfigException;
/**
* Gets all configuration keys
* @return Set of all configuration keys
*/
public Set<String> getAllKeys();
}NamingControl
Service for entity naming rules and normalization.
public class NamingControl {
/**
* Normalizes service name according to naming rules
* @param serviceName Original service name
* @return Normalized service name
*/
public String formatServiceName(String serviceName);
/**
* Normalizes instance name according to naming rules
* @param instanceName Original instance name
* @return Normalized instance name
*/
public String formatInstanceName(String instanceName);
/**
* Normalizes endpoint name according to naming rules
* @param endpointName Original endpoint name
* @return Normalized endpoint name
*/
public String formatEndpointName(String endpointName);
/**
* Checks if service name needs normalization
* @param serviceName Service name to check
* @return True if normalization required
*/
public boolean needsNormalization(String serviceName);
/**
* Gets maximum allowed name length
* @return Maximum name length
*/
public int getMaxNameLength();
/**
* Gets naming rules configuration
* @return Naming rules settings
*/
public NamingRules getNamingRules();
/**
* Updates naming rules dynamically
* @param rules New naming rules
*/
public void updateNamingRules(NamingRules rules);
}DownSamplingConfigService
Service for managing downsampling configuration and time precision settings.
public class DownSamplingConfigService implements Service {
/**
* Gets enabled downsampling levels
* @return List of active downsampling levels
*/
public List<DownSampling> getDownSamplingLevels();
/**
* Checks if specific downsampling level is enabled
* @param downSampling Downsampling level to check
* @return True if enabled
*/
public boolean isDownSamplingEnabled(DownSampling downSampling);
/**
* Gets data retention period for downsampling level
* @param downSampling Downsampling level
* @return Retention period in days
*/
public int getDataRetentionDays(DownSampling downSampling);
/**
* Gets time bucket format for downsampling level
* @param downSampling Downsampling level
* @return Time bucket format pattern
*/
public String getTimeBucketFormat(DownSampling downSampling);
/**
* Enables downsampling level
* @param downSampling Downsampling level to enable
*/
public void enableDownSampling(DownSampling downSampling);
/**
* Disables downsampling level
* @param downSampling Downsampling level to disable
*/
public void disableDownSampling(DownSampling downSampling);
/**
* Updates retention configuration
* @param downSampling Downsampling level
* @param retentionDays New retention period in days
*/
public void updateRetention(DownSampling downSampling, int retentionDays);
/**
* Gets downsampling configuration
* @return Complete downsampling configuration
*/
public DownSamplingConfig getConfig();
}HierarchyDefinitionService
Service for managing service hierarchy configurations and relationships.
public class HierarchyDefinitionService implements Service {
/**
* Gets hierarchy definition for service
* @param serviceId Service identifier
* @return Hierarchy definition or null if not found
*/
public HierarchyDefinition getHierarchyDefinition(String serviceId);
/**
* Gets all hierarchy layers
* @return List of available hierarchy layers
*/
public List<String> getAllLayers();
/**
* Gets services in specific hierarchy layer
* @param layer Hierarchy layer name
* @return List of services in layer
*/
public List<String> getServicesInLayer(String layer);
/**
* Gets parent service in hierarchy
* @param serviceId Child service identifier
* @return Parent service identifier or null
*/
public String getParentService(String serviceId);
/**
* Gets child services in hierarchy
* @param serviceId Parent service identifier
* @return List of child service identifiers
*/
public List<String> getChildServices(String serviceId);
/**
* Sets service hierarchy relationship
* @param childServiceId Child service identifier
* @param parentServiceId Parent service identifier
* @param layer Hierarchy layer
*/
public void setHierarchyRelationship(String childServiceId, String parentServiceId, String layer);
/**
* Removes service from hierarchy
* @param serviceId Service identifier to remove
*/
public void removeFromHierarchy(String serviceId);
/**
* Updates hierarchy definition
* @param serviceId Service identifier
* @param definition New hierarchy definition
*/
public void updateHierarchyDefinition(String serviceId, HierarchyDefinition definition);
}Component Library Configuration
IComponentLibraryCatalogService
Interface for component library catalog management.
public interface IComponentLibraryCatalogService extends Service {
/**
* Gets component definition by ID
* @param componentId Component identifier
* @return Component definition or null if not found
*/
ComponentDefinition getComponentDefinition(int componentId);
/**
* Gets component definition by name
* @param componentName Component name
* @return Component definition or null if not found
*/
ComponentDefinition getComponentDefinition(String componentName);
/**
* Gets all registered components
* @return List of all component definitions
*/
List<ComponentDefinition> getAllComponents();
/**
* Gets components by category
* @param category Component category (database, cache, mq, etc.)
* @return List of components in category
*/
List<ComponentDefinition> getComponentsByCategory(String category);
/**
* Registers new component definition
* @param definition Component definition to register
* @return Generated component ID
*/
int registerComponent(ComponentDefinition definition);
/**
* Updates existing component definition
* @param componentId Component identifier
* @param definition Updated component definition
*/
void updateComponent(int componentId, ComponentDefinition definition);
/**
* Removes component from catalog
* @param componentId Component identifier to remove
*/
void removeComponent(int componentId);
/**
* Checks if component exists
* @param componentId Component identifier
* @return True if component exists
*/
boolean exists(int componentId);
}ComponentLibraryCatalogService
Default implementation of component library catalog service.
public class ComponentLibraryCatalogService implements IComponentLibraryCatalogService {
private Map<Integer, ComponentDefinition> componentsById;
private Map<String, ComponentDefinition> componentsByName;
@Override
public ComponentDefinition getComponentDefinition(int componentId);
@Override
public ComponentDefinition getComponentDefinition(String componentName);
@Override
public List<ComponentDefinition> getAllComponents();
@Override
public List<ComponentDefinition> getComponentsByCategory(String category);
@Override
public int registerComponent(ComponentDefinition definition);
@Override
public void updateComponent(int componentId, ComponentDefinition definition);
@Override
public void removeComponent(int componentId);
@Override
public boolean exists(int componentId);
/**
* Loads component definitions from configuration file
* @param configFile Configuration file path
* @throws ConfigException If loading fails
*/
public void loadFromConfig(String configFile) throws ConfigException;
/**
* Saves component definitions to configuration file
* @param configFile Configuration file path
* @throws ConfigException If saving fails
*/
public void saveToConfig(String configFile) throws ConfigException;
/**
* Gets next available component ID
* @return Next component ID
*/
protected int getNextComponentId();
}Configuration Data Types
NamingRules
Configuration for entity naming rules and constraints.
public class NamingRules {
private int maxServiceNameLength;
private int maxInstanceNameLength;
private int maxEndpointNameLength;
private boolean normalizeServiceName;
private boolean normalizeInstanceName;
private boolean normalizeEndpointName;
private String serviceNamePattern;
private String instanceNamePattern;
private String endpointNamePattern;
private List<String> forbiddenServiceNames;
private List<String> forbiddenInstanceNames;
/**
* Gets maximum service name length
* @return Maximum length
*/
public int getMaxServiceNameLength();
/**
* Sets maximum service name length
* @param maxServiceNameLength Maximum length
*/
public void setMaxServiceNameLength(int maxServiceNameLength);
/**
* Checks if service name normalization is enabled
* @return True if normalization enabled
*/
public boolean isNormalizeServiceName();
/**
* Gets service name validation pattern
* @return Regex pattern for service names
*/
public String getServiceNamePattern();
/**
* Gets forbidden service names
* @return List of forbidden names
*/
public List<String> getForbiddenServiceNames();
/**
* Validates service name against rules
* @param serviceName Service name to validate
* @return True if valid
*/
public boolean isValidServiceName(String serviceName);
/**
* Validates instance name against rules
* @param instanceName Instance name to validate
* @return True if valid
*/
public boolean isValidInstanceName(String instanceName);
/**
* Validates endpoint name against rules
* @param endpointName Endpoint name to validate
* @return True if valid
*/
public boolean isValidEndpointName(String endpointName);
}DownSamplingConfig
Configuration for downsampling levels and retention policies.
public class DownSamplingConfig {
private Map<DownSampling, Boolean> enabledLevels;
private Map<DownSampling, Integer> retentionDays;
private Map<DownSampling, String> timeBucketFormats;
/**
* Checks if downsampling level is enabled
* @param level Downsampling level
* @return True if enabled
*/
public boolean isEnabled(DownSampling level);
/**
* Enables or disables downsampling level
* @param level Downsampling level
* @param enabled True to enable, false to disable
*/
public void setEnabled(DownSampling level, boolean enabled);
/**
* Gets retention period for downsampling level
* @param level Downsampling level
* @return Retention period in days
*/
public int getRetentionDays(DownSampling level);
/**
* Sets retention period for downsampling level
* @param level Downsampling level
* @param days Retention period in days
*/
public void setRetentionDays(DownSampling level, int days);
/**
* Gets time bucket format for level
* @param level Downsampling level
* @return Time bucket format pattern
*/
public String getTimeBucketFormat(DownSampling level);
/**
* Gets all enabled downsampling levels
* @return List of enabled levels
*/
public List<DownSampling> getEnabledLevels();
}ComponentDefinition
Definition of a component in the component library catalog.
public class ComponentDefinition {
private int id;
private String name;
private String category;
private String description;
private String version;
private Map<String, String> properties;
private List<String> supportedLanguages;
private boolean deprecated;
/**
* Gets component ID
* @return Component identifier
*/
public int getId();
/**
* Sets component ID
* @param id Component identifier
*/
public void setId(int id);
/**
* Gets component name
* @return Component name
*/
public String getName();
/**
* Sets component name
* @param name Component name
*/
public void setName(String name);
/**
* Gets component category
* @return Component category (database, cache, mq, http, etc.)
*/
public String getCategory();
/**
* Sets component category
* @param category Component category
*/
public void setCategory(String category);
/**
* Gets component description
* @return Component description
*/
public String getDescription();
/**
* Gets component version
* @return Component version
*/
public String getVersion();
/**
* Gets component properties
* @return Map of component properties
*/
public Map<String, String> getProperties();
/**
* Gets supported programming languages
* @return List of supported languages
*/
public List<String> getSupportedLanguages();
/**
* Checks if component is deprecated
* @return True if deprecated
*/
public boolean isDeprecated();
/**
* Sets component as deprecated
* @param deprecated True to mark as deprecated
*/
public void setDeprecated(boolean deprecated);
}HierarchyDefinition
Definition of service hierarchy relationships and metadata.
public class HierarchyDefinition {
private String serviceId;
private String layer;
private String parentServiceId;
private List<String> childServiceIds;
private Map<String, String> metadata;
private int level;
/**
* Gets service identifier
* @return Service ID
*/
public String getServiceId();
/**
* Sets service identifier
* @param serviceId Service ID
*/
public void setServiceId(String serviceId);
/**
* Gets hierarchy layer
* @return Layer name (auto, k8s, mesh, etc.)
*/
public String getLayer();
/**
* Sets hierarchy layer
* @param layer Layer name
*/
public void setLayer(String layer);
/**
* Gets parent service identifier
* @return Parent service ID or null if root
*/
public String getParentServiceId();
/**
* Sets parent service identifier
* @param parentServiceId Parent service ID
*/
public void setParentServiceId(String parentServiceId);
/**
* Gets child service identifiers
* @return List of child service IDs
*/
public List<String> getChildServiceIds();
/**
* Adds child service to hierarchy
* @param childServiceId Child service ID to add
*/
public void addChildService(String childServiceId);
/**
* Removes child service from hierarchy
* @param childServiceId Child service ID to remove
*/
public void removeChildService(String childServiceId);
/**
* Gets hierarchy metadata
* @return Map of metadata properties
*/
public Map<String, String> getMetadata();
/**
* Gets hierarchy level (depth from root)
* @return Hierarchy level
*/
public int getLevel();
/**
* Sets hierarchy level
* @param level Hierarchy level
*/
public void setLevel(int level);
}Configuration Listeners
ConfigChangeListener
Interface for receiving configuration change notifications.
public interface ConfigChangeListener {
/**
* Called when configuration value changes
* @param key Configuration key that changed
* @param oldValue Previous configuration value
* @param newValue New configuration value
*/
void onConfigChanged(String key, String oldValue, String newValue);
/**
* Called when configuration is added
* @param key Configuration key that was added
* @param value New configuration value
*/
void onConfigAdded(String key, String value);
/**
* Called when configuration is removed
* @param key Configuration key that was removed
* @param oldValue Previous configuration value
*/
void onConfigRemoved(String key, String oldValue);
}ComponentCatalogListener
Interface for component catalog change notifications.
public interface ComponentCatalogListener {
/**
* Called when component is added to catalog
* @param definition Component definition that was added
*/
void onComponentAdded(ComponentDefinition definition);
/**
* Called when component is updated in catalog
* @param oldDefinition Previous component definition
* @param newDefinition Updated component definition
*/
void onComponentUpdated(ComponentDefinition oldDefinition, ComponentDefinition newDefinition);
/**
* Called when component is removed from catalog
* @param definition Component definition that was removed
*/
void onComponentRemoved(ComponentDefinition definition);
}Configuration Exceptions
ConfigException
Base exception for configuration-related errors.
public class ConfigException extends Exception {
/**
* Creates configuration exception with message
* @param message Error message
*/
public ConfigException(String message);
/**
* Creates configuration exception with message and cause
* @param message Error message
* @param cause Underlying cause
*/
public ConfigException(String message, Throwable cause);
}NamingViolationException
Exception for entity naming rule violations.
public class NamingViolationException extends ConfigException {
private String entityName;
private String violationType;
/**
* Creates naming violation exception
* @param entityName Entity name that violates rules
* @param violationType Type of violation
* @param message Error message
*/
public NamingViolationException(String entityName, String violationType, String message);
/**
* Gets entity name that caused violation
* @return Entity name
*/
public String getEntityName();
/**
* Gets violation type
* @return Violation type (length, pattern, forbidden, etc.)
*/
public String getViolationType();
}Usage Examples
Basic Configuration Management
// Get configuration service
ConfigService configService = moduleDefineHolder.find(CoreModule.NAME)
.provider().getService(ConfigService.class);
// Read configuration values
String storageType = configService.getConfigValue("storage.type", "elasticsearch");
int maxConnections = configService.getIntValue("storage.max-connections", 100);
boolean enableDebug = configService.getBooleanValue("debug.enabled", false);
// Set configuration values dynamically
configService.setConfigValue("analysis.batch-size", "1000");
// Listen for configuration changes
configService.registerConfigListener("storage.type", new ConfigChangeListener() {
@Override
public void onConfigChanged(String key, String oldValue, String newValue) {
System.out.println("Storage type changed from " + oldValue + " to " + newValue);
// Reinitialize storage connection
reinitializeStorage(newValue);
}
@Override
public void onConfigAdded(String key, String value) {
System.out.println("New configuration added: " + key + " = " + value);
}
@Override
public void onConfigRemoved(String key, String oldValue) {
System.out.println("Configuration removed: " + key);
}
});Entity Naming Control
// Get naming control service
NamingControl namingControl = moduleDefineHolder.find(CoreModule.NAME)
.provider().getService(NamingControl.class);
// Configure naming rules
NamingRules rules = new NamingRules();
rules.setMaxServiceNameLength(200);
rules.setNormalizeServiceName(true);
rules.setServiceNamePattern("^[a-zA-Z0-9_-]+$");
rules.setForbiddenServiceNames(Arrays.asList("system", "internal", "admin"));
namingControl.updateNamingRules(rules);
// Format entity names
String originalServiceName = "My Service With Spaces!";
String normalizedServiceName = namingControl.formatServiceName(originalServiceName);
System.out.println("Normalized: " + normalizedServiceName); // "My_Service_With_Spaces"
// Validate names
if (namingControl.needsNormalization("problematic-service-name!")) {
String normalized = namingControl.formatServiceName("problematic-service-name!");
System.out.println("Service name normalized to: " + normalized);
}Downsampling Configuration
// Get downsampling configuration service
DownSamplingConfigService downsamplingService = moduleDefineHolder.find(CoreModule.NAME)
.provider().getService(DownSamplingConfigService.class);
// Check enabled levels
List<DownSampling> enabledLevels = downsamplingService.getDownSamplingLevels();
System.out.println("Enabled downsampling levels: " + enabledLevels);
// Configure retention policies
downsamplingService.updateRetention(DownSampling.Minute, 3); // 3 days
downsamplingService.updateRetention(DownSampling.Hour, 30); // 30 days
downsamplingService.updateRetention(DownSampling.Day, 365); // 1 year
// Enable/disable levels
downsamplingService.enableDownSampling(DownSampling.Hour);
downsamplingService.disableDownSampling(DownSampling.Day);
// Check specific level
if (downsamplingService.isDownSamplingEnabled(DownSampling.Minute)) {
int retentionDays = downsamplingService.getDataRetentionDays(DownSampling.Minute);
System.out.println("Minute data retained for " + retentionDays + " days");
}Component Library Management
// Get component library service
IComponentLibraryCatalogService componentService = moduleDefineHolder.find(CoreModule.NAME)
.provider().getService(IComponentLibraryCatalogService.class);
// Register new component
ComponentDefinition mysqlComponent = new ComponentDefinition();
mysqlComponent.setName("MySQL");
mysqlComponent.setCategory("database");
mysqlComponent.setDescription("MySQL relational database");
mysqlComponent.setVersion("8.0");
mysqlComponent.setSupportedLanguages(Arrays.asList("Java", "Python", "PHP", "Node.js"));
Map<String, String> properties = new HashMap<>();
properties.put("port", "3306");
properties.put("protocol", "mysql");
mysqlComponent.setProperties(properties);
int componentId = componentService.registerComponent(mysqlComponent);
System.out.println("Registered MySQL component with ID: " + componentId);
// Query components
List<ComponentDefinition> databaseComponents =
componentService.getComponentsByCategory("database");
for (ComponentDefinition component : databaseComponents) {
System.out.println("Database component: " + component.getName() +
" v" + component.getVersion());
}
// Update component
ComponentDefinition existingComponent = componentService.getComponentDefinition("MySQL");
if (existingComponent != null) {
existingComponent.setVersion("8.0.30");
componentService.updateComponent(existingComponent.getId(), existingComponent);
}Service Hierarchy Management
// Get hierarchy service
HierarchyDefinitionService hierarchyService = moduleDefineHolder.find(CoreModule.NAME)
.provider().getService(HierarchyDefinitionService.class);
// Define service hierarchy
hierarchyService.setHierarchyRelationship(
"user-service", // child
"web-gateway", // parent
"k8s" // layer
);
hierarchyService.setHierarchyRelationship(
"order-service", // child
"web-gateway", // parent
"k8s" // layer
);
// Query hierarchy
String parentService = hierarchyService.getParentService("user-service");
System.out.println("Parent of user-service: " + parentService);
List<String> childServices = hierarchyService.getChildServices("web-gateway");
System.out.println("Children of web-gateway: " + childServices);
// Get hierarchy definition
HierarchyDefinition userServiceHierarchy =
hierarchyService.getHierarchyDefinition("user-service");
if (userServiceHierarchy != null) {
System.out.println("Service: " + userServiceHierarchy.getServiceId());
System.out.println("Layer: " + userServiceHierarchy.getLayer());
System.out.println("Level: " + userServiceHierarchy.getLevel());
System.out.println("Parent: " + userServiceHierarchy.getParentServiceId());
}
// List all layers
List<String> allLayers = hierarchyService.getAllLayers();
System.out.println("Available hierarchy layers: " + allLayers);
// Get services in specific layer
List<String> k8sServices = hierarchyService.getServicesInLayer("k8s");
System.out.println("Services in k8s layer: " + k8sServices);Core Configuration Types
/**
* Configuration module definition
*/
public class ConfigModule extends ModuleDefine {
public static final String NAME = "configuration";
@Override
public String name();
@Override
public Class[] services();
}
/**
* Configuration source enumeration
*/
public enum ConfigSource {
FILE, ENVIRONMENT, SYSTEM_PROPERTY, DATABASE, REMOTE
}
/**
* Configuration change event
*/
public class ConfigChangeEvent {
private String key;
private String oldValue;
private String newValue;
private ConfigSource source;
private long timestamp;
public String getKey();
public String getOldValue();
public String getNewValue();
public ConfigSource getSource();
public long getTimestamp();
}Install with Tessl CLI
npx tessl i tessl/maven-org-apache-skywalking--server-core