WIP
This commit is contained in:
Marcin Grzejszczak
6
.gitignore
vendored
6
.gitignore
vendored
@@ -34,3 +34,9 @@ spring-*/src/main/java/META-INF/MANIFEST.MF
|
||||
|
||||
# Github Actions
|
||||
.m2
|
||||
|
||||
node
|
||||
node_modules
|
||||
build
|
||||
package.json
|
||||
package-lock.json
|
||||
|
||||
@@ -6,15 +6,10 @@ antora:
|
||||
- '@antora/collector-extension'
|
||||
- '@antora/atlas-extension'
|
||||
- require: '@springio/antora-extensions/root-component-extension'
|
||||
root_component_name: 'PROJECT_WITHOUT_SPRING'
|
||||
# FIXME: Run antora once using this extension to migrate to the Asciidoc Tabs syntax
|
||||
# and then remove this extension
|
||||
- require: '@springio/antora-extensions/tabs-migration-extension'
|
||||
unwrap_example_block: always
|
||||
save_result: true
|
||||
root_component_name: 'cloud-task'
|
||||
site:
|
||||
title: PROJECT_FULL_NAME
|
||||
url: https://docs.spring.io/PROJECT_NAME/reference/
|
||||
title: Spring Cloud Task
|
||||
url: https://docs.spring.io/spring-cloud-task/reference/
|
||||
content:
|
||||
sources:
|
||||
- url: ./..
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
name: PROJECT_WITHOUT_SPRING
|
||||
name: cloud-task
|
||||
version: true
|
||||
title: PROJECT_NAME
|
||||
title: spring-cloud-task
|
||||
nav:
|
||||
- modules/ROOT/nav.adoc
|
||||
ext:
|
||||
|
||||
@@ -10,7 +10,3 @@
|
||||
* xref:appendix.adoc[]
|
||||
* xref:appendix-task-repository-schema.adoc[]
|
||||
* xref:appendix-building-the-documentation.adoc[]
|
||||
* xref:_observability.adoc[]
|
||||
* xref:README.adoc[]
|
||||
* xref:_configprops.adoc[]
|
||||
* xref:sagan-index.adoc[]
|
||||
|
||||
@@ -1,9 +0,0 @@
|
||||
:root-target: ../../../target/
|
||||
|
||||
[[observability]]
|
||||
= Observability metadata
|
||||
:page-section-summary-toc: 1
|
||||
|
||||
include::{root-target}_metrics.adoc[]
|
||||
|
||||
include::{root-target}_spans.adoc[]
|
||||
@@ -13,7 +13,6 @@ https://spring.io/projects/spring-batch[Spring Batch documentation].
|
||||
|
||||
To obtain the starter for Maven, add the following to your build:
|
||||
|
||||
====
|
||||
[source,xml]
|
||||
----
|
||||
<dependency>
|
||||
@@ -22,16 +21,13 @@ To obtain the starter for Maven, add the following to your build:
|
||||
<version>2.3.0</version>
|
||||
</dependency>
|
||||
----
|
||||
====
|
||||
|
||||
To obtain the starter for Gradle, add the following to your build:
|
||||
|
||||
====
|
||||
[source,groovy]
|
||||
----
|
||||
compile "org.springframework.cloud:spring-cloud-starter-single-step-batch-job:2.3.0"
|
||||
----
|
||||
====
|
||||
|
||||
[[job-definition]]
|
||||
== Defining a Job
|
||||
|
||||
6
docs/modules/ROOT/pages/configprops.adoc
Normal file
6
docs/modules/ROOT/pages/configprops.adoc
Normal file
@@ -0,0 +1,6 @@
|
||||
[[configuration-properties]]
|
||||
= Configuration Properties
|
||||
|
||||
Below you can find a list of configuration properties.
|
||||
|
||||
include::partial$_configprops.adoc[]
|
||||
6
docs/modules/ROOT/pages/observability.adoc
Normal file
6
docs/modules/ROOT/pages/observability.adoc
Normal file
@@ -0,0 +1,6 @@
|
||||
[[observability]]
|
||||
== Observability metadata
|
||||
|
||||
include::partial$_metrics.adoc[]
|
||||
|
||||
include::partial$_spans.adoc[]
|
||||
@@ -41,4 +41,4 @@
|
||||
|spring.cloud.task.single-instance-lock-ttl | | Declares the maximum amount of time (in millis) that a task execution can hold a lock to prevent another task from executing with a specific task name when the single-instance-enabled is set to true. Default time is: Integer.MAX_VALUE.
|
||||
|spring.cloud.task.table-prefix | `+++TASK_+++` | The prefix to append to the table names created by Spring Cloud Task.
|
||||
|
||||
|===
|
||||
|===
|
||||
13
docs/modules/ROOT/partials/_conventions.adoc
Normal file
13
docs/modules/ROOT/partials/_conventions.adoc
Normal file
@@ -0,0 +1,13 @@
|
||||
[[observability-conventions]]
|
||||
=== Observability - Conventions
|
||||
|
||||
Below you can find a list of all `GlobalObservationConvention` and `ObservationConvention` declared by this project.
|
||||
|
||||
.ObservationConvention implementations
|
||||
|===
|
||||
|ObservationConvention Class Name | Applicable ObservationContext Class Name
|
||||
|`org.springframework.cloud.task.listener.DefaultTaskExecutionObservationConvention`|`TaskExecutionObservationContext`
|
||||
|`org.springframework.cloud.task.listener.TaskExecutionObservationConvention`|`TaskExecutionObservationContext`
|
||||
|`org.springframework.cloud.task.configuration.observation.DefaultTaskObservationConvention`|`TaskObservationContext`
|
||||
|`org.springframework.cloud.task.configuration.observation.TaskObservationConvention`|`TaskObservationContext`
|
||||
|===
|
||||
82
docs/modules/ROOT/partials/_metrics.adoc
Normal file
82
docs/modules/ROOT/partials/_metrics.adoc
Normal file
@@ -0,0 +1,82 @@
|
||||
[[observability-metrics]]
|
||||
=== Observability - Metrics
|
||||
|
||||
Below you can find a list of all metrics declared by this project.
|
||||
|
||||
[[observability-metrics-task-active]]
|
||||
==== 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`.
|
||||
|
||||
|
||||
IMPORTANT: KeyValues that are added after starting the Observation might be missing from the *.active metrics.
|
||||
|
||||
|
||||
IMPORTANT: 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`.
|
||||
|
||||
IMPORTANT: All tags must be prefixed with `spring.cloud.task` prefix!
|
||||
|
||||
.Low cardinality Keys
|
||||
[cols="a,a"]
|
||||
|===
|
||||
|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.
|
||||
|===
|
||||
|
||||
|
||||
|
||||
[[observability-metrics-task-runner-observation]]
|
||||
==== 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`.
|
||||
|
||||
|
||||
IMPORTANT: KeyValues that are added after starting the Observation might be missing from the *.active metrics.
|
||||
|
||||
|
||||
IMPORTANT: 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`.
|
||||
|
||||
IMPORTANT: All tags must be prefixed with `spring.cloud.task` prefix!
|
||||
|
||||
.Low cardinality Keys
|
||||
[cols="a,a"]
|
||||
|===
|
||||
|Name | Description
|
||||
|`spring.cloud.task.runner.bean-name` _(required)_|Name of the bean that was executed by Spring Cloud Task.
|
||||
|===
|
||||
|
||||
|
||||
|
||||
|
||||
56
docs/modules/ROOT/partials/_spans.adoc
Normal file
56
docs/modules/ROOT/partials/_spans.adoc
Normal file
@@ -0,0 +1,56 @@
|
||||
[[observability-spans]]
|
||||
=== Observability - Spans
|
||||
|
||||
Below you can find a list of all spans declared by this project.
|
||||
|
||||
[[observability-spans-task-active]]
|
||||
==== 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`.
|
||||
|
||||
IMPORTANT: All tags must be prefixed with `spring.cloud.task` prefix!
|
||||
|
||||
.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.
|
||||
|===
|
||||
|
||||
|
||||
|
||||
[[observability-spans-task-runner-observation]]
|
||||
==== 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`.
|
||||
|
||||
IMPORTANT: All tags must be prefixed with `spring.cloud.task` prefix!
|
||||
|
||||
.Tag Keys
|
||||
|===
|
||||
|Name | Description
|
||||
|`spring.cloud.task.runner.bean-name` _(required)_|Name of the bean that was executed by Spring Cloud Task.
|
||||
|===
|
||||
|
||||
|
||||
|
||||
|
||||
48
docs/pom.xml
48
docs/pom.xml
@@ -1,26 +1,30 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
|
||||
<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xmlns="http://maven.apache.org/POM/4.0.0"
|
||||
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
<groupId>org.springframework.cloud</groupId>
|
||||
<artifactId>spring-cloud-task-docs</artifactId>
|
||||
<parent>
|
||||
<groupId>org.springframework.cloud</groupId>
|
||||
<artifactId>spring-cloud-task-parent</artifactId>
|
||||
<version>3.1.0-SNAPSHOT</version>
|
||||
</parent>
|
||||
<artifactId>spring-cloud-task-docs</artifactId>
|
||||
<packaging>jar</packaging>
|
||||
<name>Spring Cloud Task Docs</name>
|
||||
<description>Spring Cloud Task Docs</description>
|
||||
<properties>
|
||||
<docs.main>spring-cloud-task</docs.main>
|
||||
<main.basedir>${basedir}/..</main.basedir>
|
||||
<configprops.inclusionPattern>spring.cloud.task.*</configprops.inclusionPattern>
|
||||
<upload-docs-zip.phase>deploy</upload-docs-zip.phase>
|
||||
<asciidoctorj.pdf.version>1.5.0-alpha.16</asciidoctorj.pdf.version>
|
||||
<configprops.inclusionPattern>spring.cloud.*</configprops.inclusionPattern>
|
||||
<!-- Don't upload docs jar to central / repo.spring.io -->
|
||||
<maven-deploy-plugin-default.phase>none</maven-deploy-plugin-default.phase>
|
||||
|
||||
<!-- Observability -->
|
||||
<micrometer-docs-generator.version>1.0.0</micrometer-docs-generator.version>
|
||||
<micrometer-docs-generator.inputPath>${maven.multiModuleProjectDirectory}/spring-cloud-task-core</micrometer-docs-generator.inputPath>
|
||||
<micrometer-docs-generator.version>1.0.2</micrometer-docs-generator.version>
|
||||
<micrometer-docs-generator.inputPath>${maven.multiModuleProjectDirectory}/spring-cloud-task-core/</micrometer-docs-generator.inputPath>
|
||||
<micrometer-docs-generator.inclusionPattern>.*</micrometer-docs-generator.inclusionPattern>
|
||||
<micrometer-docs-generator.outputPath>${maven.multiModuleProjectDirectory}/target/</micrometer-docs-generator.outputPath>
|
||||
<micrometer-docs-generator.outputPath>${maven.multiModuleProjectDirectory}/docs/modules/ROOT/partials/</micrometer-docs-generator.outputPath>
|
||||
</properties>
|
||||
<dependencies>
|
||||
<dependency>
|
||||
@@ -41,31 +45,34 @@
|
||||
<profile>
|
||||
<id>docs</id>
|
||||
<build>
|
||||
<resources>
|
||||
<resource>
|
||||
<directory>src/main/antora/resources/antora-resources</directory>
|
||||
<filtering>true</filtering>
|
||||
</resource>
|
||||
</resources>
|
||||
<plugins>
|
||||
<plugin>
|
||||
<groupId>pl.project13.maven</groupId>
|
||||
<artifactId>git-commit-id-plugin</artifactId>
|
||||
</plugin>
|
||||
<plugin>
|
||||
<groupId>org.apache.maven.plugins</groupId>
|
||||
<artifactId>maven-dependency-plugin</artifactId>
|
||||
</plugin>
|
||||
<plugin>
|
||||
<artifactId>maven-resources-plugin</artifactId>
|
||||
</plugin>
|
||||
<plugin>
|
||||
<groupId>org.codehaus.mojo</groupId>
|
||||
<artifactId>exec-maven-plugin</artifactId>
|
||||
<!-- TODO: Remove this execution if you have no observability -->
|
||||
<executions>
|
||||
<execution>
|
||||
<id>generate-docs</id>
|
||||
<phase>prepare-package</phase>
|
||||
<id>generate-observability-docs</id>
|
||||
<phase>${generate-docs.phase}</phase>
|
||||
<goals>
|
||||
<goal>java</goal>
|
||||
</goals>
|
||||
<configuration>
|
||||
<mainClass>
|
||||
io.micrometer.docs.DocsGeneratorCommand
|
||||
</mainClass>
|
||||
<mainClass>io.micrometer.docs.DocsGeneratorCommand</mainClass>
|
||||
<includePluginDependencies>true</includePluginDependencies>
|
||||
<arguments>
|
||||
<argument>${micrometer-docs-generator.inputPath}</argument>
|
||||
@@ -85,10 +92,15 @@
|
||||
</dependencies>
|
||||
</plugin>
|
||||
<plugin>
|
||||
<groupId>org.asciidoctor</groupId>
|
||||
<artifactId>asciidoctor-maven-plugin</artifactId>
|
||||
<groupId>io.spring.maven.antora</groupId>
|
||||
<artifactId>antora-component-version-maven-plugin</artifactId>
|
||||
</plugin>
|
||||
<plugin>
|
||||
<groupId>io.spring.maven.antora</groupId>
|
||||
<artifactId>antora-maven-plugin</artifactId>
|
||||
</plugin>
|
||||
<plugin>
|
||||
<groupId>org.apache.maven.plugins</groupId>
|
||||
<artifactId>maven-antrun-plugin</artifactId>
|
||||
<executions>
|
||||
<execution>
|
||||
|
||||
20
docs/src/main/antora/resources/antora-resources/antora.yml
Normal file
20
docs/src/main/antora/resources/antora-resources/antora.yml
Normal file
@@ -0,0 +1,20 @@
|
||||
version: @antora-component.version@
|
||||
prerelease: @antora-component.prerelease@
|
||||
|
||||
asciidoc:
|
||||
attributes:
|
||||
attribute-missing: 'warn'
|
||||
chomp: 'all'
|
||||
project-root: @maven.multiModuleProjectDirectory@
|
||||
github-repo: @docs.main@
|
||||
github-raw: https://raw.githubusercontent.com/spring-cloud/@docs.main@/@github-tag@
|
||||
github-code: https://github.com/spring-cloud/@docs.main@/tree/@github-tag@
|
||||
github-issues: https://github.com/spring-cloud/@docs.main@/issues/
|
||||
github-wiki: https://github.com/spring-cloud/@docs.main@/wiki
|
||||
spring-cloud-version: @project.version@
|
||||
github-tag: @github-tag@
|
||||
version-type: @version-type@
|
||||
docs-url: https://docs.spring.io/@docs.main@/docs/@project.version@
|
||||
raw-docs-url: https://raw.githubusercontent.com/spring-cloud/@docs.main@/@github-tag@
|
||||
project-version: @project.version@
|
||||
project-name: @docs.main@
|
||||
Reference in New Issue
Block a user