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