From 3224bf8d4c9fcfb51c96aae0c77ae6365d919f73 Mon Sep 17 00:00:00 2001 From: Marcin Grzejszczak Date: Fri, 8 Sep 2023 16:35:57 +0200 Subject: [PATCH] WIP --- .../workflows/deploy-docs.yml | 0 .gitignore | 6 ++ docs/antora-playbook.yml | 11 +-- docs/antora.yml | 4 +- docs/modules/ROOT/nav.adoc | 4 - docs/modules/ROOT/pages/_observability.adoc | 9 -- docs/modules/ROOT/pages/batch-starter.adoc | 4 - docs/modules/ROOT/pages/configprops.adoc | 6 ++ docs/modules/ROOT/pages/observability.adoc | 6 ++ .../{pages => partials}/_configprops.adoc | 2 +- docs/modules/ROOT/partials/_conventions.adoc | 13 +++ docs/modules/ROOT/partials/_metrics.adoc | 82 +++++++++++++++++++ docs/modules/ROOT/partials/_spans.adoc | 56 +++++++++++++ docs/pom.xml | 48 +++++++---- .../resources/antora-resources/antora.yml | 20 +++++ .../pages => src/main/asciidoc}/README.adoc | 0 .../main/asciidoc}/sagan-index.adoc | 0 17 files changed, 225 insertions(+), 46 deletions(-) rename {docs/.github => .github}/workflows/deploy-docs.yml (100%) delete mode 100644 docs/modules/ROOT/pages/_observability.adoc create mode 100644 docs/modules/ROOT/pages/configprops.adoc create mode 100644 docs/modules/ROOT/pages/observability.adoc rename docs/modules/ROOT/{pages => partials}/_configprops.adoc (99%) create mode 100644 docs/modules/ROOT/partials/_conventions.adoc create mode 100644 docs/modules/ROOT/partials/_metrics.adoc create mode 100644 docs/modules/ROOT/partials/_spans.adoc create mode 100644 docs/src/main/antora/resources/antora-resources/antora.yml rename docs/{modules/ROOT/pages => src/main/asciidoc}/README.adoc (100%) rename docs/{modules/ROOT/pages => src/main/asciidoc}/sagan-index.adoc (100%) diff --git a/docs/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml similarity index 100% rename from docs/.github/workflows/deploy-docs.yml rename to .github/workflows/deploy-docs.yml 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/docs/antora-playbook.yml b/docs/antora-playbook.yml index 9a70e676..e7720312 100644 --- a/docs/antora-playbook.yml +++ b/docs/antora-playbook.yml @@ -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: ./.. diff --git a/docs/antora.yml b/docs/antora.yml index 15b346da..a1c0b6b6 100644 --- a/docs/antora.yml +++ b/docs/antora.yml @@ -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: diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 3e0651c0..18c4f456 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -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[] diff --git a/docs/modules/ROOT/pages/_observability.adoc b/docs/modules/ROOT/pages/_observability.adoc deleted file mode 100644 index 5eac1efb..00000000 --- a/docs/modules/ROOT/pages/_observability.adoc +++ /dev/null @@ -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[] diff --git a/docs/modules/ROOT/pages/batch-starter.adoc b/docs/modules/ROOT/pages/batch-starter.adoc index 59d71473..16256636 100644 --- a/docs/modules/ROOT/pages/batch-starter.adoc +++ b/docs/modules/ROOT/pages/batch-starter.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] ---- @@ -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 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/modules/ROOT/pages/observability.adoc b/docs/modules/ROOT/pages/observability.adoc new file mode 100644 index 00000000..a229031d --- /dev/null +++ b/docs/modules/ROOT/pages/observability.adoc @@ -0,0 +1,6 @@ +[[observability]] +== Observability metadata + +include::partial$_metrics.adoc[] + +include::partial$_spans.adoc[] diff --git a/docs/modules/ROOT/pages/_configprops.adoc b/docs/modules/ROOT/partials/_configprops.adoc similarity index 99% rename from docs/modules/ROOT/pages/_configprops.adoc rename to docs/modules/ROOT/partials/_configprops.adoc index 418205de..9bf11375 100644 --- a/docs/modules/ROOT/pages/_configprops.adoc +++ b/docs/modules/ROOT/partials/_configprops.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. -|=== +|=== \ No newline at end of file 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/modules/ROOT/pages/README.adoc b/docs/src/main/asciidoc/README.adoc similarity index 100% rename from docs/modules/ROOT/pages/README.adoc rename to docs/src/main/asciidoc/README.adoc diff --git a/docs/modules/ROOT/pages/sagan-index.adoc b/docs/src/main/asciidoc/sagan-index.adoc similarity index 100% rename from docs/modules/ROOT/pages/sagan-index.adoc rename to docs/src/main/asciidoc/sagan-index.adoc