SAMZA-1478: Delete unneeded data from intermediate Kafka topic on offset commit
[samza.git] / README.md
1 ## What is Samza?  [![Build Status](https://travis-ci.org/apache/samza.svg?branch=master)](https://travis-ci.org/apache/samza)
2
3 [Apache Samza](http://samza.apache.org/) is a distributed stream processing framework. It uses [Apache Kafka](http://kafka.apache.org) for messaging, and [Apache Hadoop YARN](http://hadoop.apache.org/docs/current/hadoop-yarn/hadoop-yarn-site/YARN.html) to provide fault tolerance, processor isolation, security, and resource management.
4
5 Samza's key features include:
6
7 * **Simple API:** Unlike most low-level messaging system APIs, Samza provides a very simple callback-based "process message" API comparable to MapReduce.
8 * **Managed state:** Samza manages snapshotting and restoration of a stream processor's state. When the processor is restarted, Samza restores its state to a consistent snapshot. Samza is built to handle large amounts of state (many gigabytes per partition).
9 * **Fault tolerance:** Whenever a machine in the cluster fails, Samza works with YARN to transparently migrate your tasks to another machine.
10 * **Durability:** Samza uses Kafka to guarantee that messages are processed in the order they were written to a partition, and that no messages are ever lost.
11 * **Scalability:** Samza is partitioned and distributed at every level. Kafka provides ordered, partitioned, replayable, fault-tolerant streams. YARN provides a distributed environment for Samza containers to run in.
12 * **Pluggable:** Though Samza works out of the box with Kafka and YARN, Samza provides a pluggable API that lets you run Samza with other messaging systems and execution environments.
13 * **Processor isolation:** Samza works with Apache YARN, which supports Hadoop's security model, and resource isolation through Linux CGroups.
14
15 Check out [Hello Samza](https://samza.apache.org/startup/hello-samza/latest/) to try Samza. Read the [Background](https://samza.apache.org/learn/documentation/latest/introduction/background.html) page to learn more about Samza.
16
17 ### Building Samza
18
19 To build Samza from a git checkout, run:
20
21     ./gradlew clean build
22
23 To build Samza from a source release, it is first necessary to download the gradle wrapper script above. This bootstrapping process requires Gradle to be installed on the source machine.  Gradle is available through most package managers or directly from [its website](http://www.gradle.org/).  To bootstrap the wrapper, run:
24
25     gradle -b bootstrap.gradle
26
27 After the bootstrap script has completed, the regular gradlew instructions below are available.
28
29 #### Scala and YARN
30
31 Samza builds with [Scala](http://www.scala-lang.org/) 2.10 or 2.11 and [YARN](http://hadoop.apache.org/docs/current/hadoop-yarn/hadoop-yarn-site/YARN.html) 2.6.1, by default. Use the -PscalaVersion switches to change Scala versions. Samza supports building Scala with 2.10 and 2.11.
32
33     ./gradlew -PscalaVersion=2.11 clean build
34
35 ### Testing Samza
36
37 To run all tests:
38
39     ./gradlew clean test
40
41 To run a single test:
42
43     ./gradlew clean :samza-test:test -Dtest.single=TestStatefulTask
44
45 To run key-value performance tests:
46
47     ./gradlew samza-shell:kvPerformanceTest -PconfigPath=file://$PWD/samza-test/src/main/config/perf/kv-perf.properties
48
49 To run all integration tests:
50
51     ./bin/integration-tests.sh <dir>
52
53 ### Running checkstyle on the java code ###
54
55     ./gradlew checkstyleMain checkstyleTest
56
57 ### Job Management
58
59 To run a job (defined in a properties file):
60
61     ./gradlew samza-shell:runJob -PconfigPath=file:///path/to/job/config.properties
62
63 To inspect a job's latest checkpoint:
64
65     ./gradlew samza-shell:checkpointTool -PconfigPath=file:///path/to/job/config.properties
66
67 To modify a job's checkpoint (assumes that the job is not currently running), give it a file with the new offset for each partition, in the format `systems.<system>.streams.<topic>.partitions.<partition>=<offset>`:
68
69     ./gradlew samza-shell:checkpointTool -PconfigPath=file:///path/to/job/config.properties \
70         -PnewOffsets=file:///path/to/new/offsets.properties
71
72 ### Developers
73
74 To get Eclipse projects, run:
75
76     ./gradlew eclipse
77
78 For IntelliJ, run:
79
80     ./gradlew idea
81
82 ### Contribution
83
84 To start contributing on Samza please read [Rules](http://samza.apache.org/contribute/rules.html) and [Contributor Corner](https://cwiki.apache.org/confluence/display/SAMZA/Contributor%27s+Corner). Notice that **Samza git repository does not support git pull request**.
85
86 ### Apache Software Foundation
87
88 Apache Samza is a top level project of the [Apache Software Foundation](http://www.apache.org/).
89
90 ![Apache Software Foundation Logo](http://www.apache.org/images/feather.gif)