=================
Progress Facility
=================

About
-----

The Progress Facility makes allows reporting of the overall completion percentage of a given Omniverse Farm job.

This can be particularly helpful for Users wishing to have at-a-glance information on the overall status of a job, and to derive an approximate time of completion. This information is surfaced to Users through the `Farm Queue Dashboard <../../../app_farm/app_farm/queue.html>`_, where progress can be monitored from the list of tasks, or by inspecting the detailed view of a specific task, where timestamped progress information will be logged.

Configuration
-------------

The Progress Facility can be accessed from a Kit Service by first registering the Facility's instance on the Service's ``router``:

.. code-block:: python
   :linenos:
   :caption: extension.py
   :name: extension.py
   :emphasize-lines: 13

   import omni.ext

   from omni.services.core import main
   from omni.services.facilities.monitoring.progress.facilities import ProgressFacility

   from .services.sample import router


   class SampleProgressFacilityExtension(omni.ext.IExt):
       """Sample Extension illustrating usage of the Progress Facility."""

       def on_startup(self) -> None:
           router.register_facility(name="progress", facility_inst=ProgressFacility())
           main.register_router(router=router, prefix="/sample-progress", tags=["example"])

       def on_shutdown(self) -> None:
           main.deregister_router(router=router, prefix="/sample-progress")

Usage
-----

Once configured, the Progress Facility then becomes available to the Service's endpoints via dependency injection:

.. code-block:: python
   :linenos:
   :caption: services/sample.py
   :name: services/sample.py
   :emphasize-lines: 11,19-26

   import asyncio

   from omni.services.core import routers
   from omni.services.facilities.monitoring.progress.facilities import ProgressFacility

   router = routers.ServiceAPIRouter()


   @router.post("/sample-endpoint")
   async def sample(
       progress_facility: ProgressFacility = router.get_facility("progress"),
   ):
       # For demonstration purposes, we mimic a long-running operation by reporting progress every second
       # for a total of 60 seconds. In a real-world scenario, progress would be reported as needed by calling
       # `progress_facility.set_progress()` when appropriate, so the information could be surfaced to the User.
       TOTAL_STEP_COUNT = 60

       for step_number in range(TOTAL_STEP_COUNT):
           progress_facility.set_progress(
               # Index of the current step in the overall progress:
               current_step_index=step_number,
               # Overall number of steps in the progress:
               total_step_count=TOTAL_STEP_COUNT,
               # Optional status message providing additional information about the current progress of the task:
               status_message=f"Completed step {step_number} of {TOTAL_STEP_COUNT}",
           )

           await asyncio.sleep(delay=1.0)  # Wait a moment to mimic a long operation.

       return {"success": True}

Implementation References
-------------------------

For examples of the Progress Facility being used in the Omniverse Farm ecosystem, consult the following extensions:

 * ``omni.services.collect``: Bulk collection of USD assets
 * ``omni.services.render``: Rendering service for USD stages
 * ``omni.services.thumbnails.mdl``: Rendering service for MDL thumbnails