0
# Flower
1

2
Web-based tool for monitoring and administrating Celery clusters with real-time task tracking and worker management. Flower provides comprehensive visibility into distributed task queues, enabling effective monitoring of worker status, task execution, and cluster operations through both REST API endpoints and a rich web interface.
3

4
## Package Information
5

6
- **Package Name**: flower
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install flower`
10
- **Version**: 2.0.1
11

12
## Core Imports
13

14
```python
15
from flower.command import flower
16
from flower.app import Flower
17
```
18

19
For Celery integration:
20

21
```python
22
from celery.bin.celery import main, celery
23
from flower.command import flower
24

25
# Add flower command to celery
26
celery.add_command(flower)
27
```
28

29
## Basic Usage
30

31
### Command Line Usage
32

33
Run Flower as a Celery command:
34

35
```bash
36
celery flower
37
```
38

39
With options:
40

41
```bash
42
celery flower --port=5555 --broker=redis://localhost:6379
43
```
44

45
### Programmatic Usage
46

47
```python
48
from flower.app import Flower
49
from flower.options import default_options
50
import celery
51

52
# Create Celery app
53
capp = celery.Celery('myapp', broker='redis://localhost:6379')
54

55
# Create Flower app
56
flower_app = Flower(capp=capp, options=default_options)
57

58
# Start monitoring
59
flower_app.start()
60
```
61

62
## Architecture
63

64
Flower follows a multi-layer architecture built on Tornado web framework:
65

66
- **Core Application**: Main Flower class managing the web server and Celery integration
67
- **Events System**: Real-time event monitoring with persistent storage and Prometheus metrics
68
- **Inspector**: Worker inspection and management using Celery's remote control commands
69
- **REST API Layer**: Complete API for programmatic access to cluster information and control
70
- **Web UI Layer**: Rich web interface for interactive monitoring and management
71
- **Broker Integration**: Multi-broker support (RabbitMQ, Redis, variants) for queue monitoring
72
- **Authentication**: Multiple authentication providers (Basic Auth, OAuth2 with various providers)
73

74
## Capabilities
75

76
### Application Management
77

78
Core application lifecycle management including server startup, configuration, and shutdown.
79

80
```python { .api }
81
class Flower(tornado.web.Application):
82
    def __init__(self, options=None, capp=None, events=None, io_loop=None, **kwargs): ...
83
    def start(self): ...
84
    def stop(self): ...
85
    def update_workers(self, workername=None): ...
86
    
87
    @property
88
    def transport(self): ...
89
    
90
    @property
91
    def workers(self): ...
92
```
93

94
[Application Management](./application.md)
95

96
### Command Line Interface
97

98
Command-line interface for starting and configuring Flower with extensive configuration options.
99

100
```python { .api }
101
@click.command(cls=CeleryCommand)
102
def flower(ctx, tornado_argv): ...
103

104
def apply_env_options(): ...
105
def apply_options(prog_name, argv): ...
106
def setup_logging(): ...
107
def extract_settings(): ...
108
```
109

110
[Command Line Interface](./command-line.md)
111

112
### Event Monitoring
113

114
Real-time event processing with persistent storage, state management, and Prometheus metrics collection.
115

116
```python { .api }
117
class Events(threading.Thread):
118
    def __init__(self, capp, io_loop, db=None, persistent=False, enable_events=False, **kwargs): ...
119
    def start(self): ...
120
    def stop(self): ...
121
    def run(self): ...
122
    def save_state(self): ...
123
    def on_enable_events(self): ...
124
    def on_event(self, event): ...
125

126
class PrometheusMetrics:
127
    events: Counter
128
    runtime: Histogram
129
    prefetch_time: Gauge
130
    worker_online: Gauge
131
```
132

133
[Event Monitoring](./events.md)
134

135
### Worker Management
136

137
Worker inspection, status monitoring, and remote control operations.
138

139
```python { .api }
140
class Inspector:
141
    def __init__(self, io_loop, capp, timeout): ...
142
    def inspect(self, workername=None): ...
143
    
144
    @property
145
    def workers(self): ...
146
    
147
    methods: List[str]  # Available inspection methods
148
```
149

150
[Worker Management](./workers.md)
151

152
### Task Management
153

154
Complete task lifecycle management including execution, monitoring, filtering, and control operations.
155

156
```python { .api }
157
def iter_tasks(events, limit=None, offset=None, type=None, worker=None, 
158
               state=None, sort_by=None, received_start=None, received_end=None,
159
               started_start=None, started_end=None, search=None): ...
160

161
def sort_tasks(tasks, sort_by): ...
162
def get_task_by_id(events, task_id): ...
163
def as_dict(task): ...
164
```
165

166
[Task Management](./tasks.md)
167

168
### REST API
169

170
Complete REST API providing programmatic access to all Flower functionality including worker control, task management, and monitoring.
171

172
```python { .api }
173
class BaseApiHandler(BaseHandler):
174
    def prepare(self): ...
175
    def write_error(self, status_code, **kwargs): ...
176
```
177

178
API Endpoints:
179
- Worker management: `/api/workers`, `/api/worker/*`
180
- Task operations: `/api/tasks`, `/api/task/*`
181
- Control operations: Worker and task control endpoints
182

183
[REST API](./rest-api.md)
184

185
### Web Interface
186

187
Web-based user interface providing interactive monitoring and management capabilities with authentication support.
188

189
```python { .api }
190
class BaseHandler(tornado.web.RequestHandler):
191
    def render(self, *args, **kwargs): ...
192
    def get_current_user(self): ...
193
    def get_argument(self, name, default=None, strip=True, type=str): ...
194
    def format_task(self, task): ...
195
    def get_active_queue_names(self): ...
196
    
197
    @property
198
    def capp(self): ...
199
```
200

201
[Web Interface](./web-interface.md)
202

203
### Authentication
204

205
Multiple authentication methods including Basic Auth and OAuth2 integration with various providers.
206

207
```python { .api }
208
def authenticate(pattern, email): ...
209
def validate_auth_option(pattern): ...
210

211
class GoogleAuth2LoginHandler: ...
212
class GithubLoginHandler: ...
213
class GitLabLoginHandler: ...
214
class OktaLoginHandler: ...
215
```
216

217
[Authentication](./authentication.md)
218

219
### Broker Integration
220

221
Multi-broker support for monitoring message queues across different broker types.
222

223
```python { .api }
224
class Broker:
225
    @staticmethod
226
    def queues(names): ...
227

228
class BrokerBase:
229
    def __init__(self, broker_url, *_, **__): ...
230
    def queues(self, names): ...
231

232
class RabbitMQ(BrokerBase): ...
233
class Redis(BrokerBase): ...
234
class RedisSsl(Redis): ...
235
class RedisSocket(Redis): ...
236
class RedisSentinel(Redis): ...
237
```
238

239
[Broker Integration](./broker.md)
240

241
### Utilities
242

243
Utility functions for search, template formatting, and general operations.
244

245
```python { .api }
246
def parse_search_terms(raw_search_value): ...
247
def satisfies_search_terms(task, search_terms): ...
248
def format_time(time, tz): ...
249
def humanize(obj, type, length): ...
250
def gen_cookie_secret(): ...
251
def abs_path(path): ...
252
def strtobool(val): ...
253
```
254

255
[Utilities](./utilities.md)
256

257
## Configuration Options
258

259
Flower provides extensive configuration through command-line options, environment variables, and configuration files. Key options include:
260

261
- **Server Configuration**: port, address, ssl_options
262
- **Authentication**: auth, basic_auth, oauth2 settings
263
- **Performance**: max_workers, max_tasks, inspect_timeout
264
- **Storage**: persistent, db, state_save_interval
265
- **Monitoring**: enable_events, broker_api
266

267
## Error Handling
268

269
Flower includes comprehensive error handling for:
270

271
- **Authentication Errors**: 401 responses for unauthorized access
272
- **Task Errors**: Proper handling of task failures and timeouts
273
- **Broker Connection Errors**: Graceful handling of broker connectivity issues
274
- **Configuration Errors**: Validation and reporting of configuration problems
275

276
## Types
277

278
```python { .api }
279
# Configuration types
280
OptionsNamespace = tornado.options.OptionParser
281

282
# Event types (from Celery)
283
TaskEvent = Dict[str, Any]
284
WorkerEvent = Dict[str, Any]
285

286
# Task state types
287
TaskState = Literal['PENDING', 'STARTED', 'SUCCESS', 'FAILURE', 'RETRY', 'REVOKED']
288

289
# Authentication types
290
AuthProvider = Literal['google', 'github', 'gitlab', 'okta']
291
```