Command-line Interface¶
Program: faust
¶
The faust umbrella command hosts all command-line functionality
for Faust. Projects may add custom commands using the @app.command
decorator (see CLI Commands).
Options:
- -A, --app¶
Path of Faust application to use, or the name of a module.
- --quiet, --no-quiet, -q¶
Silence output to <stdout>/<stderr>.
- --debug, --no-debug¶
Enable debugging output, and the blocking detector.
- --workdir, -W¶
Working directory to change to after start.
- --datadir¶
Directory to keep application state.
- --json¶
Return output in machine-readable JSON format.
- --loop, -L¶
Event loop implementation to use:
aio
(default),eventlet
,uvloop
.
Why is examples/word_count.py
used as the program?
The convention for Faust projects is to define an entry point for
the Faust command using app.main()
- see app.main() – Start the faust command-line program.
to see how to do so.
For a standalone program such as examples/word_count.py
this
is accomplished by adding the following at the end of the file:
if __name__ == '__main__':
app.main()
For a project organized in modules (a package) you can add a
package/__main__.py
module:
# package/__main__.py
from package.app import app
app.main()
Or use setuptools entry points so that pip install myproj
installs
a command-line program.
Even if you don’t add an entry point you can always use the faust program by specifying the path to an app.
Either the name of a module having an app
attribute:
$ faust -A examples.word_count
or specifying the attribute directly:
$ faust -A examples.word_count:app
faust --version
- Show version information and exit.¶
Example:
$ python examples/word_count.py --version
word_count.py, version Faust 0.9.39
faust --help
- Show help and exit.¶
Example:
$ python examples/word_count.py --help
Usage: word_count.py [OPTIONS] COMMAND [ARGS]...
Faust command-line interface.
Options:
-L, --loop [aio|eventlet|uvloop]
Event loop implementation to use.
--json / --no-json Prefer data to be emitted in json format.
-D, --datadir DIRECTORY Directory to keep application state.
-W, --workdir DIRECTORY Working directory to change to after start.
--debug / --no-debug Enable debugging output, and the blocking
detector.
-q, --quiet / --no-quiet Silence output to <stdout>/<stderr>.
-A, --app TEXT Path of Faust application to use, or the
name of a module.
--version Show the version and exit.
--help Show this message and exit.
Commands:
agents List agents.
model Show model detail.
models List all available models as tabulated list.
reset Delete local table state.
send Send message to agent/topic.
tables List available tables.
worker Start ƒaust worker instance.
faust agents
- List agents defined in this application.¶
Example:
$ python examples/word_count.py agents
┌Agents──────────┬─────────────────────────────────────────────┬──────────────────────────────────────────┐
│ name │ topic │ help │
├────────────────┼─────────────────────────────────────────────┼──────────────────────────────────────────┤
│ @count_words │ word-counts-examples.word_count.count_words │ Count words from blog post article body. │
│ @shuffle_words │ posts │ <N/A> │
└────────────────┴─────────────────────────────────────────────┴──────────────────────────────────────────┘
JSON Output using --json
:
$ python examples/word_count.py --json agents
[{"name": "@count_words",
"topic": "word-counts-examples.word_count.count_words",
"help": "Count words from blog post article body."},
{"name": "@shuffle_words",
"topic": "posts",
"help": "<N/A>"}]
faust models
- List defined serialization models.¶
Example:
$ python examples/word_count.py models
┌Models┬───────┐
│ name │ help │
├──────┼───────┤
│ Word │ <N/A> │
└──────┴───────┘
JSON Output using --json
:
python examples/word_count.py --json models
[{"name": "Word", "help": "<N/A>"}]
faust model <name>
- List model fields by model name.¶
Example:
$ python examples/word_count.py model Word
┌Word───┬──────┬──────────┐
│ field │ type │ default* │
├───────┼──────┼──────────┤
│ word │ str │ * │
└───────┴──────┴──────────┘
JSON Output using --json
:
$ python examples/word_count.py --json model Word
[{"field": "word", "type": "str", "default*": "*"}]
faust reset
- Delete local table state.¶
Warning
This command will result in the destruction of the following files:
- The local database directories/files backing tables
(does not apply if an in-memory store like memory:// is used).
Note
This data is technically recoverable from the Kafka cluster (if intact), but it’ll take a long time to get the data back as you need to consume each changelog topic in total.
It’d be faster to copy the data from any standbys that happen to have the topic partitions you require.
Example:
$ python examples/word_count.py reset
faust send <topic/agent> <message_value>
- Send message.¶
Options:
- --key-type, -K¶
Name of model to serialize key into.
- --key-serializer¶
Override default serializer for key.
- --value-type, -V¶
Name of model to serialize value into.
- --value-serializer¶
Override default serializer for value.
- --key, -k¶
String value for key (use json if model).
- --partition¶
Specific partition to send to.
- --repeat, -r¶
Send message n times.
- --min-latency¶
Minimum delay between sending.
- --max-latency¶
Maximum delay between sending.
Examples:
Send to agent by name using @
prefix:
$ python examples/word_count.py send @word_count "foo"
Send to topic by name (no prefix):
$ python examples/word_count.py send mytopic "foo"
{"topic": "mytopic",
"partition": 2,
"topic_partition": ["mytopic", 2],
"offset": 0,
"timestamp": 1520974493620,
"timestamp_type": 0}
To get help:
$ python examples/word_count.py send --help
Usage: word_count.py send [OPTIONS] ENTITY [VALUE]
Send message to agent/topic.
Options:
-K, --key-type TEXT Name of model to serialize key into.
--key-serializer TEXT Override default serializer for key.
-V, --value-type TEXT Name of model to serialize value into.
--value-serializer TEXT Override default serializer for value.
-k, --key TEXT String value for key (use json if model).
--partition INTEGER Specific partition to send to.
-r, --repeat INTEGER Send message n times.
--min-latency FLOAT Minimum delay between sending.
--max-latency FLOAT Maximum delay between sending.
--help Show this message and exit.
faust tables
- List Tables (distributed K/V stores).¶
Example:
$ python examples/word_count.py tables
┌Tables───────┬───────────────────────────────────┐
│ name │ help │
├─────────────┼───────────────────────────────────┤
│ word_counts │ Keep count of words (str to int). │
└─────────────┴───────────────────────────────────┘
JSON Output using --json
:
$ python examples/word_count.py --json tables
[{"name": "word_counts", "help": "Keep count of words (str to int)."}]
faust worker
- Start Faust worker instance.¶
A “worker” starts a single instance of a Faust application.
Options:
- --logfile, -f¶
Path to logfile (default is <stderr>).
- --loglevel, -l¶
Logging level to use:
CRIT|ERROR|WARN|INFO|DEBUG
.
- --blocking-timeout¶
Blocking detector timeout (requires –debug).
- --without-web¶
Do not start embedded web server.
- --web-host, -h¶
Canonical host name for the web server.
- --web-port, -p¶
Port to run web server on (default is 6066).
- --web-bind, -b¶
Network mask to bind web server to (default is “0.0.0.0” - all interfaces).
- --console-port¶
When
faust --debug
is enabled this specifies the port to run the https://pypi.org/project/aiomonitor/ console on (default is 50101).
Examples:
$ python examples/word_count.py worker
┌ƒaµS† v1.0.0──────────────────────────────────────────┐
│ id │ word-counts │
│ transport │ kafka://localhost:9092 │
│ store │ rocksdb: │
│ web │ http://localhost:6066/ │
│ log │ -stderr- (warn) │
│ pid │ 46052 │
│ hostname │ grainstate.local │
│ platform │ CPython 3.6.4 (Darwin x86_64) │
│ drivers │ aiokafka=0.4.0 aiohttp=3.0.8 │
│ datadir │ /opt/devel/faust/word-counts-data │
│ appdir │ /opt/devel/faust/word-counts-data/v1 │
└───────────┴──────────────────────────────────────────┘
starting➢ 😊
To get more logging use -l info (or further -l debug):
$ python examples/word_count.py worker -l info
┌ƒaµS† v1.0.0──────────────────────────────────────────┐
│ id │ word-counts │
│ transport │ kafka://localhost:9092 │
│ store │ rocksdb: │
│ web │ http://localhost:6066/ │
│ log │ -stderr- (info) │
│ pid │ 46034 │
│ hostname │ grainstate.local │
│ platform │ CPython 3.6.4 (Darwin x86_64) │
│ drivers │ aiokafka=0.4.0 aiohttp=3.0.8 │
│ datadir │ /opt/devel/faust/word-counts-data │
│ appdir │ /opt/devel/faust/word-counts-data/v1 │
└───────────┴──────────────────────────────────────────┘
starting^[2018-03-13 13:41:39,269: INFO]: [^Worker]: Starting...
[2018-03-13 13:41:39,275: INFO]: [^-App]: Starting...
[2018-03-13 13:41:39,271: INFO]: [^--Web]: Starting...
[2018-03-13 13:41:39,272: INFO]: [^---ServerThread]: Starting...
[2018-03-13 13:41:39,273: INFO]: [^--Web]: Serving on http://localhost:6066/
[2018-03-13 13:41:39,275: INFO]: [^--Monitor]: Starting...
[2018-03-13 13:41:39,275: INFO]: [^--Producer]: Starting...
[2018-03-13 13:41:39,317: INFO]: [^--Consumer]: Starting...
[2018-03-13 13:41:39,325: INFO]: [^--LeaderAssignor]: Starting...
[2018-03-13 13:41:39,325: INFO]: [^--Producer]: Creating topic word-counts-__assignor-__leader
[2018-03-13 13:41:39,325: INFO]: [^--Producer]: Nodes: [0]
[2018-03-13 13:41:39,668: INFO]: [^--Producer]: Topic word-counts-__assignor-__leader created.
[2018-03-13 13:41:39,669: INFO]: [^--ReplyConsumer]: Starting...
[2018-03-13 13:41:39,669: INFO]: [^--Agent]: Starting...
[2018-03-13 13:41:39,673: INFO]: [^---OneForOneSupervisor]: Starting...
[2018-03-13 13:41:39,673: INFO]: [^---Agent*: examples.word_co[.]shuffle_words]: Starting...
[2018-03-13 13:41:39,673: INFO]: [^--Agent]: Starting...
[2018-03-13 13:41:39,674: INFO]: [^---OneForOneSupervisor]: Starting...
[2018-03-13 13:41:39,674: INFO]: [^---Agent*: examples.word_count.count_words]: Starting...
[2018-03-13 13:41:39,674: INFO]: [^--Conductor]: Starting...
[2018-03-13 13:41:39,674: INFO]: [^--TableManager]: Starting...
[2018-03-13 13:41:39,675: INFO]: [^--Stream: <(*)Topic: posts@0x10497e5f8>]: Starting...
[2018-03-13 13:41:39,675: INFO]: [^--Stream: <(*)Topic: wo...s@0x105f73b38>]: Starting...
[...]
To get help use faust worker --help
:
$ python examples/word_count.py worker --help
Usage: word_count.py worker [OPTIONS]
Start ƒaust worker instance.
Options:
-f, --logfile PATH Path to logfile (default is <stderr>).
-l, --loglevel [crit|error|warn|info|debug]
Logging level to use.
--blocking-timeout FLOAT Blocking detector timeout (requires
--debug).
-p, --web-port RANGE[1-65535] Port to run web server on.
-b, --web-bind TEXT
-h, --web-host TEXT Canonical host name for the web server.
--console-port RANGE[1-65535] (when --debug:) Port to run debugger console
on.
--help Show this message and exit.