diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml new file mode 100644 index 00000000..be4b92df --- /dev/null +++ b/.github/workflows/deploy-docs.yml @@ -0,0 +1,32 @@ +name: Deploy Docs +on: + push: + branches-ignore: [ gh-pages ] + tags: '**' + repository_dispatch: + types: request-build-reference # legacy + #schedule: + #- cron: '0 10 * * *' # Once per day at 10am UTC + workflow_dispatch: +permissions: + actions: write +jobs: + build: + runs-on: ubuntu-latest + # if: github.repository_owner == 'spring-cloud' + steps: + - name: Checkout + uses: actions/checkout@v3 + with: + ref: docs-build + fetch-depth: 1 + - name: Dispatch (partial build) + if: github.ref_type == 'branch' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD) -f build-refname=${{ github.ref_name }} + - name: Dispatch (full build) + if: github.ref_type == 'tag' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD) diff --git a/.gitignore b/.gitignore index de421b99..f5a6f0e6 100644 --- a/.gitignore +++ b/.gitignore @@ -34,3 +34,9 @@ spring-*/src/main/java/META-INF/MANIFEST.MF # Github Actions .m2 + +node +node_modules +build +package.json +package-lock.json diff --git a/README.adoc b/README.adoc index 6f38d6d9..20e2e963 100644 --- a/README.adoc +++ b/README.adoc @@ -5,6 +5,7 @@ Edit the files in the src/main/asciidoc/ directory instead. //// +[[spring-cloud-task]] = Spring Cloud Task Is a project centered around the idea of processing on demand. A user is able to develop @@ -12,10 +13,12 @@ a “task” that can be deployed, executed and removed on demand, yet the resul process persists beyond the life of the task for future reporting. +[[requirements:]] == Requirements: * Java 17 or Above +[[build-main-project:]] == Build Main Project: [source,shell,indent=2] @@ -23,6 +26,7 @@ process persists beyond the life of the task for future reporting. $ ./mvnw clean install ---- +[[example:]] == Example: [source,java,indent=2] @@ -50,9 +54,11 @@ public class MyApp { } ---- +[[code-of-conduct]] == Code of Conduct This project adheres to the Contributor Covenant link:CODE_OF_CONDUCT.adoc[code of conduct]. By participating, you are expected to uphold this code. Please report unacceptable behavior to spring-code-of-conduct@pivotal.io. +[[building-the-project]] == Building the Project This project requires that you invoke the Javadoc engine from the Maven command line. You can do so by appending `javadoc:aggregate` to the rest of your Maven command. diff --git a/docs/antora-playbook.yml b/docs/antora-playbook.yml new file mode 100644 index 00000000..e7720312 --- /dev/null +++ b/docs/antora-playbook.yml @@ -0,0 +1,38 @@ +antora: + extensions: + - '@springio/antora-extensions/partial-build-extension' + - require: '@springio/antora-extensions/latest-version-extension' + - require: '@springio/antora-extensions/inject-collector-cache-config-extension' + - '@antora/collector-extension' + - '@antora/atlas-extension' + - require: '@springio/antora-extensions/root-component-extension' + root_component_name: 'cloud-task' +site: + title: Spring Cloud Task + url: https://docs.spring.io/spring-cloud-task/reference/ +content: + sources: + - url: ./.. + branches: HEAD + start_path: docs + worktrees: true +asciidoc: + attributes: + page-stackoverflow-url: https://stackoverflow.com/tags/spring-cloud + page-pagination: '' + hide-uri-scheme: '@' + tabs-sync-option: '@' + chomp: 'all' + extensions: + - '@asciidoctor/tabs' + - '@springio/asciidoctor-extensions' + sourcemap: true +urls: + latest_version_segment: '' +runtime: + log: + failure_level: warn + format: pretty +ui: + bundle: + url: https://github.com/spring-io/antora-ui-spring/releases/download/v0.3.5/ui-bundle.zip diff --git a/docs/antora.yml b/docs/antora.yml new file mode 100644 index 00000000..a1c0b6b6 --- /dev/null +++ b/docs/antora.yml @@ -0,0 +1,12 @@ +name: cloud-task +version: true +title: spring-cloud-task +nav: + - modules/ROOT/nav.adoc +ext: + collector: + run: + command: ./mvnw --no-transfer-progress -B process-resources -Pdocs -pl docs -Dantora-maven-plugin.phase=none -Dgenerate-docs.phase=none -Dgenerate-readme.phase=none -Dgenerate-cloud-resources.phase=none -Dmaven-dependency-plugin-for-docs.phase=none -Dmaven-dependency-plugin-for-docs-classes.phase=none -DskipTests + local: true + scan: + dir: ./target/classes/antora-resources/ diff --git a/docs/modules/ROOT/assets/images/task_schema.png b/docs/modules/ROOT/assets/images/task_schema.png new file mode 100644 index 00000000..aa98a9d6 Binary files /dev/null and b/docs/modules/ROOT/assets/images/task_schema.png differ diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc new file mode 100644 index 00000000..4afa587e --- /dev/null +++ b/docs/modules/ROOT/nav.adoc @@ -0,0 +1,11 @@ +* xref:index.adoc[] +* xref:preface.adoc[] +* xref:getting-started.adoc[] +* xref:features.adoc[] +* xref:batch.adoc[] +* xref:batch-starter.adoc[] +* xref:stream.adoc[] +* xref:appendix.adoc[] +** xref:appendix-task-repository-schema.adoc[] +** xref:appendix-building-the-documentation.adoc[] +** xref:observability.adoc[] diff --git a/docs/src/main/asciidoc/_attributes.adoc b/docs/modules/ROOT/pages/_attributes.adoc similarity index 99% rename from docs/src/main/asciidoc/_attributes.adoc rename to docs/modules/ROOT/pages/_attributes.adoc index 9d81da7f..918a0223 100644 --- a/docs/src/main/asciidoc/_attributes.adoc +++ b/docs/modules/ROOT/pages/_attributes.adoc @@ -1,8 +1,6 @@ :doctype: book :idprefix: :idseparator: - -:toc: left -:toclevels: 4 :tabsize: 4 :numbered: :sectanchors: diff --git a/docs/src/main/asciidoc/appendix-building-the-documentation.adoc b/docs/modules/ROOT/pages/appendix-building-the-documentation.adoc similarity index 76% rename from docs/src/main/asciidoc/appendix-building-the-documentation.adoc rename to docs/modules/ROOT/pages/appendix-building-the-documentation.adoc index 1103edaf..e015445d 100644 --- a/docs/src/main/asciidoc/appendix-building-the-documentation.adoc +++ b/docs/modules/ROOT/pages/appendix-building-the-documentation.adoc @@ -1,6 +1,7 @@ [[appendix-building-the-documentation]] -== Building This Documentation += Building This Documentation +:page-section-summary-toc: 1 This project uses Maven to generate this documentation. To generate it for yourself, run the following command: `$ mvn clean install -DskipTests -P docs`. diff --git a/docs/src/main/asciidoc/appendix-task-repository-schema.adoc b/docs/modules/ROOT/pages/appendix-task-repository-schema.adoc similarity index 91% rename from docs/src/main/asciidoc/appendix-task-repository-schema.adoc rename to docs/modules/ROOT/pages/appendix-task-repository-schema.adoc index ce8096b3..f5882b43 100644 --- a/docs/src/main/asciidoc/appendix-task-repository-schema.adoc +++ b/docs/modules/ROOT/pages/appendix-task-repository-schema.adoc @@ -1,5 +1,5 @@ [[appendix-task-repository-schema]] -== Task Repository Schema += Task Repository Schema [[partintro]] -- @@ -8,7 +8,8 @@ This appendix provides an ERD for the database schema used in the task repositor image::task_schema.png[] -=== Table Information +[[table-information]] +== Table Information -- .TASK_EXECUTION @@ -34,9 +35,9 @@ Spring Cloud Task Framework at app startup establishes the next available id as |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 <> +|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 xref:features.adoc#features-external_task_id[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 <> +|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 xref:features.adoc#features-parent_task_id[here] |========================================================= @@ -65,7 +66,7 @@ Used to link the task execution to the batch execution. .TASK_LOCK -Used for the `single-instance-enabled` feature discussed <>. +Used for the `single-instance-enabled` feature discussed xref:features.adoc#features-single-instance-enabled[here]. [width="80%", cols="1,1,1,1,10", options="header"] |========================================================= |Column Name |Required |Type | Field Length |Notes @@ -84,7 +85,8 @@ Used for the `single-instance-enabled` feature discussed < @@ -22,16 +21,13 @@ To obtain the starter for Maven, add the following to your build: 2.3.0 ---- -==== 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 @@ -625,6 +621,7 @@ Second, this starter lets you configure two properties on the writer. For more about the configuration options for the `KafkaItemWriter`, see the https://docs.spring.io/spring-batch/docs/4.3.x/api/org/springframework/batch/item/kafka/KafkaItemWriter.html[`KafkaItemWiter` documentation]. +[[spring-aot]] === Spring AOT When using Spring AOT with Single Step Batch Starter you must set the reader and writer name properties at compile time (unless you create a bean(s) for the reader and or writer). diff --git a/docs/src/main/asciidoc/batch.adoc b/docs/modules/ROOT/pages/batch.adoc similarity index 96% rename from docs/src/main/asciidoc/batch.adoc rename to docs/modules/ROOT/pages/batch.adoc index 958854b1..0347d753 100644 --- a/docs/src/main/asciidoc/batch.adoc +++ b/docs/modules/ROOT/pages/batch.adoc @@ -135,6 +135,7 @@ NOTE: You can find a sample remote partition application in the samples module o Spring Cloud Task project, https://github.com/spring-cloud/spring-cloud-task/tree/master/spring-cloud-task-samples/partitioned-batch-job[here]. +[[asynchronously-launch-remote-batch-partitions]] === Asynchronously launch remote batch partitions By default batch partitions are launched sequentially. However, in some cases this may affect performance as each launch will block until the resource (For example: provisioning a pod in Kubernetes) is provisioned. @@ -169,6 +170,7 @@ For example: NOTE: We need to close the context since the use of `ThreadPoolTaskExecutor` leaves a thread active thus the app will not terminate. To close the application appropriately, we will need to set `spring.cloud.task.closecontextEnabled` property to `true`. +[[notes-on-developing-a-batch-partitioned-application-for-the-kubernetes-platform]] === Notes on Developing a Batch-partitioned application for the Kubernetes Platform * When deploying partitioned apps on the Kubernetes platform, you must use the following @@ -190,12 +192,12 @@ Otherwise, an exception is thrown. == Batch Informational Messages Spring Cloud Task provides the ability for batch jobs to emit informational messages. The -"`<>`" section covers this feature in detail. +"`xref:stream.adoc#stream-integration-batch-events[Spring Batch Events]`" section covers this feature in detail. [[batch-failures-and-tasks]] == Batch Job Exit Codes -As discussed <>, Spring Cloud Task +As discussed xref:features.adoc#features-lifecycle-exit-codes[earlier], Spring Cloud Task applications support the ability to record the exit code of a task execution. However, in cases where you run a Spring Batch Job within a task, regardless of how the Batch Job Execution completes, the result of the task is always zero when using the default diff --git a/docs/modules/ROOT/pages/configprops.adoc b/docs/modules/ROOT/pages/configprops.adoc new file mode 100644 index 00000000..32cbb8e5 --- /dev/null +++ b/docs/modules/ROOT/pages/configprops.adoc @@ -0,0 +1,6 @@ +[[configuration-properties]] += Configuration Properties + +Below you can find a list of configuration properties. + +include::partial$_configprops.adoc[] diff --git a/docs/src/main/asciidoc/features.adoc b/docs/modules/ROOT/pages/features.adoc similarity index 98% rename from docs/src/main/asciidoc/features.adoc rename to docs/modules/ROOT/pages/features.adoc index 5922b5bb..1fc9af7c 100644 --- a/docs/src/main/asciidoc/features.adoc +++ b/docs/modules/ROOT/pages/features.adoc @@ -98,7 +98,7 @@ boot application. === Mapping Exit Codes When a task completes, it tries to return an exit code to the OS. If we take a look -at our <>, we can see that we are +at our xref:getting-started.adoc#getting-started-developing-first-task[original example], we can see that we are not controlling that aspect of our application. So, if an exception is thrown, the JVM returns a code that may or may not be of any use to you in debugging. @@ -372,6 +372,7 @@ application: NOTE: The exit code for the application will be 1 if the task fails because this feature is enabled and another task is running with the same task name. +[[single-instance-usage-for-spring-aot-and-native-compilation]] ==== Single Instance Usage for Spring AOT And Native Compilation To use Spring Cloud Task's single-instance feature when creating a natively compiled app, you need to enable the feature at build time. To do so, add the process-aot execution and set `spring.cloud.task.single-step-instance-enabled=true` as a JVM argument, as follows: @@ -394,6 +395,7 @@ To do so, add the process-aot execution and set `spring.cloud.task.single-step-i +[[enabling-observations-for-applicationrunner-and-commandlinerunner]] === Enabling Observations for ApplicationRunner and CommandLineRunner @@ -401,6 +403,7 @@ To Enable Task Observations for `ApplicationRunner` or `CommandLineRunner` set ` An example task application with observations enables using the `SimpleMeterRegistry` can be found https://github.com/spring-cloud/spring-cloud-task/tree/main/spring-cloud-task-samples/task-observations[here]. +[[disabling-spring-cloud-task-auto-configuration]] === Disabling Spring Cloud Task Auto Configuration In cases where Spring Cloud Task should not be autoconfigured for an implementation, you can disable Task's auto configuration. diff --git a/docs/src/main/asciidoc/getting-started.adoc b/docs/modules/ROOT/pages/getting-started.adoc similarity index 98% rename from docs/src/main/asciidoc/getting-started.adoc rename to docs/modules/ROOT/pages/getting-started.adoc index f59cde28..5142bb34 100755 --- a/docs/src/main/asciidoc/getting-started.adoc +++ b/docs/modules/ROOT/pages/getting-started.adoc @@ -23,6 +23,7 @@ environment. You need to have Java installed (Java 17 or better). To build, you need to have Maven installed as well. +[[database-requirements]] === Database Requirements Spring Cloud Task uses a relational database to store the results of an executed task. @@ -136,7 +137,7 @@ In our demo, the `TaskRepository` uses an embedded H2 database to record the res of a task. This H2 embedded database is not a practical solution for a production environment, since the H2 DB goes away once the task ends. However, for a quick getting-started experience, we can use this in our example as well as echoing to the logs what is being updated -in that repository. In the <> section (later in this +in that repository. In the xref:features.adoc#features-configuration[Configuration] section (later in this documentation), we cover how to customize the configuration of the pieces provided by Spring Cloud Task. diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc new file mode 100644 index 00000000..22e6a15f --- /dev/null +++ b/docs/modules/ROOT/pages/index.adoc @@ -0,0 +1,25 @@ +[[spring-cloud-task-reference-guide]] += Spring Cloud Task Reference Guide +:page-section-summary-toc: 1 +Michael Minella, Glenn Renfro, Jay Bryant + + +// ====================================================================================== + +Version {project-version} + +(C) 2009-2022 VMware, Inc. All rights reserved. + +Copies of this document may be made for your own use and for distribution to +others, provided that you do not charge any fee for such copies and further +provided that each copy contains this Copyright Notice, whether distributed in +print or electronically. + + + + + + + + +// ====================================================================================== diff --git a/docs/modules/ROOT/pages/observability.adoc b/docs/modules/ROOT/pages/observability.adoc new file mode 100644 index 00000000..9784e942 --- /dev/null +++ b/docs/modules/ROOT/pages/observability.adoc @@ -0,0 +1,8 @@ +[[observability]] += Observability + +== Observability metadata + +include::partial$_metrics.adoc[] + +include::partial$_spans.adoc[] diff --git a/docs/src/main/asciidoc/preface.adoc b/docs/modules/ROOT/pages/preface.adoc similarity index 65% rename from docs/src/main/asciidoc/preface.adoc rename to docs/modules/ROOT/pages/preface.adoc index 0c47f351..7093d75e 100644 --- a/docs/src/main/asciidoc/preface.adoc +++ b/docs/modules/ROOT/pages/preface.adoc @@ -7,10 +7,11 @@ This section provides a brief overview of the Spring Cloud Task reference docume Think of it as a map for the rest of the document. You can read this reference guide in a linear fashion or you can skip sections if something does not interest you. +[[about-the-documentation]] == About the documentation -The Spring Cloud Task reference guide is available in {spring-cloud-task-docs}[html] -and {spring-cloud-task-docs}/index.pdf[pdf]. The latest copy is available at -{spring-cloud-task-docs-current}. +The Spring Cloud Task reference guide is available in https://docs.spring.io/spring-cloud-task/docs/current/reference[html]. +The latest copy is available at +https://docs.spring.io/spring-cloud-task/docs/current-SNAPSHOT/reference/html/. Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each @@ -32,14 +33,14 @@ involved]. [[task-documentation-first-steps]] == First Steps If you are just getting started with Spring Cloud Task or with 'Spring' in general, we -suggesting reading the <> chapter. +suggesting reading the xref:getting-started.adoc[Getting started] chapter. To get started from scratch, read the following sections: -* <> -* <> + +* xref:getting-started.adoc#getting-started-introducing-spring-cloud-task[Introducing Spring Cloud Task] +* xref:getting-started.adoc#getting-started-system-requirements[System Requirements] + To follow the tutorial, read -<> + +xref:getting-started.adoc#getting-started-developing-first-task[Developing Your First Spring Cloud Task Application] + To run your example, read -<> +xref:getting-started.adoc#getting-started-running-the-example[Running the Example] diff --git a/docs/src/main/asciidoc/spring-cloud-task.adoc b/docs/modules/ROOT/pages/spring-cloud-task.adoc similarity index 74% rename from docs/src/main/asciidoc/spring-cloud-task.adoc rename to docs/modules/ROOT/pages/spring-cloud-task.adoc index 99c6585c..22e6a15f 100644 --- a/docs/src/main/asciidoc/spring-cloud-task.adoc +++ b/docs/modules/ROOT/pages/spring-cloud-task.adoc @@ -1,7 +1,8 @@ +[[spring-cloud-task-reference-guide]] = Spring Cloud Task Reference Guide +:page-section-summary-toc: 1 Michael Minella, Glenn Renfro, Jay Bryant -include::_attributes.adoc[] // ====================================================================================== @@ -14,18 +15,11 @@ others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically. -include::preface.adoc[] -include::getting-started.adoc[] -include::features.adoc[] -include::batch.adoc[] -include::batch-starter.adoc[] -include::stream.adoc[] -include::appendix.adoc[] // ====================================================================================== diff --git a/docs/src/main/asciidoc/stream.adoc b/docs/modules/ROOT/pages/stream.adoc similarity index 98% rename from docs/src/main/asciidoc/stream.adoc rename to docs/modules/ROOT/pages/stream.adoc index 28da2750..558af79f 100644 --- a/docs/src/main/asciidoc/stream.adoc +++ b/docs/modules/ROOT/pages/stream.adoc @@ -162,6 +162,7 @@ NOTE: A sample batch event application can be found in the samples module of the Spring Cloud Task Project, https://github.com/spring-cloud/spring-cloud-task/tree/master/spring-cloud-task-samples/batch-events[here]. +[[sending-batch-events-to-different-channels]] === Sending Batch Events to Different Channels One of the options that Spring Cloud Task offers for batch events is the ability to alter @@ -174,6 +175,7 @@ following configuration: `spring.cloud.task.batch.events.step-execution-events-binding-name=my-step-execution-events` +[[disabling-batch-events]] === Disabling Batch Events To disable the listener functionality for all batch events, use the following configuration: @@ -197,6 +199,7 @@ spring.cloud.task.batch.events.item-write.enabled=false spring.cloud.task.batch.events.skip.enabled=false ---- +[[emit-order-for-batch-events]] === Emit Order for Batch Events By default, batch events have `Ordered.LOWEST_PRECEDENCE`. To change this value (for example, to 5 ), use the following configuration: diff --git a/docs/src/main/asciidoc/_configprops.adoc b/docs/modules/ROOT/partials/_configprops.adoc similarity index 100% rename from docs/src/main/asciidoc/_configprops.adoc rename to docs/modules/ROOT/partials/_configprops.adoc diff --git a/docs/modules/ROOT/partials/_conventions.adoc b/docs/modules/ROOT/partials/_conventions.adoc new file mode 100644 index 00000000..36625960 --- /dev/null +++ b/docs/modules/ROOT/partials/_conventions.adoc @@ -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` +|=== diff --git a/docs/modules/ROOT/partials/_metrics.adoc b/docs/modules/ROOT/partials/_metrics.adoc new file mode 100644 index 00000000..e25dbc61 --- /dev/null +++ b/docs/modules/ROOT/partials/_metrics.adoc @@ -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. +|=== + + + + diff --git a/docs/modules/ROOT/partials/_spans.adoc b/docs/modules/ROOT/partials/_spans.adoc new file mode 100644 index 00000000..2bd73430 --- /dev/null +++ b/docs/modules/ROOT/partials/_spans.adoc @@ -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. +|=== + + + + diff --git a/docs/pom.xml b/docs/pom.xml index c1456dc3..52c42cdb 100644 --- a/docs/pom.xml +++ b/docs/pom.xml @@ -1,26 +1,30 @@ - + 4.0.0 + org.springframework.cloud + spring-cloud-task-docs org.springframework.cloud spring-cloud-task-parent 3.1.0-SNAPSHOT - spring-cloud-task-docs + jar Spring Cloud Task Docs Spring Cloud Task Docs spring-cloud-task ${basedir}/.. - spring.cloud.task.* - deploy - 1.5.0-alpha.16 + spring.cloud.* + + none - 1.0.0 - ${maven.multiModuleProjectDirectory}/spring-cloud-task-core + 1.0.2 + ${maven.multiModuleProjectDirectory}/spring-cloud-task-core/ .* - ${maven.multiModuleProjectDirectory}/target/ + ${maven.multiModuleProjectDirectory}/docs/modules/ROOT/partials/ @@ -41,31 +45,34 @@ docs + + + src/main/antora/resources/antora-resources + true + + pl.project13.maven git-commit-id-plugin + org.apache.maven.plugins maven-dependency-plugin - - maven-resources-plugin - org.codehaus.mojo exec-maven-plugin + - generate-docs - prepare-package + generate-observability-docs + ${generate-docs.phase} java - - io.micrometer.docs.DocsGeneratorCommand - + io.micrometer.docs.DocsGeneratorCommand true ${micrometer-docs-generator.inputPath} @@ -85,10 +92,15 @@ - org.asciidoctor - asciidoctor-maven-plugin + io.spring.maven.antora + antora-component-version-maven-plugin + io.spring.maven.antora + antora-maven-plugin + + + org.apache.maven.plugins maven-antrun-plugin diff --git a/docs/src/main/antora/resources/antora-resources/antora.yml b/docs/src/main/antora/resources/antora-resources/antora.yml new file mode 100644 index 00000000..9148923f --- /dev/null +++ b/docs/src/main/antora/resources/antora-resources/antora.yml @@ -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@ diff --git a/docs/src/main/asciidoc/README.adoc b/docs/src/main/asciidoc/README.adoc index 2cb3623d..02130ce2 100644 --- a/docs/src/main/asciidoc/README.adoc +++ b/docs/src/main/asciidoc/README.adoc @@ -1,3 +1,4 @@ +[[spring-cloud-task]] = Spring Cloud Task Is a project centered around the idea of processing on demand. A user is able to develop @@ -5,10 +6,12 @@ a “task” that can be deployed, executed and removed on demand, yet the resul process persists beyond the life of the task for future reporting. +[[requirements:]] == Requirements: * Java 17 or Above +[[build-main-project:]] == Build Main Project: [source,shell,indent=2] @@ -16,6 +19,7 @@ process persists beyond the life of the task for future reporting. $ ./mvnw clean install ---- +[[example:]] == Example: [source,java,indent=2] @@ -43,9 +47,11 @@ public class MyApp { } ---- +[[code-of-conduct]] == Code of Conduct This project adheres to the Contributor Covenant link:CODE_OF_CONDUCT.adoc[code of conduct]. By participating, you are expected to uphold this code. Please report unacceptable behavior to spring-code-of-conduct@pivotal.io. +[[building-the-project]] == Building the Project This project requires that you invoke the Javadoc engine from the Maven command line. You can do so by appending `javadoc:aggregate` to the rest of your Maven command. diff --git a/docs/src/main/asciidoc/_observability.adoc b/docs/src/main/asciidoc/_observability.adoc deleted file mode 100644 index 01121b26..00000000 --- a/docs/src/main/asciidoc/_observability.adoc +++ /dev/null @@ -1,8 +0,0 @@ -:root-target: ../../../target/ - -[[observability]] -== Observability metadata - -include::{root-target}_metrics.adoc[] - -include::{root-target}_spans.adoc[] diff --git a/docs/src/main/asciidoc/appendix.adoc b/docs/src/main/asciidoc/appendix.adoc deleted file mode 100644 index 7540549e..00000000 --- a/docs/src/main/asciidoc/appendix.adoc +++ /dev/null @@ -1,12 +0,0 @@ - -[[appendix]] -= Appendices - -include::appendix-task-repository-schema.adoc[] - -include::appendix-building-the-documentation.adoc[] - -ifndef::train-docs[] -include::_observability.adoc[] -endif::[] - diff --git a/docs/src/main/asciidoc/index.adoc b/docs/src/main/asciidoc/index.adoc deleted file mode 100644 index 1af1bb98..00000000 --- a/docs/src/main/asciidoc/index.adoc +++ /dev/null @@ -1 +0,0 @@ -include::spring-cloud-task.adoc[]