All Products
Search
Document Center

Microservices Engine:Executor management

Last Updated:Dec 03, 2025

After you create an application, you must connect an executor to run tasks.

Connect a standard application to an executor

Automatic registration

Automatic registration requires your service to use the XXL-JOB software development kit (SDK). After you configure the connection, the application automatically registers when it starts.

1. View the connection configuration

  1. Log on to the MSE XXL-JOB console.

  2. In the upper-left corner of the page, select the target Region.

  3. Click the target instance ID. In the navigation pane on the left, choose Application Management.

  4. In the Number of actuators column for the target application, click the Integrate button.

  5. Set Connection Type to Automatic Registration and modify the configuration.

2. Import the SDK to connect the executor

Java SDK

  1. In the pom.xml file, add the "xxl-job-core" Maven dependency.

  2. Initialize the executor.

    @Configuration
    public class XxlJobConfig {
        private Logger logger = LoggerFactory.getLogger(XxlJobConfig.class);
    
        @Value("${xxl.job.admin.addresses}")
        private String adminAddresses;
    
        @Value("${xxl.job.accessToken}")
        private String accessToken;
    
        @Value("${xxl.job.executor.appname}")
        private String appname;
    
        @Value("${xxl.job.executor.address}")
        private String address;
    
        @Value("${xxl.job.executor.ip}")
        private String ip;
    
        @Value("${xxl.job.executor.port}")
        private int port;
    
        @Value("${xxl.job.executor.logpath}")
        private String logPath;
    
        @Value("${xxl.job.executor.logretentiondays}")
        private int logRetentionDays;
    
        @Bean
        public XxlJobSpringExecutor xxlJobExecutor() {
            logger.info(">>>>>>>>>>> xxl-job config init.");
            XxlJobSpringExecutor xxlJobSpringExecutor = new XxlJobSpringExecutor();
            xxlJobSpringExecutor.setAdminAddresses(adminAddresses);
            xxlJobSpringExecutor.setAppname(appname);
            xxlJobSpringExecutor.setAddress(address);
            xxlJobSpringExecutor.setIp(ip);
            xxlJobSpringExecutor.setPort(port);
            xxlJobSpringExecutor.setAccessToken(accessToken);
            xxlJobSpringExecutor.setLogPath(logPath);
            xxlJobSpringExecutor.setLogRetentionDays(logRetentionDays);
    
            return xxlJobSpringExecutor;
        }
    
    }

Go SDK

  1. Run the following command to pull the Go version of the XXL-JOB SDK using the latest tag.

    go get github.com/xxl-job/xxl-job-executor-go@{latest_tag}
  2. Write the business code.

    package main
    
    import (
        "context"
        "fmt"
        xxl "github.com/xxl-job/xxl-job-executor-go"
        "github.com/xxl-job/xxl-job-executor-go/example/task"
        "log"
    )
    
    func main() {
        exec := xxl.NewExecutor(
            xxl.ServerAddr("xxxxxx"),       // Request address. Obtain it from the connection configuration in the Application Management section of the console.
            xxl.AccessToken("xxxxxxx"),     // Request token. Obtain it from the connection configuration in the Application Management section of the console.
            xxl.ExecutorPort("9999"),       // Default is 9999. This parameter is optional.
            xxl.RegistryKey("golang-jobs"), // Executor name.
            xxl.SetLogger(&logger{}),       // Custom logger.
        )
        exec.Init()
        exec.Use(customMiddleware)
        // Set the handler for viewing logs.
        exec.LogHandler(customLogHandle)
        // Register the task handler.
        exec.RegTask("task.test", task.Test)
        exec.RegTask("task.test2", task.Test2)
        exec.RegTask("task.panic", task.Panic)
        log.Fatal(exec.Run())
    }
    
    // Custom log handler.
    func customLogHandle(req *xxl.LogReq) *xxl.LogRes {
        return &xxl.LogRes{Code: xxl.SuccessCode, Msg: "", Content: xxl.LogResContent{
            FromLineNum: req.FromLineNum,
            ToLineNum:   2,
            LogContent:  "This is a custom log handler",
            IsEnd:       true,
        }}
    }
    
    // Implementation of the xxl.Logger interface.
    type logger struct{}
    
    func (l *logger) Info(format string, a ...interface{}) {
        fmt.Println(fmt.Sprintf("Custom log - "+format, a...))
    }
    
    func (l *logger) Error(format string, a ...interface{}) {
        log.Println(fmt.Sprintf("Custom log - "+format, a...))
    }
    
    // Custom middleware.
    func customMiddleware(tf xxl.TaskFunc) xxl.TaskFunc {
        return func(cxt context.Context, param *xxl.RunReq) string {
            log.Println("I am a middleware start")
            res := tf(cxt, param)
            log.Println("I am a middleware end")
            return res
        }
    }
    

Python SDK

  1. Pull the dependencies.

    pip install pyxxl
    
    # To write logs to Redis
    pip install "pyxxl[redis]"
    
    # To load configurations from a .env file
    pip install "pyxxl[dotenv]"
    
    # Install all features
    pip install "pyxxl[all]"
  2. Write the business code.

    import asyncio
    import time
    
    from pyxxl import ExecutorConfig, PyxxlRunner
    from pyxxl.ctx import g
    
    config = ExecutorConfig(
        xxl_admin_baseurl="http://xxljob-1b3fd8196eb.schedulerx.mse.aliyuncs.com/api/",
        executor_app_name="xueren-test",
        access_token="default_token",
    #    executor_listen_host="0.0.0.0",  # If xxl-admin can directly connect to the executor's IP address, you do not need to specify executor_listen_host.
    )
    
    app = PyxxlRunner(config)
    
    
    @app.register(name="demoJobHandler")
    async def test_task():
        # you can get task params with "g"
        g.logger.info("get executor params: %s" % g.xxl_run_data.executorParams)
        for i in range(10):
            g.logger.warning("test logger %s" % i)
        await asyncio.sleep(5)
        return "Success..."
    
    @app.register(name="sync_func")
    def test_task4():
        # To view execution logs in xxl-admin, you must use g.logger for log printing. By default, only logs of the INFO level and higher are printed.
        n = 1
        g.logger.info("Job %s get executor params: %s" % (g.xxl_run_data.jobId, g.xxl_run_data.executorParams))
        # If a sync task contains a loop, you must check g.cancel_event in each iteration to support the cancel operation.
        while n <= 10 and not g.cancel_event.is_set():
            # If you do not need to view logs from xxl-admin, you can use your own logger.
            g.logger.info(
                "log to {} logger test_task4.{},params:{}".format(
                    g.xxl_run_data.jobId,
                    n,
                    g.xxl_run_data.executorParams,
                )
            )
            time.sleep(2)
            n += 1
        return "Success3"
    
    
    if __name__ == "__main__":
        app.run_executor()

Manual entry

Manual entry lets you maintain the address information of executors. The address format is http://192.168.0.1:9999/.

  1. Log on to the MSE XXL-JOB console.

  2. In the upper-left corner of the page, select the target Region.

  3. Click the target instance ID. In the navigation pane on the left, choose Application Management.

  4. In the Number of actuators column for the target application, click the Integrate button.

  5. Set Connection Type to Manual Entry and enter the Actuator Address.

Connect an HTTP application to an executor

An SDK is not required. Backend nodes are automatically discovered by configuring a domain name or a Kubernetes service. The HTTP protocol is used for scheduling.

Connect to a Kubernetes service

If your HTTP application is deployed in Container Service for Kubernetes (ACK), use the "Connect to a Kubernetes service" method.

  1. Optional: Deploy the application in ACK. The following cluster types are supported:

    • ACK managed cluster that uses the Terway network plug-in

    • ACK Serverless cluster

    • ACS cluster

  2. Optional: Create a service for the application in ACK. The following service types are supported:

    • ClusterIP

    • LoadBalancer

  3. Log on to the MSE XXL-JOB console.

  4. In the upper-left corner of the page, select the target Region.

  5. Click the target instance ID. In the navigation pane on the left, choose Application Management.

  6. In the Number Of Executors column for the target application, click the Integrate button.

  7. On the IntegrateActuator page, set Connection Type to Integrate K8s Service, configure the parameters, and then click OK.

After the connection is established, the number of executors changes. You can click the number to view the list of backend pods.

Manually enter a domain name

If your application is not deployed in ACK, such as on an ECS instance, you can schedule HTTP tasks using an internal domain name.

  1. Optional: Create a gateway for the HTTP application, such as a Network Load Balancer (NLB). An internal domain name is automatically generated.

  2. In the upper-left corner of the page, select the target Region.

  3. Click the target instance ID. In the navigation pane on the left, choose Application Management.

  4. In the Number Of Executors column for the target application, click the Integrate button.

  5. On the IntegrateActuator page,set Connection Type to Enter a domain name and configure the internal domain name.