Update event-trace doc (#1134)

apache · Jul 18, 2020 · 3831793 · 3831793
1 parent dfea320
commit 3831793
Show file tree

Hide file tree

Showing 10 changed files with 141 additions and 73 deletions.
diff --git a/docs/content/user-manual/elasticjob-lite/usage/event-trace/_index.cn.md b/docs/content/user-manual/elasticjob-lite/usage/event-trace/_index.cn.md
@@ -4,4 +4,5 @@ weight = 3
 chapter = true
 +++
 
-TODO
+ElasticJob 提供了事件追踪功能，可通过事件订阅的方式处理调度过程的重要事件，用于查询、统计和监控。
+目前提供了基于关系型数据库的事件订阅方式记录事件，开发者也可以通过 SPI 自行扩展。
diff --git a/docs/content/user-manual/elasticjob-lite/usage/event-trace/event-trace.cn.md b/docs/content/user-manual/elasticjob-lite/usage/event-trace/event-trace.cn.md
diff --git a/docs/content/user-manual/elasticjob-lite/usage/event-trace/java-api.cn.md b/docs/content/user-manual/elasticjob-lite/usage/event-trace/java-api.cn.md
@@ -0,0 +1,20 @@
++++
+title = "使用 Java API"
+weight = 1
+chapter = true
++++
+
+ElasticJob-Lite 在配置中提供了 TracingConfiguration，目前支持数据库方式配置。
+开发者也可以通过 SPI 自行扩展。
+
+```java
+    // 初始化数据源
+    DataSource dataSource = ...;
+    // 定义日志数据库事件溯源配置
+    TracingConfiguration tracingConfig = new TracingConfiguration<>("RDB", dataSource);
+    // 初始化注册中心
+    CoordinatorRegistryCenter regCenter = ...;
+    // 初始化作业配置
+    JobConfiguration jobConfig = ...;
+    new ScheduleJobBootstrap(regCenter, jobConfig, tracingConfig).schedule();
+```
diff --git a/...-lite/usage/event-trace/event-trace.en.md → ...job-lite/usage/event-trace/java-api.en.md b/...-lite/usage/event-trace/event-trace.en.md → ...job-lite/usage/event-trace/java-api.en.md
@@ -1,5 +1,5 @@
 +++
-title = "Event Trace"
+title = "Use Java API"
 weight = 1
 chapter = true
 +++

diff --git a/...content/user-manual/elasticjob-lite/usage/event-trace/spring-boot-starter.cn.md b/...content/user-manual/elasticjob-lite/usage/event-trace/spring-boot-starter.cn.md
@@ -0,0 +1,7 @@
++++
+title = "Spring Boot Starter"
+weight = 2
+chapter = true
++++
+
+TODO
diff --git a/...content/user-manual/elasticjob-lite/usage/event-trace/spring-boot-starter.en.md b/...content/user-manual/elasticjob-lite/usage/event-trace/spring-boot-starter.en.md
@@ -0,0 +1,7 @@
++++
+title = "Spring Boot Starter"
+weight = 2
+chapter = true
++++
+
+TODO
diff --git a/docs/content/user-manual/elasticjob-lite/usage/event-trace/spring-namespace.cn.md b/docs/content/user-manual/elasticjob-lite/usage/event-trace/spring-namespace.cn.md
@@ -0,0 +1,42 @@
++++
+title = "Spring 命名空间"
+weight = 3
+chapter = true
++++
+
+## 事件追踪配置
+
+```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 -->
+    <bean id="myJob" class="xxx.MyJob" />
+
+    <!-- 配置数据源 -->
+    <bean id="tracingDataSource" class="org.apache.commons.dbcp.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-event-trace 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 启动，作业将自动加载。
diff --git a/docs/content/user-manual/elasticjob-lite/usage/event-trace/spring-namespace.en.md b/docs/content/user-manual/elasticjob-lite/usage/event-trace/spring-namespace.en.md
@@ -0,0 +1,7 @@
++++
+title = "Spring Namespace"
+weight = 3
+chapter = true
++++
+
+TODO
diff --git a/docs/content/user-manual/elasticjob-lite/usage/event-trace/table-structure.cn.md b/docs/content/user-manual/elasticjob-lite/usage/event-trace/table-structure.cn.md
@@ -0,0 +1,48 @@
++++
+title = "表结构说明"
+weight = 4
+chapter = true
++++
+
+事件追踪的 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 查询作业状态变化的生命周期和运行轨迹。
diff --git a/docs/content/user-manual/elasticjob-lite/usage/event-trace/table-structure.en.md b/docs/content/user-manual/elasticjob-lite/usage/event-trace/table-structure.en.md
@@ -0,0 +1,7 @@
++++
+title = "Table Structure"
+weight = 4
+chapter = true
++++
+
+TODO