ElasticJob-Lite使用手册——事件追踪与操作API-京东云开发者社区

# 事件追踪
ElasticJob 提供了事件追踪功能，可通过事件订阅的方式处理调度过程的重要事件，用于查询、统计和监控。 目前提供了基于关系型数据库的事件订阅方式记录事件，开发者也可以通过 SPI 自行扩展。
## 使用 Java API

ElasticJob-Lite 在配置中提供了 TracingConfiguration，目前支持数据库方式配置。
开发者也可以通过 SPI 自行扩展。

```java
    // 初始化数据源
    DataSource dataSource = ...;
    // 定义日志数据库事件溯源配置
    TracingConfiguration tracingConfig = new TracingConfiguration<>("RDB", dataSource);
    // 初始化注册中心
    CoordinatorRegistryCenter regCenter = ...;
    // 初始化作业配置
    JobConfiguration jobConfig = ...;
    jobConfig.getExtraConfigurations().add(tracingConfig);
    new ScheduleJobBootstrap(regCenter, jobConfig).schedule();
```
## 使用 Spring Boot Starter

ElasticJob-Lite 的 Spring Boot Starter 集成了 TracingConfiguration 自动配置，
开发者只需注册一个 DataSource 到 Spring 容器中并在配置文件指定事件追踪数据源类型，
Starter 就会自动创建一个 TracingConfiguration 实例并注册到 Spring 容器中。

### 引入 Maven 依赖

引入 spring-boot-starter-jdbc 注册数据源或自行创建一个 DataSource Bean。

```xml
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jdbc</artifactId>
    <version>${springboot.version}</version>
</dependency>
```

### 配置

```yaml
spring:
  datasource:
    url: jdbc:h2:mem:job_event_storage
    driver-class-name: org.h2.Driver
    username: sa
    password:

elasticjob:
  tracing:
    type: RDB
```

### 作业启动

指定事件追踪数据源类型为 RDB，TracingConfiguration 会自动注册到容器中，如果与 elasticjob-lite-spring-boot-starter 配合使用，
开发者无需进行其他额外的操作，作业启动器会自动使用创建的 TracingConfiguration。
## 使用 Spring 命名空间

### 引入 Maven 依赖

引入 elasticjob-lite-spring

```xml
<dependency>
    <groupId>org.apache.shardingsphere.elasticjob</groupId>
    <artifactId>elasticjob-lite-spring-namespace</artifactId>
    <version>${elasticjob.latest.version}</version>
</dependency>
```

### 配置

```xml
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:elasticjob="http://shardingsphere.apache.org/schema/elasticjob"
    xsi:schemaLocation="http://www.springframework.org/schema/beans 
                        http://www.springframework.org/schema/beans/spring-beans.xsd 
                        http://shardingsphere.apache.org/schema/elasticjob
                        http://shardingsphere.apache.org/schema/elasticjob/elasticjob.xsd
                        ">
    
    <elasticjob:zookeeper id="regCenter" server-lists="yourhost:2181" namespace="my-job" base-sleep-time-milliseconds="1000" max-sleep-time-milliseconds="3000" max-retries="3" />
    
    
    <bean id="myJob" class="xxx.MyJob" />
    
    
    <bean id="tracingDataSource" class="org.apache.commons.dbcp2.BasicDataSource" destroy-method="close">
        <property name="driverClassName" value="${driver.class.name}" />
        <property name="url" value="${url}" />
        <property name="username" value="${username}" />
        <property name="password" value="${password}" />
    </bean>
    
    <elasticjob:rdb-tracing id="elasticJobTrace" data-source-ref="elasticJobTracingDataSource" />
    
    
    <elasticjob:job id="${myJob.id}" job-ref="myJob" registry-center-ref="regCenter" tracing-ref="elasticJobTrace" sharding-total-count="3" cron="0/1 * * * * ?" />
</beans>
```

### 作业启动

将配置 Spring 命名空间的 xml 通过 Spring 启动，作业将自动加载。
## 表结构说明
事件追踪的 event_trace_rdb_url 属性对应库自动创建 JOB_EXECUTION_LOG 和 JOB_STATUS_TRACE_LOG 两张表以及若干索引。

### JOB_EXECUTION_LOG 字段含义

| 字段名称          | 字段类型       | 是否必填  | 描述                                                   |
| ---------------- |:------------- |:-------- |:----------------------------------------------------- |
| id               | VARCHAR(40)   | 是       | 主键                                                   |
| job_name         | VARCHAR(100)  | 是       | 作业名称                                               |
| task_id          | VARCHAR(1000) | 是       | 任务名称,每次作业运行生成新任务                           |
| hostname         | VARCHAR(255)  | 是       | 主机名称                                               |
| ip               | VARCHAR(50)   | 是       | 主机IP                                                |
| sharding_item    | INT           | 是       | 分片项                                                |
| execution_source | VARCHAR(20)   | 是       | 作业执行来源。可选值为NORMAL_TRIGGER, MISFIRE, FAILOVER |
| failure_cause    | VARCHAR(2000) | 否       | 执行失败原因                                           |
| is_success       | BIT           | 是       | 是否执行成功                                           |
| start_time       | TIMESTAMP     | 是       | 作业开始执行时间                                        |
| complete_time    | TIMESTAMP     | 否       | 作业结束执行时间                                        |

JOB_EXECUTION_LOG 记录每次作业的执行历史。
分为两个步骤：

1. 作业开始执行时向数据库插入数据，除 failure_cause 和 complete_time 外的其他字段均不为空。
1. 作业完成执行时向数据库更新数据，更新 is_success, complete_time 和 failure_cause(如果作业执行失败)。

### JOB_STATUS_TRACE_LOG 字段含义

| 字段名称          | 字段类型       | 是否必填  | 描述                                                                                                          |
| ---------------- |:--------------|:---------|:------------------------------------------------------------------------------------------------------------- |
| id               | VARCHAR(40)   | 是       | 主键                                                                                                           |
| job_name         | VARCHAR(100)  | 是       | 作业名称                                                                                                       |
| original_task_id | VARCHAR(1000) | 是       | 原任务名称                                                                                                     |
| task_id          | VARCHAR(1000) | 是       | 任务名称                                                                                                       |
| slave_id         | VARCHAR(1000) | 是       | 执行作业服务器的名称，Lite版本为服务器的IP地址，Cloud版本为Mesos执行机主键                                           |
| source           | VARCHAR(50)   | 是       | 任务执行源，可选值为CLOUD_SCHEDULER, CLOUD_EXECUTOR, LITE_EXECUTOR                                               |
| execution_type   | VARCHAR(20)   | 是       | 任务执行类型，可选值为NORMAL_TRIGGER, MISFIRE, FAILOVER                                                          |
| sharding_item    | VARCHAR(255)  | 是       | 分片项集合，多个分片项以逗号分隔                                                                                  |
| state            | VARCHAR(20)   | 是       | 任务执行状态，可选值为TASK_STAGING, TASK_RUNNING, TASK_FINISHED, TASK_KILLED, TASK_LOST, TASK_FAILED, TASK_ERROR |
| message          | VARCHAR(2000) | 是       | 相关信息                                                                                                       |
| creation_time    | TIMESTAMP     | 是       | 记录创建时间                                                                                                    |

JOB_STATUS_TRACE_LOG 记录作业状态变更痕迹表。
可通过每次作业运行的 task_id 查询作业状态变化的生命周期和运行轨迹。
# 操作 API

ElasticJob-Lite 提供了 Java API，可以通过直接对注册中心进行操作的方式控制作业在分布式环境下的生命周期。

该模块目前仍处于孵化状态。

## 配置类 API

类名称：`org.apache.shardingsphere.elasticjob.lite.lifecycle.api.JobConfigurationAPI`

### 获取作业配置

方法签名：YamlJobConfiguration getJobConfiguration(String jobName)

* **Parameters:** 
  * jobName — 作业名称

* **Returns:** 作业配置对象

### 更新作业配置

方法签名：void updateJobConfiguration(YamlJobConfiguration yamlJobConfiguration)

* **Parameters:** 
  * jobConfiguration — 作业配置对象

### 删除作业设置

方法签名：void removeJobConfiguration(String jobName)

* **Parameters:** 
  * jobName — 作业名称

## 操作类 API

类名称：`org.apache.shardingsphere.elasticjob.lite.lifecycle.api.JobConfigurationAPI`

### 触发作业执行

作业在不与当前运行中作业冲突的情况下才会触发执行，并在启动后自动清理此标记。

方法签名：void trigger(Optional<String> jobName, Optional<String> serverIp)

* **Parameters:**
  * jobName — 作业名称
  * serverIp — 作业服务器IP地址

### 禁用作业

禁用作业将会导致分布式的其他作业触发重新分片。

方法签名：void disable(Optional<String> jobName, Optional<String> serverIp)

* **Parameters:**
  * jobName — 作业名称
  * serverIp — 作业服务器 IP 地址

### 启用作业

方法签名：void enable(Optional<String> jobName, Optional<String> serverIp)

* **Parameters:**
  * jobName — 作业名称
  * serverIp — 作业服务器 IP 地址

### 停止调度作业

方法签名：void shutdown(Optional<String> jobName, Optional<String> serverIp)

* **Parameters:**
  * jobName — 作业名称
  * serverIp — 作业服务器IP地址

### 删除作业

方法签名：void remove(Optional<String> jobName, Optional<String> serverIp)

* **Parameters:**
  * jobName — 作业名称
  * serverIp — 作业服务器IP地址

## 操作分片的 API

类名称：`org.apache.shardingsphere.elasticjob.lite.lifecycle.api.ShardingOperateAPI`

### 禁用作业分片

方法签名：void disable(String jobName, String item)

* **Parameters:**
  * jobName — 作业名称
  * item — 作业分片项

### 启用作业分片

方法签名：void enable(String jobName, String item)

* **Parameters:**
  * jobName — 作业名称
  * item — 作业分片项

## 作业统计 API

类名称：`org.apache.shardingsphere.elasticjob.lite.lifecycle.api.JobStatisticsAPI`

### 获取作业总数

方法签名：int getJobsTotalCount()

* **Returns:** 作业总数

### 获取作业简明信息

方法签名：JobBriefInfo getJobBriefInfo(String jobName)

* **Parameters:**
  * jobName — 作业名称
 
* **Returns:** 作业简明信息

### 获取所有作业简明信息

方法签名：Collection<JobBriefInfo> getAllJobsBriefInfo()

* **Returns:** 作业简明信息集合

### 获取该 IP 下所有作业简明信息

方法签名：Collection<JobBriefInfo> getJobsBriefInfo(String ip)

* **Parameters:**
  * ip — 服务器 IP
 
* **Returns:** 作业简明信息集合

## 作业服务器状态展示 API

类名称：`org.apache.shardingsphere.elasticjob.lite.lifecycle.api.ServerStatisticsAPI`

### 获取作业服务器总数

方法签名：int getServersTotalCount()

* **Returns:** 作业服务器总数

### 获取所有作业服务器简明信息

方法签名：Collection<ServerBriefInfo> getAllServersBriefInfo()

* **Returns:** 作业服务器简明信息集合

## 作业分片状态展示 API

类名称：`org.apache.shardingsphere.elasticjob.lite.lifecycle.api.ShardingStatisticsAPI`

### 获取作业分片信息集合

方法签名：Collection<ShardingInfo> getShardingInfo(String jobName)

* **Parameters:**
  * jobName — 作业名称
 
* **Returns:** 作业分片信息集合