Atlas Stream Processing Vertical Autoscaling

Vertical autoscaling automatically adjusts the tier of a stream processor in response to its resource usage. When you enable autoscaling, Atlas Stream Processing scales a processor up or down within the range of tiers that you define. You don't need to manually stop and restart the processor to change its tier.

Autoscaling helps you handle fluctuating workloads, absorb unexpected traffic spikes, and avoid failures that occur when a processor exhausts the resources of its tier. Because Atlas Stream Processing manages the scaling decisions internally, you don't need to monitor usage and resize processors yourself.

Use Cases

Consider enabling vertical autoscaling in the following scenarios:

Uncertain initial sizing: If you can't accurately estimate the tier a processor requires, start with a smaller tier and allow autoscaling to adjust the tier to match the actual load.
Fluctuating or growing traffic: If your workload experiences organic growth or periodic spikes, autoscaling increases resources during high demand and reduces them during low demand.
Operational resilience: If an undersized processor risks failure during peak events, autoscaling raises the tier automatically to keep the processor running.

How Autoscaling Works

When you enable autoscaling for a stream processor, Atlas Stream Processing monitors the processor's CPU and memory usage and compares it to internally managed thresholds. Atlas Stream Processing controls these thresholds to balance responsiveness and stability, and you can't configure them.

To change a processor's tier, Atlas Stream Processing performs the following actions:

Stop the processor

Atlas Stream Processing stops the processor on its current tier.

Change the tier

Atlas Stream Processing moves the processor to the next tier in the tier hierarchy: SP2, SP5, SP10, SP30, SP50.

Restart the processor

Atlas Stream Processing restarts the processor on the new tier and resumes operation from the last committed checkpoint, so no data is lost.

Scale-Up Behavior

Atlas Stream Processing scales a processor up to the next higher tier when the processor's resource usage exceeds one of the following scale-up thresholds for a sustained period:

CPU usage is above 90% for 60 minutes
Memory usage is above 80% for 60 minutes, or above 90% for 30 seconds

Atlas Stream Processing also scales a processor up if the processor runs out of memory. When autoscaling is enabled, an out-of-memory condition scales the processor up to the next higher tier instead of failing the processor.

Scaling up responds quickly to sustained resource pressure to protect processor availability.

Atlas Stream Processing scales a processor up only when the next higher tier is less than or equal to the configured maxTier.

Scale-Down Behavior

Atlas Stream Processing scales down a processor to the next lower tier when the processor's CPU and memory usage remain below a scale-down threshold for more than two days. The scale-down threshold is the scale-up threshold of the next lower tier, minus a 10% buffer that prevents the processor from scaling back up immediately. This two-day stabilization period makes scaling down deliberately slow to prevent frequent scaling between tiers.

Atlas Stream Processing scales a processor down only when the next lower tier is greater than or equal to the configured minTier.

Tier Bounds: minTier and maxTier

While Atlas Stream Processing manages the scaling thresholds, you control the range of tiers a processor can scale between with two settings:

Setting	Description
`minTier`	The lowest tier the processor can scale down to. Guarantees a baseline level of resources and sets a cost floor.
`maxTier`	The highest tier the processor can scale up to. Caps resource consumption and cost, and prevents an anomalous spike from scaling the processor to an unnecessarily expensive tier.

If you don't specify minTier or maxTier when you enable autoscaling, Atlas Stream Processing uses the stream processing workspace configuration as the default:

If you don't specify minTier, Atlas Stream Processing uses the lower of the stream processing workspace default tier and the tier that you start the processor on. Using the lower value prevents an invalid configuration when the default tier is above the starting tier.
If you don't specify maxTier, Atlas Stream Processing uses the stream processing workspace maximum tier size. If the stream processing workspace has no maximum tier size, the processor returns an error and doesn't start.

Some pipeline features require a minimum tier. For example, processors that use failover processors require a minimum tier of SP10. Set minTier to at least the minimum tier that your processor's pipeline requires.

The following table shows how minTier and maxTier bound scaling actions:

Tier Configuration	Current Tier	Scale Action	Resulting Tier
`minTier: SP5`, `maxTier: SP30`	`SP10`	Scale up	`SP30`
`minTier: SP5`, `maxTier: SP30`	`SP30`	Scale up	Remains `SP30` (maximum reached)
`minTier: SP5`, `maxTier: SP30`	`SP10`	Scale down	`SP5`
`minTier: SP5`, `maxTier: SP30`	`SP5`	Scale down	Remains `SP5` (minimum reached)

Enable and Configure Autoscaling

You can enable, modify, and disable autoscaling for a stream processor with the autoscaling option on the sp.processor.start() or sp.processor.modify() method in mongosh. Atlas Stream Processing persists the autoscaling configuration, so a processor reuses its prior configuration if you stop and restart it without changes.

To enable autoscaling with the stream processing workspace default and maximum tiers as bounds, use the following syntax:

sp.processor.start({autoscaling: {enabled: true}})

To enable autoscaling with explicit tier bounds, specify minTier and maxTier:

sp.processor.start(
   {autoscaling: {enabled: true, minTier: "SP2", maxTier: "SP50"}}
)

To set the tier a processor starts on while allowing it to scale within a different range, specify tier with the autoscaling option:

sp.processor.start(
   {tier: "SP10", autoscaling: {enabled: true, minTier: "SP5", maxTier: "SP30"}}
)

To change the tier bounds of an existing processor, stop the processor, then modify the tier levels with the new values. You must stop a processor before you modify it. Atlas Stream Processing changes only the values that you provide:

sp.processor.modify(
   {autoscaling: {enabled: true, minTier: "SP2", maxTier: "SP30"}}
)

To disable autoscaling, stop the processor and set enabled to false:

sp.processor.modify({autoscaling: {enabled: false}})

When you disable autoscaling, Atlas Stream Processing pins the processor's effectiveTier to its tier baseline.

Additional Behavior

tier and effectiveTier

When autoscaling is enabled, Atlas Stream Processing tracks two tier values for a processor:

tier: The baseline tier that you set. Atlas Stream Processing doesn't change this value through autoscaling. It changes only when you set a new baseline, which takes effect the next time you start the processor.
effectiveTier: A read-only value that shows the tier the processor is actually running on. When autoscaling is enabled, Atlas Stream Processing adjusts effectiveTier within the range set by minTier and maxTier. When autoscaling is disabled, effectiveTier matches tier.

If you stop a processor after autoscaling changes its effectiveTier, Atlas Stream Processing restarts the processor on its last effectiveTier, not the tier you initially started it on. This behavior lets the processor resume its previous workload without waiting to autoscale again.

To view a processor's autoscaling configuration and current tier, use the sp.processor.stats() method. The output includes the tier baseline, the read-only effectiveTier, and an autoscaling object with minTier and maxTier:

sp.processor.stats()
{
  ok: 1,
  name: 'sampleProc',
  state: 'STARTED',
  tier: 'SP10',
  effectiveTier: 'SP10',
  autoscaling: { minTier: 'SP2', maxTier: 'SP50' },
  stats: {
    ...
  },
  ...
}

Tier Alignment

If you start a processor with a tier value outside the configured autoscaling range, either below minTier or above maxTier, the processor returns an error and doesn't start.

Resource Exhaustion at maxTier

If a processor exhausts its resources at the configured maxTier, Atlas Stream Processing behaves as follows:

Memory exhaustion: The processor fails with an out-of-memory error.
CPU exhaustion: The processor continues running.

If a processor reaches maxTier and can't keep up with its workload, consider optimizing your pipeline logic or increasing maxTier.

Monitoring Autoscaling Events

Atlas Stream Processing records each scale-up and scale-down event. Each record identifies the processor and stream processing workspace, whether the event is a scale-up or scale-down, the tiers the processor moved to and from, and the metric that triggered the event. To learn how to view scaling events and configure alerts, see Monitor Stream Processors.

Get Started

To learn how to create and manage the stream processors you enable autoscaling on, see Develop Stream Processors.

To choose an appropriate tier range for your workload, see the Tier Selection Guide.

Learn More

Back

Architecture

Stream Processor Windows