wip

docs/advanced/observing-job-progress.md

@@ -0,0 +1,51 @@
+# Observing job progress
+
+Every time one schedules a job (or triggers it as an instant job), a virtual orchestration is spawned.
+
+An orchestration can be as simple as a unique job or as complex as a root job and the whole hierarchy of its direct and indirect dependent jobs (see *[Model Dependencies](../features/model-dependencies.md)*).
+
+An orchestration is uniquely identifed by an identifier. All jobs belonging to an orchestration share the same `CorrelationId` (See [*"Tracing requests of dependencies via `CorrelationId`"*](../features/model-dependencies.md#tracing-requests-of-dependencies-via-correlationid).).
+
+From a timeline perspective, an orchestration starts before the root job that initiated it and completes when **all** of its leaf jobs have reached a final state.
+
+## Subscribing to the executions of jobs
+
+### Forewords
+
+!!! warning
+
+    This is an **experimental** feature subject to breaking changes independently of the standard semver lifecycle release of **NCronJob**.
+
+    While reporting feedback or bugs about it, please do not forget to
+    mention in the issue which version of NCronJob you're using.
+
+Would you decide to give it an early try, in order to suppress the warnings that comes with the [.NET Experimental attribute](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/preview-apis#experimentalattribute), update your `.csproj` with a `<NoWarn>` project setting:
+
+```xml
+<PropertyGroup>
+    ...
+    <NoWarn>$(NoWarn);NCRONJOB_OBSERVER</NoWarn>
+</PropertyGroup>
+```
+
+### Registering a notifier callback
+
+### Sample
+
+given an orchestration with jobs of varying durations the log may look like this
+
+## The ExecutionProgress type
+
+immutable snapshot
+
+### Execution states
+
+mention final states
+
+### Known limits
+
+As this feature is stiull under development, it's not complete yet.
+Below are the know missing bits of it:
+
+- [Report removed jobs as `Cancelled`](https://github.com/NCronJob-Dev/NCronJob/issues/161)
+- [Report skipped child jobs as `Skipped`](https://github.com/NCronJob-Dev/NCronJob/issues/160)

mkdocs.yml

@@ -49,6 +49,7 @@ nav:
     - Controlling the log level: advanced/log-level.md
     - Global Concurrency: advanced/global-concurrency.md
     - Dynamic Job Control: advanced/dynamic-job-control.md
+    - Observing progress of jobs: advanced/observing-job-progress.md
 
 extra:
   generator: false