Quick Start

Hello World

Application

The first thing you need to get up and running with Faust is to define an application.

The application (or app for short) configures your project and implements common functionality. We also define a topic description, and an agent to process messages in that topic.

Lets create the file hello_world.py:

import faust

app = faust.App(
    'hello-world',
    broker='kafka://localhost:9092',
    value_serializer='raw',
)

greetings_topic = app.topic('greetings')

@app.agent(greetings_topic)
async def greet(greetings):
    async for greeting in greetings:
        print(greeting)

In this tutorial, we keep everything in a single module, but for larger projects, you can create a dedicated package with a submodule layout.

The first argument passed to the app is the id of the application, needed for internal bookkeeping and to distribute work among worker instances.

By default Faust will use JSON serialization, so we specify value_serializer here as raw to avoid deserializing incoming greetings. For real applications you should define models (see Models, Serialization, and Codecs).

Here you defined a Kafka topic greetings and then an agent that iterates over the messages in the topic and prints each one of them.

Note

The application id setting (i.e. 'hello-world' in the example above), should be unique per Faust app in your Kafka cluster.

Starting Kafka

Before running your app, you need to start Zookeeper and Kafka.

Start Zookeeper first:

$ $KAFKA_HOME/bin/zookeeper-server-start $KAFKA_HOME/etc/kafka/zookeeper.properties

Then start Kafka:

$ $KAFKA_HOME/bin/kafka-server-start $KAFKA_HOME/etc/kafka/server.properties

Running the Faust worker

Now that you have created a simple Faust application and have Kafka and Zookeeper running, you need to run a worker instance for the application.

Start a worker:

$ faust -A hello_world worker -l info

Multiple instances of a Faust worker can be started independently to distribute stream processing across machines and CPU cores.

In production, you’ll want to run the worker in the background as a daemon. Use the tools provided by your platform, or use something like supervisord.

Use --help to get a complete listing of available command-line options:

$ faust worker --help

Seeing things in Action

At this point, you have an application running, but not much is happening. You need to feed data into the Kafka topic to see Faust print the greetings as it processes the stream, and right now that topic is probably empty.

Let’s use the faust send command to push some messages into the greetings topic:

$ faust -A hello_world send @greet "Hello Faust"

The above command sends a message to the greet agent by using the @ prefix. If you don’t use the prefix, it will be treated as the name of a topic:

$ faust -A hello_world send greetings "Hello Kafka topic"

After sending the messages, you can see your worker start processing them and print the greetings to the console.

Where to go from here…

Now that you have seen a simple Faust application in action, you should dive into the other sections of the User Guide or jump right into the Playbooks for tutorials and solutions to common patterns.