DOCSEARCHbyAlgolia
Submit Docs

SOFARegistry Documentation

repository·master·Indexed 20 days ago

https://github.com/sofastack/sofa-registry

A high-performance, low-latency micro-service registry system designed for massive scale and high availability. Powered by Ant Group, it utilizes an AP architecture and the SOFABolt communication framework to provide real-time service discovery notifications. The system consists of meta, data, and session roles, featuring a multi-tier layered architecture for horizontal scaling and comprehensive Admin APIs for metadata, registry data, and session monitoring.

Tokens
9.5K
Snippets
28
Records
37
Agent score
68%

What's inside SOFARegistry

  1. Overview of SOFARegistry

    master

    SOFARegistry is a production-level, low-latency, and high-availability registry system designed for micro-services registration. It is powered by Ant Group and utilizes an AP (Availability/Partition-tolerance) architecture to ensure service availability even during network partitions.

    Key features include:

    • Service Management: Supports service publishing and subscription.
    • Real-time Notifications: Provides millisecond-level notifications for service registration and deregistration using the SOFABolt communication framework.
    • Scalability: Employs a multi-tier, layered architecture to handle massive connections and large-scale datasets through horizontal scaling.
    • High Availability: Ensures data availability via facility replication capabilities.
    • Governance: Offers enhanced service governance API endpoints.

  2. How Session auto-batching works in SOFARegistry

    master

    The Session server uses an auto-batching mechanism to improve push efficiency by balancing latency and throughput.

    Core Mechanism:

    • Reduces push frequency: Batches multiple push requests to reduce network round-trips and improve throughput.
    • Optimizes resources: Reduces CPU and network overhead by processing multiple tasks in a single batch.
    • Latency vs. Throughput Trade-off:
      • Shorter batching duration: Lower push latency, but higher system overhead (more frequent operations).
      • Longer batching duration: Higher push latency, but lower system overhead (fewer operations).

    Key Components:

    • PushEfficiencyImproveConfig: Main configuration for push efficiency.
    • AutoPushEfficiencyConfig: Configuration for auto-tuning batching duration.
    • AutoPushEfficiencyRegulator: Component that automatically adjusts duration based on system load and push frequency.

  3. System Requirements for SOFARegistry

    master

    Depending on whether you are compiling the project or running the server, the following requirements apply:

    Compilation Requirements

    • JDK: 8 or higher
    • Maven: 3.2.5 or higher

    Runtime Requirements

    • Client/General Runtime: JDK 6 or higher
    • Server-side Deployment: JDK 8 or higher
    IMPORTANT

    Recommended Environment: JDK 8. JDK 16 has not been tested and may encounter compatibility issues.

  4. Configure Session auto-batching parameters

    master

    You can configure batching behavior in the application.properties file of the Session server. Parameters are grouped into Basic Batching, Auto-Tuning, and Traffic Control.

    # Basic batching parameters
session.server.data.change.debouncing.millis=1000
session.server.data.change.max.debouncing.millis=3000
session.server.push.data.task.debouncing.millis=500

# Auto-tuning parameters
session.server.push.efficiency.auto.enable=false
session.server.push.efficiency.debouncing.time.enable=false
session.server.push.efficiency.debouncing.time.max=1000
session.server.push.efficiency.debouncing.time.min=100
session.server.push.efficiency.debouncing.time.step=100
session.server.push.efficiency.max.debouncing.time.enable=false
session.server.push.efficiency.max.debouncing.time.max=3000
session.server.push.efficiency.max.debouncing.time.min=1000
session.server.push.efficiency.max.debouncing.time.step=200

  5. Build and Run Requirements for SOFARegistry

    master

    Before compiling or running SOFARegistry, ensure your environment meets the following requirements:

    Compilation Requirements

    • JDK: 8 or higher
    • Maven: 3.2.5 or higher

    Runtime Requirements

    • Client/General Runtime: JDK 6 or higher
    • Server Runtime: JDK 8 or higher
    IMPORTANT

    JDK 8 is highly recommended. JDK 16 has not been tested and may encounter compatibility issues.

  6. Run SOFARegistry using Docker Compose

    master

    You can deploy and manage SOFARegistry using Docker Compose. Use the provided sofa-registry-in-docker-compose.yml configuration file to start or stop the service stack.

    # Start the service in detached mode
docker-compose -f sofa-registry-in-docker-compose.yml up -d

# Stop and remove the containers
docker-compose -f sofa-registry-in-docker-compose.yml down

  7. Tune Session server for High Throughput or Low Latency

    master

    Depending on your workload, use the following configuration strategies:

    High Throughput Scenario

    Goal: Handle high push frequency and large data volumes.

    1. Increase batching duration: Set a longer pushTaskDebouncingMillis (e.g., 1000ms).
    2. Enable auto-tuning: Set enableAutoPushEfficiency and enableDebouncingTime to true.
    3. Adjust thresholds: Increase pushCountThreshold for high-volume systems.

    Low Latency Scenario

    Goal: Minimize push delay.

    1. Decrease batching duration: Set a shorter pushTaskDebouncingMillis (e.g., 100ms).
    2. Disable auto-tuning: Keep auto-tuning disabled to maintain manual control over latency.
    3. Optimize intervals: Ensure changeTaskWaitingMillis and pushTaskWaitingMillis are set to low, reasonable values.

  10. Start the SOFARegistry base server

    master

    The start_base.sh script is used to launch the SOFARegistry base server component. It requires the REGISTRY_APP_NAME environment variable to identify which JAR file to execute and to configure logging paths.

    Required Environment Variables

    • REGISTRY_APP_NAME: The name of the registry application (used to locate ${RELEASE_DIR}/registry-${REGISTRY_APP_NAME}.jar and configure logging).

    Optional Configuration via Environment Variables

    • SPRING_CONFIG_LOCATION: Path to additional Spring configuration files. Defaults to ${RELEASE_DIR}/conf/ if not provided.
    • SPRING_PROFILES_ACTIVE: Sets the active Spring profiles (e.g., dev, prod).
    • JAVA_OPTS: Additional JVM arguments. Note that the script appends several default memory and GC settings to this variable.
    • SPRINGBOOT_OPTS: Additional Spring Boot arguments.
    • DEBUG_PORT: If set, enables JDWP remote debugging and suspends the process until a debugger is attached.

    Default JVM Behavior

    • Memory: Uses a default memory allocation logic based on an 8GB baseline (unless overridden via JAVA_OPTS).
    • Logging: Configures Log4j2 using files located in ${RELEASE_DIR}/log-conf/${REGISTRY_APP_NAME}/log4j2.xml.
    • GC Logging: Writes GC logs to ${HOME}/logs/registry-${REGISTRY_APP_NAME}-gc.log.
    • Error Handling: Generates heap dumps and error logs in ${HOME}/logs upon OutOfMemoryErrors.
    # Example usage
export REGISTRY_APP_NAME=my-registry
export SPRING_PROFILES_ACTIVE=prod
export DEBUG_PORT=5005
./start_base.sh

  11. Troubleshoot Session push performance

    master

    Monitor these key metrics to diagnose issues:

    • Push latency: Average time from data change to push completion.
    • Push throughput: Number of push operations per second.
    • System load: CPU and memory usage.
    • Push task queue length: Number of pending push tasks.

    Common Issues:

    • High push latency: Batching duration might be too high. Try reducing pushTaskDebouncingMillis.
    • Low throughput: Batching duration might be too low. Try increasing pushTaskDebouncingMillis or enabling auto-tuning.
    • System overload: Enable traffic control using enableTrafficOperateLimitSwitch and adjust loadThreshold.
    • Push task starvation: Check if changeDebouncingMaxMillis is set appropriately to ensure tasks are eventually processed.

  12. Discover and Monitor Session Servers via Session Open API

    master

    The Session Open API is used for server discovery, connection monitoring, and health checks. It allows clients to find available session servers within a specific zone and provides insights into connection counts and data slot assignments.

    # Get session server list (JSON format)
curl -X GET "http://localhost:9603/api/servers/query.json?zone=ZONE1"

# Get session server list (Text format)
curl -X GET "http://localhost:9603/api/servers/query?zone=ZONE1"

# Get session server list with weights
curl -X GET "http://localhost:9603/api/servers/queryWithWeight?zone=ZONE1"

# Get current session connection count
curl -X GET http://localhost:9603/api/servers/connectionNum

# Check if server is alive
curl -X GET http://localhost:9603/api/servers/alive

# Get server list for the current data center
curl -X GET http://localhost:9603/api/servers/dataCenter

# Get slot information for specific data
curl -X GET "http://localhost:9603/api/servers/slot?dataInfoId=testDataId#@#DEFAULT_INSTANCE_ID#@#DEFAULT_GROUP"