> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# Atlas Stream Processing Vertical Autoscaling

Vertical autoscaling automatically adjusts the [tier](https://www.mongodb.com/docs/atlas/atlas-stream-processing/architecture.md#std-label-atlas-sp-architecture-tiers) 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:

1. Stop the processor

   Atlas Stream Processing stops the processor on its current tier.

2. Change the tier

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

3. Restart the processor

   Atlas Stream Processing restarts the processor on the new tier and resumes operation from the last committed [checkpoint](https://www.mongodb.com/docs/atlas/atlas-stream-processing/architecture.md#std-label-atlas-sp-checkpoints), 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.](https://www.mongodb.com/docs/atlas/atlas-stream-processing/autoscaling.md#std-label-atlas-sp-autoscaling-tier-bounds)

### 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.](https://www.mongodb.com/docs/atlas/atlas-stream-processing/autoscaling.md#std-label-atlas-sp-autoscaling-tier-bounds)

## 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](https://www.mongodb.com/docs/atlas/atlas-stream-processing/architecture.md#std-label-atlas-sp-architecture-tiers) 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](https://www.mongodb.com/docs/atlas/atlas-stream-processing/architecture.md#std-label-atlas-sp-architecture-failover) 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()`](https://www.mongodb.com/docs/manual/reference/method/sp.processor.start.md#mongodb-method-sp.processor.start) or [`sp.processor.modify()`](https://www.mongodb.com/docs/manual/reference/method/sp.processor.modify.md#mongodb-method-sp.processor.modify) method in [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.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:

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

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

```javascript
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:

```javascript
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:

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

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

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

When you disable autoscaling, Atlas Stream Processing pins the processor's [effectiveTier](https://www.mongodb.com/docs/atlas/atlas-stream-processing/autoscaling.md#std-label-atlas-sp-autoscaling-effective-tier) 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()`](https://www.mongodb.com/docs/manual/reference/method/sp.processor.stats.md#mongodb-method-sp.processor.stats) method. The output includes the `tier` baseline, the read-only `effectiveTier`, and an `autoscaling` object with `minTier` and `maxTier`:

```javascript
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.](https://www.mongodb.com/docs/atlas/atlas-stream-processing/monitoring.md#std-label-atlas-sp-monitoring)

## Get Started

To learn how to create and manage the stream processors you enable autoscaling on, see [Develop Stream Processors.](https://www.mongodb.com/docs/atlas/atlas-stream-processing/manage-stream-processor.md#std-label-atlas-sp-manage-processor)

To choose an appropriate tier range for your workload, see the [Tier Selection Guide.](https://www.mongodb.com/docs/atlas/atlas-stream-processing/tier-guide.md#std-label-atlas-sp-tier-guide)

## Learn More

- [Atlas Stream Processing Architecture](https://www.mongodb.com/docs/atlas/atlas-stream-processing/architecture.md#std-label-atlas-sp-architecture)

- [Atlas Stream Processing Tier Selection Guide](https://www.mongodb.com/docs/atlas/atlas-stream-processing/tier-guide.md#std-label-atlas-sp-tier-guide)

- [Monitor Stream Processors](https://www.mongodb.com/docs/atlas/atlas-stream-processing/monitoring.md#std-label-atlas-sp-monitoring)

- [Atlas Stream Processing Limitations](https://www.mongodb.com/docs/atlas/atlas-stream-processing/limitations.md#std-label-atlas-sp-limitations)