kafka/docs/quickstart.html at 2.x · tvainika/kafka

Repository navigation

History

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

<!--

Licensed to the Apache Software Foundation (ASF) under one or more

contributor license agreements. See the NOTICE file distributed with

this work for additional information regarding copyright ownership.

The ASF licenses this file to You under the Apache License, Version 2.0

(the "License"); you may not use this file except in compliance with

the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software

distributed under the License is distributed on an "AS IS" BASIS,

WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the License for the specific language governing permissions and

limitations under the License.

-->

<p>

This tutorial assumes you are starting fresh and have no existing Kafka or ZooKeeper data.

Since Kafka console scripts are different for Unix-based and Windows platforms, on Windows platforms use <code>bin\windows\</code> instead of <code>bin/</code>, and change the script extension to <code>.bat</code>.

</p>

<h4><a id="quickstart_download" href="#quickstart_download">Step 1: Download the code</a></h4>

<a href="https://www.apache.org/dyn/closer.cgi?path=/kafka/{{fullDotVersion}}/kafka_{{scalaVersion}}-{{fullDotVersion}}.tgz" title="Kafka downloads">Download</a> the {{fullDotVersion}} release and un-tar it.

> tar -xzf kafka_{{scalaVersion}}-{{fullDotVersion}}.tgz

> cd kafka_{{scalaVersion}}-{{fullDotVersion}}

</pre>

<h4><a id="quickstart_startserver" href="#quickstart_startserver">Step 2: Start the server</a></h4>

<p>

Kafka uses <a href="https://zookeeper.apache.org/">ZooKeeper</a> so you need to first start a ZooKeeper server if you don't already have one. You can use the convenience script packaged with kafka to get a quick-and-dirty single-node ZooKeeper instance.

</p>

> bin/zookeeper-server-start.sh config/zookeeper.properties

[2013-04-22 15:01:37,495] INFO Reading configuration from: config/zookeeper.properties (org.apache.zookeeper.server.quorum.QuorumPeerConfig)

...

</pre>

<p>Now start the Kafka server:</p>

> bin/kafka-server-start.sh config/server.properties

[2013-04-22 15:01:47,028] INFO Verifying properties (kafka.utils.VerifiableProperties)

[2013-04-22 15:01:47,051] INFO Property socket.send.buffer.bytes is overridden to 1048576 (kafka.utils.VerifiableProperties)

...

</pre>

<h4><a id="quickstart_createtopic" href="#quickstart_createtopic">Step 3: Create a topic</a></h4>

<p>Let's create a topic named "test" with a single partition and only one replica:</p>

> bin/kafka-topics.sh --create --bootstrap-server localhost:9092 --replication-factor 1 --partitions 1 --topic test

</pre>

<p>We can now see that topic if we run the list topic command:</p>

> bin/kafka-topics.sh --list --bootstrap-server localhost:9092

test

</pre>

<p>Alternatively, instead of manually creating topics you can also configure your brokers to auto-create topics when a non-existent topic is published to.</p>

<h4><a id="quickstart_send" href="#quickstart_send">Step 4: Send some messages</a></h4>

<p>Kafka comes with a command line client that will take input from a file or from standard input and send it out as messages to the Kafka cluster. By default, each line will be sent as a separate message.</p>

<p>

Run the producer and then type a few messages into the console to send to the server.</p>

> bin/kafka-console-producer.sh --bootstrap-server localhost:9092 --topic test

This is a message

This is another message

</pre>

<h4><a id="quickstart_consume" href="#quickstart_consume">Step 5: Start a consumer</a></h4>

<p>Kafka also has a command line consu 8000 mer that will dump out messages to standard output.</p>

> bin/kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic test --from-beginning

This is a message

This is another message

</pre>

<p>

If you have each of the above commands running in a different terminal then you should now be able to type messages into the producer terminal and see them appear in the consumer terminal.

</p>

<p>

All of the command line tools have additional options; running the command with no arguments will display usage information documenting them in more detail.

</p>

<h4><a id="quickstart_multibroker" href="#quickstart_multibroker">Step 6: Setting up a multi-broker cluster</a></h4>

<p>So far we have been running against a single broker, but that's no fun. For Kafka, a single broker is just a cluster of size one, so nothing much changes other than starting a few more broker instances. But just to get feel for it, let's expand our cluster to three nodes (still all on our local machine).</p>

<p>

First we make a config file for each of the brokers (on Windows use the <code>copy</code> command instead):

</p>

> cp config/server.properties config/server-1.properties

> cp config/server.properties config/server-2.properties

</pre>

<p>

Now edit these new files and set the following properties:

</p>

config/server-1.properties:

broker.id=1

listeners=PLAINTEXT://:9093

log.dirs=/tmp/kafka-logs-1

config/server-2.properties:

broker.id=2

listeners=PLAINTEXT://:9094

log.dirs=/tmp/kafka-logs-2

</pre>

<p>The <code>broker.id</code> property is the unique and permanent name of each node in the cluster. We have to override the port and log directory only because we are running these all on the same machine and we want to keep the brokers from all trying to register on the same port or overwrite each other's data.</p>

<p>

We already have Zookeeper and our single node started, so we just need to start the two new nodes:

</p>

> bin/kafka-server-start.sh config/server-1.properties &

...

> bin/kafka-server-start.sh config/server-2.properties &

...

</pre>

<p>Now create a new topic with a replication factor of three:</p>

> bin/kafka-topics.sh --create --bootstrap-server localhost:9092 --replication-factor 3 --partitions 1 --topic my-replicated-topic

</pre>

<p>Okay but now that we have a cluster how can we know which broker is doing what? To see that run the "describe topics" command:</p>

> bin/kafka-topics.sh --describe --bootstrap-server localhost:9092 --topic my-replicated-topic

Topic:my-replicated-topic PartitionCount:1 ReplicationFactor:3 Configs:

Topic: my-replicated-topic Partition: 0 Leader: 1 Replicas: 1,2,0 Isr: 1,2,0

</pre>

<p>Here is an explanation of output. The first line gives a summary of all the partitions, each additional line gives information about one partition. Since we have only one partition for this topic there is only one line.</p>

<ul>

<li>"leader" is the node responsible for all reads and writes for the given partition. Each node will be the leader for a randomly selected portion of the partitions.

<li>"replicas" is the list of nodes that replicate the log for this partition regardless of whether they are the leader or even if they are currently alive.

<li>"isr" is the set of "in-sync" replicas. This is the subset of the replicas list that is currently alive and caught-up to the leader.

</ul>

<p>Note that in my example node 1 is the leader for the only partition of the topic.</p>

<p>

We can run the same command on the original topic we created to see where it is:

</p>

> bin/kafka-topics.sh --describe --bootstrap-server localhost:9092 --topic test

Topic:test PartitionCount:1 ReplicationFactor:1 Configs:

Topic: test Partition: 0 Leader: 0 Replicas: 0 Isr: 0

</pre>

<p>So there is no surprise there—the original topic has no replicas and is on server 0, the only server in our cluster when we created it.</p>

<p>

Let's publish a few messages to our new topic:

</p>

> bin/kafka-console-producer.sh --bootstrap-server localhost:9092 --topic my-replicated-topic

...

my test message 1

my test message 2

</pre>

<p>Now let's consume these messages:</p>

> bin/kafka-console-consumer.sh --bootstrap-server localhost:9092 --from-beginning --topic my-replicated-topic

...

my test message 1

my test message 2

</pre>

<p>Now let's test out fault-tolerance. Broker 1 was acting as the leader so let's kill it:</p>

> ps aux | grep server-1.properties

7564 ttys002 0:15.91 /System/Library/Frameworks/JavaVM.framework/Versions/1.8/Home/bin/java...

> kill -9 7564

</pre>

On Windows use:

> wmic process where "caption = 'java.exe' and commandline like '%server-1.properties%'" get processid

ProcessId

6016

> taskkill /pid 6016 /f

</pre>

<p>Leadership has switched to one of the followers and node 1 is no longer in the in-sync replica set:</p>

> bin/kafka-topics.sh --describe --bootstrap-server localhost:9092 --topic my-replicated-topic

Topic:my-replicated-topic PartitionCount:1 ReplicationFactor:3 Configs:

Topic: my-replicated-topic Partition: 0 Leader: 2 Replicas: 1,2,0 Isr: 2,0

</pre>

<p>But the messages are still available for consumption even though the leader that took the writes originally is down:</p>

8000

> bin/kafka-console-consumer.sh --bootstrap-server localhost:9092 --from-beginning --topic my-replicated-topic

...

my test message 1

my test message 2

</pre>

<h4><a id="quickstart_kafkaconnect" href="#quickstart_kafkaconnect">Step 7: Use Kafka Connect to import/export data</a></h4>

<p>Reading data from the console and writing it back to the console is a convenient place to start, but you'll probably want

to use data from other sources or export data from Kafka to other systems. For many systems, instead of writing custom

integration code you can use Kafka Connect to import or export data.</p>

<p>Kafka Connect is a tool included with Kafka that imports and exports data to Kafka. It is an extensible tool that runs

<i>connectors</i>, which implement the custom logic for interacting with an external system. In this quickstart we'll see

how to run Kafka Connect with simple connectors that import data from a file to a Kafka topic and export data from a

Kafka topic to a file.</p>

<p>First, we'll start by creating some seed data to test with:</p>

> echo -e "foo\nbar" > test.txt

</pre>

Or on Windows:

> echo foo> test.txt

> echo bar>> test.txt

</pre>

<p>Next, we'll start two connectors running in <i>standalone</i> mode, which means they run in a single, local, dedicated

process. We provide three configuration files as parameters. The first is always the configuration for the Kafka Connect

process, containing common configuration such as the Kafka brokers to connect to and the serialization format for data.

The remaining configuration files each specify a connector to create. These files include a unique connector name, the connector

class to instantiate, and any other configuration required by the connector.</p>

> bin/connect-standalone.sh config/connect-standalone.properties config/connect-file-source.properties config/connect-file-sink.properties

</pre>

<p>

These sample configuration files, included with Kafka, use the default local cluster configuration you started earlier

and create two connectors: the first is a source connector that reads lines from an input file and produces each to a Kafka topic

and the second is a sink connector that reads messages from a Kafka topic and produces each as a line in an output file.

</p>

<p>

During startup you'll see a number of log messages, including some indicating that the connectors are being instantiated.

Once the Kafka Connect process has started, the source connector should start reading lines from <code>test.txt</code> and

producing them to the topic <code>connect-test</code>, and the sink connector should start reading messages from the topic <code>connect-test</code>

and write them to the file <code>test.sink.txt</code>. We can verify the data has been delivered through the entire pipeline

by examining the contents of the output file:

</p>

> more test.sink.txt

foo

bar

</pre>

<p>

Note that the data is being stored in the Kafka topic <code>connect-test</code>, so we can also run a console consumer to see the

data in the topic (or use custom consumer code to process it):

</p>

> bin/kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic connect-test --from-beginning

{"schema":{"type":"string","optional":false},"payload":"foo"}

{"schema":{"type":"string","optional":false},"payload":"bar"}

...

</pre>

<p>The connectors continue to process data, so we can add data to the file and see it move through the pipeline:</p>

> echo Another line>> test.txt

</pre>

<p>You should see the line appear in the console consumer output and in the sink file.</p>

<h4><a id="quickstart_kafkastreams" href="#quickstart_kafkastreams">Step 8: Use Kafka Streams to process data</a></h4>

<p>

Kafka Streams is a client library for building mission-critical real-time applications and microservices,

where the input and/or output data is stored in Kafka clusters. Kafka Streams combines the simplicity of

writing and deploying standard Java and Scala applications on the client side with the benefits of Kafka's

server-side cluster technology to make these applications highly scalable, elastic, fault-tolerant, distributed,

and much more. This <a href="/{{version}}/documentation/streams/quickstart">quickstart example</a> will demonstrate how

to run a streaming application coded in this library.

</p>

</script>

FilesExpand file tree

quickstart.html

Latest commit

History

quickstart.html

File metadata and controls