apache / apache/pulsar

Add --state filter flag to pulsar-admin functions list

Open
#25,235 7 comments 1 reaction 1 assignee Claimed by @onceMisery View on GitHub
type/enhancement
Dominant language
Java
Stars
15.3k
Forks
3.8k
Avg merge
1d 14h
Merged PRs (30d)
160

Description

### Search before reporting

- [x] I searched in the [issues](https://github.com/apache/pulsar/issues) and found nothing similar.

### Motivation

IMHO, it's kind of annoying that pulsar-admin functions list doesn't distinguish between running functions and stopped ones. If you have a namespace with a mix of active and stopped functions, there's no way to quickly see which ones are actually running without checking each one individually.
This bash one-liner solves that, but it shouldn't be necessary:

```
for function in $(pulsar-admin functions list --namespace $NAMESPACE --tenant $TENANT); do
echo $function
pulsar-admin functions status --namespace $NAMESPACE --tenant $TENANT --name $function | fgrep running
done
```

This is slow and noisy — it makes N+1 API calls just to answer "what's currently running?" It would be much more useful if functions list supported filtering by runtime state directly.

### Solution

Add optional filter flags to pulsar-admin functions list:

--state flag
Filter functions by their running state.

```
# Show only running functions
pulsar-admin functions list --tenant public --namespace default --state RUNNING

# Show only stopped functions
pulsar-admin functions list --tenant public --namespace default --state STOPPED
```
Accepted values: RUNNING, STOPPED (and potentially FAILED, UNKNOWN to cover all states returned by functions status).

--long / -l flag (optional, nice-to-have)
Show extended output with status inline, similar to ls -l:

```
NAME STATE INSTANCES
add-offset-function RUNNING 1/1
topic-filter-key STOPPED 0/1
my-dedup-function RUNNING 3/3
```

### Alternatives

### Benefit

Eliminates the N+1 API call pattern shown above
Makes it practical to monitor function health from scripts and CI/CD pipelines
Consistent with other pulsar-admin subcommands that support filtering (e.g., topics list)
Reduces operational friction for namespaces with many functions

### Compatibility
This is a purely additive change. Without any flags, functions list behaves exactly as it does today.

### Anything else?

_No response_

### Are you willing to submit a PR?

- [ ] I'm willing to submit a PR!

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.