No mention of "active slots" setting in Global Concurrency Limits section of documentation

[tristanchambers-bids]

First check

• [X] I added a descriptive title to this issue.
• [X] I used GitHub search to find a similar request and didn't find it 😇

Describe the issue

The Add Concurrency Limit dialog box has a setting called "Active Slots". But this setting is not explained in the documentation, nor is there a tooltip to explain the effect of this setting. The docs list all of the other settings on this dialog box:

Name: The name of the concurrency limit. This name is also how you'll reference the concurrency limit in your code. Special characters, such as /, %, &, >, <, are not allowed.
Concurrency Limit: The maximum number of slots that can be occupied on this concurrency limit.
Slot Decay Per Second: Controls the rate at which slots are released when the concurrency limit is used as a rate limit. This value must be configured when using the rate_limit function.
Active: Whether or not the concurrency limit is in an active state.

Describe the proposed change

Add a line to the list of settings explaining the effect of this setting.

Additional context

I'd like to get my concurrency limits set up, but I'm not confident that I'm doing it right without understanding this setting.

[serinamarie]

Hi, @tristanchambers-bids, we have a section in the documentation for this-- were you able to locate this guide?

[jeffrose-relay]

@serinamarie I am struggling with this too. This guide you linked does not mention the Active Slots field or what it means. I have even looked in the source code but there is nothing helpful there either.

[tristanchambers-bids]

Hi @serinamarie yes those are the docs I was referring to in my issue description. I updated to clarify. This page has no mention of the words "Active Slots".

[tristanchambers-bids]

For those who are scratching their head like me, I discovered today that "Active Slots" is not a parameter that you set. It is in fact a variable which keeps track of how many slots are currently claimed. The system increments and decrements the value when each task is added and completed (respectively). Why is this a user editable value you may ask? Well it turns out that when you cancel a job, the system does not decrement the active slots value for any tasks that were killed. So after you cancel a job you should check this value and set it to zero if there were any killed tasks that did not complete!

[frantakalab]

@tristanchambers-bids isn't this a bug? It just happened to me and tbh I am super confused about this behavior.

[abrookins]

99% of the time, this field is only useful on the update form when editing an existing limit. It doesn't make a lot of sense to ask for "active slots" when you're just creating the limit, so I've hidden the limit on the create form in https://github.com/PrefectHQ/prefect-ui-library/pull/2674.

I'll also update the docs to explain what this field means because there are cases where editing it can be useful, e.g. just as you posted, the limits don't correctly decrement for some reason.

@tristanchambers-bids That said, global concurrency limits should decrement their active slots in most cases, even most types of crashes, so if you're having to manually edit the active slots count after canceling flow and task runs, that sounds like a bug. Are you using Prefect 2 or 3? The docs, etc., look like 2, but just wanted to confirm.

[cicdw]

Going to close this issue as the core element has been addressed above. If there are any slot-related bugs though, please feel free to open a new issue!

[yesheneve]

@abrookins When I cancel a task, that task is stuck in cancelling status and never goes to canceled status. Also the active slots do not decrement automatically. Here is the prefect version that I am using

Version:             3.2.12
API version:         0.8.4
Python version:      3.11.11
Git commit:          826eb1a7
Built:               Mon, Mar 10, 2025 4:36 PM
OS/Arch:             linux/x86_64
Profile:             ephemeral
Server type:         ephemeral
Pydantic version:    2.10.6
Server:
  Database:          AWS RDS Postgres
  Postgres version:  16.4
Integrations:
  prefect-aws:       0.5.5

[cicdw]

I think it would be best if you could open a new issue with a reproducible example for us to work from @yesheneve - thank you!