Franz:   mac  OS Client for Apache Kafka
1 Connections
1.1 Security
1.2 Workspaces
1.3 Topics
1.3.1 Information Tab
1.3.2 Records Table Tab
1.3.3 Records Table Scripting
1.3.4 Configuration Table Tab
1.4 Consumer Groups
2 Keyboard Shortcuts
3 Known Issues and Limitations
3.1 Compression
4 Scripting Reference
5 Credits
8.7.0.7

Franz: macOS Client for Apache Kafka

Bogdan Popa <bogdan@defn.io>

Franz is a native macOS client for Apache Kafka. It helps you manage your Kafka clusters, topics and consumer groups and it provides convenient functionality for monitoring the data being published to topics.

Franz is currently in beta and free during the beta period. Beta builds expire after 90 days, so be sure to update when new builds come out. Once out of Beta, you will be able to purchase a perpetual license for a small fee.

1 Connections

When you start Franz, you are presented with the Welcome Screen. From the Welcome Screen you can connect to servers you’ve previously used or create new connections.

You can access the Welcome Screen using the “Window” -> “Welcome to Franz” menu item or by pressing ⇧ ⌘ 1.

1.1 Security

Connection metadata is stored inside Franz’ internal metadata database, but passwords are stored in the macOS Keychain.

1.2 Workspaces

When you connect to a Kafka cluster, a Workspace Window is opened for that cluster. All operations within the workspace operate on the same connection. When you close a Workspace Window, all of its associated connections and interface objects are closed.

1.3 Topics

From the Workspace Window sidebar, you can select topics to view general information about them, to browse through their record data and publish new data, or to view their configuration.

You can publish new data on a topic by pressing the plus icon on the top right corner of the Workspace Window toolbar.

1.3.1 Information Tab

The Information tab (⌘ 1) displays general information about the selected topic.

1.3.2 Records Table Tab

The Records Table tab (⌘ 2) on a topic lets you stream live data being published on a topic or jump to any offset you like and paginate through the data manually.

When you open the Records Table tab on a topic, it immediately starts streaming new data into the table. You can stop this by pressing the “Toggle Live Mode” button on the bottom left corner of the table. You can configure how much data is requested from the topic on each fetch by click the “Options..” button in the bottom right, and you can manually load more data by pressing the “Load More Records...” button.

From the “Options..” popover, you can also reset the topic iterator to any offset you like.

You can right-click on any record with a non-null key to publish a tombstone for it. Additionally, you can drag and drop any non-null key or value from the table to any application that accepts files to export the dragged value. You can use the “Key Format” and “Value Format” options from the “Options...” popover to control what format the columns are exported as.

1.3.3 Records Table Scripting

You can control the values displayed in the Records Table by writing Lua scripts. With the Records Table for a topic selected, press the scripting button – located in the center bottom of the table – to bring up the scripting window. Using the scripting window, you can edit the transform function to control how data is presented in the Records Table.

To activate and deactivate a script, press the bolt icon in the scripting window toolbar or use the ⌘ R keyboard shortcut. After a script is activated, any changes made to the text of the script will cause it to be deactivated.

The record argument to the transform function is a Lua table with the following fields:

field

description

partition_id

the partition the record was published to

offset

the record’s offset as a non-negative integer

timestamp

the record’s timestamp in milliseconds since the UNIX epoch

key

the record’s key as a string or nil

value

the record’s value as a string or nil

You may modify any of these fields to control how the record is displayed in the Records Table. Changing the data types of these fields is prohibited and will lead to an error when data gets loaded.

Returning nil from the transform function will cause the record to be skipped in the Records Table. You can leverage this to, for example, filter messages by partition:

function script.transform(record)
  if record.partition_id ~= 2 then
    return nil
  end
  return record
end

Within the scripting environment, a json table is provided with functions for encoding and decoding JSON data. For example, the following script can be used to read the example property of the record’s JSON value:

local script = {}
 
function script.transform(record)
  record.value = json.decode(record.value).example
  return record
end
 
return script

See the Scripting Reference for a list of all the functionality available within the scripting environment.

1.3.4 Configuration Table Tab

The Configuration Table tab displays the selected topic’s configuration. Non-default values are presented in bold and sensitive values are hidden by default. You may reveal sensitive values by right clicking on them and pressing the “Reveal” context menu item.

1.4 Consumer Groups

When you select a consumer group from the Workspace Window sidebar, you are presented with the Consumer Offsets Table. There, you can see member assignments, offsets and lag as well as reset individual offsets by right-clicking any of the entries.

You may only reset offsets if the consumer group is in the empty state.

2 Keyboard Shortcuts

⇧ ⌘ 1 — Display the Welcome Screen.

⌘ 1 — With a broker or topic selected, switches to the Information tab.

⌘ 2 — With a topic selected, switches to the Records Table tab. With a broker or consumer group selected, switches to the Configuration tab.

⌘ 3 — With a topic selected, switches to the Configuration tab.

⌘ R — Within a Workspace Window, reloads the connection metadata. Within a Scripting Window, activates or deactivates the script.

3 Known Issues and Limitations

Franz is currently in Beta so you should expect minor issues and limitations to pop up. I do my best to resolve these issues when they appear, so please let me know when you run into them by emailing me at bogdan@defn.io with the topic “Franz Support”.

3.1 Compression

The only compression format currently supported is gzip. If you need support for any other format, please e-mail me and let me know.

4 Scripting Reference

json.decode(str)

table

Decodes the JSON data in str to a Lua table.

json.encode(t)

string

Encodes the Lua table t to JSON.

math.abs(n)

number

Returns the absolute value of n.

math.ceil(n)

number

Rounds n towards positive infinity.

math.floor(n)

number

Rounds n towards negative infinity.

math.min(n, ...)

number

Returns the smallest number amongst the given set.

math.max(n, ...)

number

Returns the largest number amongst the given set.

math.sqrt(n)

number

Returns the square root of n.

string.sub(str, i, j)

string

Returns a substring of str starting from i until j. The i argument defaults to 1 and the j argument defaults to the length of str.

5 Credits

Franz is built using the Racket programming language and distributes its runtime alongside the application. Racket is licensed under the MIT License.