Force Stop statuses

The status after a Force Stop depends on the meter type.

The different statuses reflect the recovery behavior. A Force Stop creates a distinct FORCE_STOPPED status for streaming meters because it cancels the job without creating a savepoint. For batch meters, a Force Stop has the same cancellation and recovery behavior as a normal stop, so the existing CANCELED status is used and displayed as Stopped in the UI.

A Force Stop immediately cancels the running job without creating a savepoint. Successfully processed data is not affected, but work that is in progress may not complete. When the meter is started again, it resumes from the latest successfully completed savepoint, if one is available. If no savepoint is available, the meter starts without the latest execution state.

Example 1: Streaming API source

Suppose a streaming meter has processed Events 1001 and 1002 and is processing Event 1003. Events 1004 and 1005 are waiting to be processed.

• With a Graceful Stop, the meter completes Event 1003, creates a savepoint, and stops. When restarted, processing resumes with Event 1004.

• With a Force Stop, the meter is canceled while Event 1003 is in progress. Event 1003 might not complete. When restarted, the meter resumes from the latest available savepoint, such as the savepoint created after Event 1002, or from the configured source position if no savepoint exists.

• Depending on the source configuration, Event 1003 might need to be replayed, or it might be skipped if the source cannot replay previously delivered events.

Example 2: Windowed aggregation

Consider a meter that aggregates API requests into one-minute windows. If a Force Stop occurs at 12:00:58 before the current window is completed or checkpointed, the partially completed aggregation can be discarded. After restart, the aggregation begins from the latest saved state. The affected window might contain fewer events than expected or require replay from the source. With a Graceful Stop, the aggregation state is saved before the meter stops.

Example 3: Rating pipeline

Suppose a streaming meter performs the following: Source -> Enrichment -> Rating -> Billing. The rating pipeline has completed 50,000 events and has 500 additional events in progress. A Force Stop does not affect the 50,000 completed events, but some or all of the 500 in-flight events might not finish. After restart, those events might be replayed or might need to be resent, depending on the source's replay capabilities.

Recommended stop option by scenario

• Use Graceful Stop whenever you expect to resume the meter later.
• Use Force Stop only when immediate shutdown takes priority over preserving the latest processing state.
• Before using Force Stop in production, understand whether the source can replay events. Sources that cannot replay may require manual intervention to recover in-flight events.

Best practices for managing meter statuses

Use the following guidance when monitoring and stopping meter runs:

• Streaming meters continuously process incoming events and normally remain in Running until they are stopped.

• Job Submission In Progress, Initializing, and Stopping are transitional statuses. Allow the applicable operation time to complete before taking further action.

• When a meter is in Stopping, the system is processing a graceful stop and completing the required cleanup. The run normally either returns to Running if the graceful stop cannot be completed or moves to its final terminal state.

• Use Graceful Stop whenever you expect to resume the meter later. Graceful Stop preserves the current processing state by creating a savepoint before stopping.

• Use Force Stop only when immediate shutdown is more important than preserving the latest processing state. Before using Force Stop in production, verify whether the source can replay events. A source that cannot replay events might require manual intervention to recover events that were in progress.

• If a meter remains in Stopping, wait for the graceful-stop transition to complete. Do not issue Force Stop while the meter is in this state; retry only after the meter exits Stopping.

• Do not use Force Stop while a run is in Stopping. Wait until the run exits Stopping, then retry the Force Stop operation if necessary.

• After a successful Force Stop, successfully processed data is not affected. Work that was in progress may not complete. When you start the meter again, it resumes from the latest successfully completed savepoint, if one is available.

• If a meter remains in a transitional status longer than expected, review the run details and logs. Contact Zuora Support if the status does not progress.