Appendices

Task Repository Schema

This appendix provides an ERD for the database schema used in the task repository.

Table Information

TASK_EXECUTION

Stores the task execution information.

Column Name Required Type Field Length Notes

Column Name	Required	Type	Field Length	Notes
TASK_EXECUTION_ID	TRUE	BIGINT	X	Spring Cloud Task Framework at app startup establishes the next available id as obtained from the `TASK_SEQ`. Or if the record is created outside of task then the value must be populated at record creation time.
START_TIME	FALSE	DATETIME(6)	X	Spring Cloud Task Framework at app startup establishes the value.
END_TIME	FALSE	DATETIME(6)	X	Spring Cloud Task Framework at app exit establishes the value.
TASK_NAME	FALSE	VARCHAR	100	Spring Cloud Task Framework at app startup will set this to "Application" unless user establish the name using the `spring.application.name`.
EXIT_CODE	FALSE	INTEGER	X	Follows Spring Boot defaults unless overridden by the user as discussed here.
EXIT_MESSAGE	FALSE	VARCHAR	2500	User Defined as discussed here.
ERROR_MESSAGE	FALSE	VARCHAR	2500	Spring Cloud Task Framework at app exit establishes the value.
LAST_UPDATED	TRUE	TIMESTAMP	X	Spring Cloud Task Framework at app startup establishes the value. Or if the record is created outside of task then the value must be populated at record creation time.
EXTERNAL_EXECUTION_ID	FALSE	VARCHAR	250	If the `spring.cloud.task.external-execution-id` property is set then Spring Cloud Task Framework at app startup will set this to the value specified. More information can be found here
PARENT_TASK_EXECUTION_ID	FALSE	BIGINT	X	If the `spring.cloud.task.parent-execution-id` property is set then Spring Cloud Task Framework at app startup will set this to the value specified. More information can be found here

TASK_EXECUTION_ID

TRUE

BIGINT

Spring Cloud Task Framework at app startup establishes the next available id as obtained from the TASK_SEQ. Or if the record is created outside of task then the value must be populated at record creation time.

START_TIME

FALSE

DATETIME(6)

Spring Cloud Task Framework at app startup establishes the value.

END_TIME

FALSE

DATETIME(6)

Spring Cloud Task Framework at app exit establishes the value.

TASK_NAME

FALSE

VARCHAR

100

Spring Cloud Task Framework at app startup will set this to "Application" unless user establish the name using the spring.application.name.

EXIT_CODE

FALSE

INTEGER

Follows Spring Boot defaults unless overridden by the user as discussed here.

EXIT_MESSAGE

FALSE

VARCHAR

2500

User Defined as discussed here.

ERROR_MESSAGE

FALSE

VARCHAR

2500

Spring Cloud Task Framework at app exit establishes the value.

LAST_UPDATED

TRUE

TIMESTAMP

Spring Cloud Task Framework at app startup establishes the value. Or if the record is created outside of task then the value must be populated at record creation time.

EXTERNAL_EXECUTION_ID

FALSE

VARCHAR

250

If the spring.cloud.task.external-execution-id property is set then Spring Cloud Task Framework at app startup will set this to the value specified. More information can be found here

PARENT_TASK_EXECUTION_ID

FALSE

BIGINT

If the spring.cloud.task.parent-execution-id property is set then Spring Cloud Task Framework at app startup will set this to the value specified. More information can be found here

TASK_EXECUTION_PARAMS

Stores the parameters used for a task execution

Column Name	Required	Type	Field Length
TASK_EXECUTION_ID	TRUE	BIGINT	X
TASK_PARAM	FALSE	VARCHAR	2500

Column Name

Required

Type

Field Length

TASK_EXECUTION_ID

TRUE

BIGINT

TASK_PARAM

FALSE

VARCHAR

2500

TASK_TASK_BATCH

Used to link the task execution to the batch execution.

Column Name	Required	Type	Field Length
TASK_EXECUTION_ID	TRUE	BIGINT	X
JOB_EXECUTION_ID	TRUE	BIGINT	X

Column Name

Required

Type

Field Length

TASK_EXECUTION_ID

TRUE

BIGINT

JOB_EXECUTION_ID

TRUE

BIGINT

TASK_LOCK

Used for the single-instance-enabled feature discussed here.

Column Name	Required	Type	Field Length	Notes
LOCK_KEY	TRUE	CHAR	36	UUID for the this lock
REGION	TRUE	VARCHAR	100	User can establish a group of locks using this field.
CLIENT_ID	TRUE	CHAR	36	The task execution id that contains the name of the app to lock.
CREATED_DATE	TRUE	DATETIME	X	The date that the entry was created

Column Name

Required

Type

Field Length

Notes

LOCK_KEY

TRUE

CHAR

UUID for the this lock

REGION

TRUE

VARCHAR

100

User can establish a group of locks using this field.

CLIENT_ID

TRUE

CHAR

The task execution id that contains the name of the app to lock.

CREATED_DATE

TRUE

DATETIME

The date that the entry was created

The DDL for setting up tables for each database type can be found here.

SQL Server

By default Spring Cloud Task uses a sequence table for determining the TASK_EXECUTION_ID for the TASK_EXECUTION table. However, when launching multiple tasks simultaneously while using SQL Server, this can cause a deadlock to occur on the TASK_SEQ table. The resolution is to drop the TASK_EXECUTION_SEQ table and create a sequence using the same name. For example:

DROP TABLE TASK_SEQ;

CREATE SEQUENCE [DBO].[TASK_SEQ] AS BIGINT
 START WITH 1
 INCREMENT BY 1;

Set the START WITH to a higher value than your current execution id.

Building This Documentation

This project uses Maven to generate this documentation. To generate it for yourself, run the following command: $ mvn clean install -DskipTests -P docs.

Observability metadata

Observability - Metrics

Below you can find a list of all metrics declared by this project.

Task Active

Metrics created around a task execution.

Metric name spring.cloud.task (defined by convention class org.springframework.cloud.task.listener.DefaultTaskExecutionObservationConvention). Type timer.

Metric name spring.cloud.task.active (defined by convention class org.springframework.cloud.task.listener.DefaultTaskExecutionObservationConvention). Type long task timer.

KeyValues that are added after starting the Observation might be missing from the *.active metrics.

Micrometer internally uses nanoseconds for the baseunit. However, each backend determines the actual baseunit. (i.e. Prometheus uses seconds)

Fully qualified name of the enclosing class org.springframework.cloud.task.listener.TaskExecutionObservation.

All tags must be prefixed with spring.cloud.task prefix!

Table 1. Low cardinality Keys
Name	Description
`spring.cloud.task.cf.app.id` (required)	App id for CF cloud.
`spring.cloud.task.cf.app.name` (required)	App name for CF cloud.
`spring.cloud.task.cf.app.version` (required)	App version for CF cloud.
`spring.cloud.task.cf.instance.index` (required)	Instance index for CF cloud.
`spring.cloud.task.cf.org.name` (required)	Organization Name for CF cloud.
`spring.cloud.task.cf.space.id` (required)	Space id for CF cloud.
`spring.cloud.task.cf.space.name` (required)	Space name for CF cloud.
`spring.cloud.task.execution.id` (required)	Task execution id.
`spring.cloud.task.exit.code` (required)	Task exit code.
`spring.cloud.task.external.execution.id` (required)	External execution id for task.
`spring.cloud.task.name` (required)	Task name measurement.
`spring.cloud.task.parent.execution.id` (required)	Task parent execution id.
`spring.cloud.task.status` (required)	task status. Can be either success or failure.

Task Runner Observation

Observation created when a task runner is executed.

Metric name spring.cloud.task.runner (defined by convention class org.springframework.cloud.task.configuration.observation.DefaultTaskObservationConvention). Type timer.

Metric name spring.cloud.task.runner.active (defined by convention class org.springframework.cloud.task.configuration.observation.DefaultTaskObservationConvention). Type long task timer.

KeyValues that are added after starting the Observation might be missing from the *.active metrics.

Micrometer internally uses nanoseconds for the baseunit. However, each backend determines the actual baseunit. (i.e. Prometheus uses seconds)

Fully qualified name of the enclosing class org.springframework.cloud.task.configuration.observation.TaskDocumentedObservation.

All tags must be prefixed with spring.cloud.task prefix!

Table 2. Low cardinality Keys
Name	Description
`spring.cloud.task.runner.bean-name` (required)	Name of the bean that was executed by Spring Cloud Task.

Observability - Spans

Below you can find a list of all spans declared by this project.

Task Active Span

Metrics created around a task execution.

Span name spring.cloud.task (defined by convention class org.springframework.cloud.task.listener.DefaultTaskExecutionObservationConvention).

Fully qualified name of the enclosing class org.springframework.cloud.task.listener.TaskExecutionObservation.

All tags must be prefixed with spring.cloud.task prefix!

Table 3. Tag Keys
Name	Description
`spring.cloud.task.cf.app.id` (required)	App id for CF cloud.
`spring.cloud.task.cf.app.name` (required)	App name for CF cloud.
`spring.cloud.task.cf.app.version` (required)	App version for CF cloud.
`spring.cloud.task.cf.instance.index` (required)	Instance index for CF cloud.
`spring.cloud.task.cf.org.name` (required)	Organization Name for CF cloud.
`spring.cloud.task.cf.space.id` (required)	Space id for CF cloud.
`spring.cloud.task.cf.space.name` (required)	Space name for CF cloud.
`spring.cloud.task.execution.id` (required)	Task execution id.
`spring.cloud.task.exit.code` (required)	Task exit code.
`spring.cloud.task.external.execution.id` (required)	External execution id for task.
`spring.cloud.task.name` (required)	Task name measurement.
`spring.cloud.task.parent.execution.id` (required)	Task parent execution id.
`spring.cloud.task.status` (required)	task status. Can be either success or failure.

Task Runner Observation Span

Observation created when a task runner is executed.

Span name spring.cloud.task.runner (defined by convention class org.springframework.cloud.task.configuration.observation.DefaultTaskObservationConvention).

Fully qualified name of the enclosing class org.springframework.cloud.task.configuration.observation.TaskDocumentedObservation.

All tags must be prefixed with spring.cloud.task prefix!

Table 4. Tag Keys
Name	Description
`spring.cloud.task.runner.bean-name` (required)	Name of the bean that was executed by Spring Cloud Task.