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:

1. 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.