Quick Start

This page walks you through a first session with KafkIO: add a cluster, connect to it, find a message on a topic and produce one of your own. Each step links to the page that covers it in full.

Before you begin

You need KafkIO installed (see Installation & Updates) and a Kafka cluster that your machine can reach, along with its bootstrap servers (one or more host:port addresses) and, if the cluster is secured, the credentials or certificates it expects. If you don't have a cluster to hand, run one locally in Docker first and come back.

The examples below use a local cluster called Storefront Dev with an orders topic. Use your own names and topics as you go.

1. Add a cluster

The first time you start KafkIO, the Kafka Clusters list on the left is empty.

1 2

1. Add Cluster in the toolbar (also File ▸ Add Cluster) is always there for adding more clusters later.
2. Add a cluster does the same, and shows while the list is empty.

Either one opens the Cluster Properties dialog on its Kafka General tab:

1 2 3 4 5 6

1. Name: any name you like. It's how the cluster appears in the list and on its tabs, so include the environment if you'll have several (for example Payments Prod).
2. Bootstrap servers: one or more brokers, separated by commas, for example kafka1.example.com:9092, kafka2.example.com:9092. This is Kafka's bootstrap.servers setting.
3. Color (optional): tick the box and pick a colour. KafkIO uses it for the cluster's icon, its tabs and the status bar, which makes it hard to mistake production for development.
4. Kafka Security: needed if the cluster uses SSL/TLS or SASL. The default is plaintext, with no security.
5. Test Connection tries the settings without saving them.
6. Save is available once the name and bootstrap servers are filled in.

1. Enter a name and the bootstrap servers

   Fill in 1 Name and 2 Bootstrap servers, and choose a colour if you want one.

2. Add security settings, if the cluster needs them

   On 4 Kafka Security, choose the security type (Plaintext, SSL, SASL plaintext or SASL SSL) and fill in what it asks for. For a managed service such as Confluent Cloud or Amazon MSK, Provider Recipes lists the settings to use; every option is in Security & Authentication. Schema Registry, Kafka Connect and ksqlDB can wait until later.

3. Test the connection

   Click 5 Test Connection. If KafkIO reaches the cluster you'll see Connection success; otherwise an error explains what went wrong. A timeout is the most common failure, and it's often misleading: it can mean the host or port is unreachable, but also that the broker ignored the request because the security settings don't match. The error dialog links to the Network Tool to tell the two apart, and Troubleshooting Connections goes through the usual causes.

4. Save

   Click 6 Save. The cluster appears in the Kafka Clusters list. Saving doesn't connect; that's the next step.

You can change these settings at any time with Edit Cluster (while the cluster is disconnected). Managing Cluster Configurations covers editing, duplicating and deleting clusters.

2. Connect and explore the Overview

To connect, double-click the cluster in the Kafka Clusters list, or select it and click Connect in the toolbar (or Cluster ▸ Connect). When it's connected, the status bar at the bottom says so and the cluster expands into its sections: Overview, Brokers, Topics, Consumers, Schema Registry, ACL, Kafka Connect and ksqlDB. Sections for services you haven't configured (here Schema Registry, Kafka Connect and ksqlDB) are greyed out.

Click Overview. The cluster opens in a tab of its own:

1 2 3 4 5

1. The connected cluster, in its colour. The signal icon at the right of the row also connects and disconnects it.
2. Its sections. Click one to open it in the cluster's tab.
3. The cluster at a glance: whether it's online, its Kafka version, how many brokers, topics and partitions it has, which broker is the active controller, and how many partitions are under-replicated (URP) or have all replicas in sync. A non-zero URP is the first thing to look into.
4. What's available to you on this cluster: whether Schema Registry, Kafka Connect and ksqlDB are configured, whether topics can be deleted, and whether you can view and edit ACLs.
5. Duplicate Tab opens this section in a second tab of the same cluster.

Below the cards, KafkIO Cluster Configuration shows the settings you saved, as JSON. Any passwords in them are shown as entered, so mind your screen when sharing it. Cluster Overview explains every card.

One cluster can have several tabs: click 5 Duplicate Tab now, and a Storefront Dev (Overview) tab keeps the Overview open while you use the first tab for topics. The KafkIO Workspace explains tabs, panes and the rest of the window.

3. Find a message in a topic

Go back to the first Storefront Dev tab and click Topics in the cluster's sections. The topics list appears on the right, with the number of messages in each.

1 2 3 4 5 6 7

1. The topic, selected in the topics list.
2. The topic's Messages tab.
3. Search type: where to read from. Newest is the default.
4. Search runs the search.
5. The messages found, one per row.
6. The selected message in full, with its key, headers and raw bytes on the other tabs.
7. The duplicated tab from step 2, still showing the Overview.

1. Open the topic's messages

   Select the topic 1 (type in Filter topics... if the list is long), then its 2 Messages tab.

2. Search

   Leave 3 Search type on Newest to get the most recent messages, or choose Oldest to start from the beginning, then click 4 Search. To look for something specific, type it in Text filter first: only messages whose key, value or headers contain it are listed.

3. Read a message

   Click a row in the results 5. The pane below 6 shows its value; JSON is formatted for you, and Display as switches to text, XML or hex.

A search reads at most 5,000 messages by default (Max page/poll size). The same form can also search from an offset or a point in time, in chosen partitions, or Stream Live to watch new messages arrive: see Searching Messages, Viewing Messages and, for Avro, Protobuf and other formats, Deserialization & Formats.

4. Produce a test message

With the topic selected, click Produce Message(s) (the envelope with a plus, at the top right of the Topics section), or right-click the topic in the list and choose it there.

1 2 3 4 5

1. Key: the message key, for example customer-42. Leave it empty if your topic doesn't use keys.
2. Message: the value, typed or pasted.
3. The serializers. String (raw) sends the text as it is, which suits JSON and plain text.
4. Produce Message sends it.
5. Where the last message went: its partition and offset, sizes and timestamp.

Type a key on 1 Key and a value on 2 Message, then click 4 Produce Message. The dialog stays open, so you can change the message and send again; Close it when you're done. Back on the Messages tab, search again (with the key in Text filter to go straight to it) and your message is there, at the partition and offset the dialog reported.

The same dialog adds headers, picks a partition, sends many messages at once with a delay between them, fills in ${…} variables to make each one unique, and saves templates for messages you send often: see Producing Messages.

No cluster? Run one locally

If you have Docker, a single-broker Kafka on your own machine is the safest place to try KafkIO. KafkIO includes a Docker Compose file for one: choose Tools ▸ Sample Docker Compose (also linked from the Kafka General tab of the cluster dialog).

1

1. Copy puts the whole file on the clipboard.

1. Save the file

   Click 1 Copy and paste the text into a new file called docker-compose.yml, in a folder of its own.

2. Start Kafka

   In a terminal in that folder, run:

   docker compose up -d

   This starts the latest apache/kafka image as a single node (broker and controller, in KRaft mode) in a container called broker, with port 9092 published on your machine. If something else already uses port 9092, stop it or change the port in the file (in both ports and KAFKA_ADVERTISED_LISTENERS).

3. Add it to KafkIO

   Add a cluster with bootstrap servers localhost:9092 and no security, and carry on from step 2. The cluster starts without topics: create one from the Topics section with Create Topic (see Creating Topics), then produce a few messages to it.

When you're finished, docker compose down in the same folder stops and removes the container, along with its data. If you run Kafka in Docker your own way, the notes at the top of the window are the part that matters: KafkIO, running on your machine, can only connect if Kafka listens on 0.0.0.0 inside the container and advertises an address your machine can resolve, such as localhost. See Sample Docker Compose for more.

Next steps

• Secure clusters and managed services: Security & Authentication and Provider Recipes.
• Schema Registry, Kafka Connect and ksqlDB: add them on their tabs of the cluster dialog (Schema Registry Connection, Kafka Connect Connections, ksqlDB Connections).
• More on topics: The Topics List, Streaming Messages Live and Dumping a Topic to a File.
• Consumer groups and lag: Consumers.
• Can't connect? Troubleshooting Connections.

Related

• Installation & Updates
• The KafkIO Workspace
• Managing Cluster Configurations
• Searching Messages
• Producing Messages