Getting Started (1.x)

Setting up Turbine is fairly easy. Turbine is setup to work directly with Hystrix. It can be used independently as well but requires some setup. Refer to the simple procedure below for getting up and running with Turbine.

Steps

Get a Hystrix server up and running

Use the Hystrix Getting Started Guide in case you don't already have a server running Hystrix.

Note that when Turbine starts, it requires your Hystrix enabled servers to be up and running. If they aren't it will just try to re-connect to your servers and you will not get any data.

Once this is done, you need to know what your hystrix server connection url is Example

http://my-hystrix-enabled-server-hostname:7080/hystrix.stream

You must curl this url and you should see a continuous stream of hystrix data to your console. If you see this, then your hystrix server is ready to integrate with Turbine, CTRL+C and stop the stream.

Get Turbine installed

Get the binaries

Turbine ships as a library (jar) and a web-app (war) as well. You can directly fetch the artifacts from Maven Central Repo.

Want to use Turbine's web-app directly?

In case you don't have your own web-app, then you can just pull in turbine's war from Maven and run it within a Tomcat container installation. Once you do this, skip directly to the next step Configure Turbine*

Using your own web-app?

If you have your own web-app, then follow this procedure once you have pulled in the turbine-core jar and all it's dependencies.

web.xml

Update your web.xml to include the Turbine servlet that it ships with. This is the endpoint to connect to for getting the aggregate stream.

  <servlet>
    <description></description>
    <display-name>TurbineStreamServlet</display-name>
    <servlet-name>TurbineStreamServlet</servlet-name>
    <servlet-class>com.netflix.turbine.streaming.servlet.TurbineStreamServlet</servlet-class>
  </servlet>
  
  <servlet-mapping>
    <servlet-name>TurbineStreamServlet</servlet-name>
    <url-pattern>/turbine.stream</url-pattern>
  </servlet-mapping>

Init Turbine

You need to init the Turbine Aggregator to start monitoring your servers. Note that your servers must be up and running for you to do this. Inject this code into the class that is called when your server starts.

TurbineInit.init();

Configure Turbine

Once your Turbine server is ready to go, you will need to configure Turbine and it uses Archaius for it's configuration mechanism. You can use their Getting Started Guide, but early integration is really simple if you are not using them already. By default Archaius looks for a file called config.properties on the classpath. Just add this file to the classpath and edit it's contents to be like so

Step 1. Tell Turbine what clusters you will be monitoring

The config property with an example is

turbine.aggregator.clusterConfig=myFirstHystrixCluster

For more details see the Turbine cluster config section

Step 2. Next tell Turbine how to connect to each of your servers

Assuming your hystrix connection url is something like this

http://{hystrix-enabled-app-hostname}:7080/myHystrixEnabledService/hystrix.stream

Your connection url config will look like

turbine.instanceUrlSuffix=:7080/myHystrixEnabledService/hystrix.stream

You can also have different connection paths to different services for different clusters. For more details see the url connection config section

Step 3. Tell Turbine what hosts belong to your cluster(s)

The InstanceDiscovery component gives Turbine the list of your servers. You need to provide an impl for InstanceDiscovery. Turbine ships with a few simple implementations

• Pure config giving the instance list
• Instance list from a file
• Instance list from Eureka

For more details see InstanceDiscovery config section for how to do this.

Start Turbine

Now start your webapp and you should see some helpful logging from Turbine similar to this ...

2012-12-05 14:45:20 INFO  com.netflix.turbine.discovery.InstanceObservable$1:260 [InstanceObservable$1] [run]: Rertieved hosts from InstanceDiscovery: 0
2012-12-05 14:45:20 INFO  com.netflix.turbine.discovery.InstanceObservable$1:272 [InstanceObservable$1] [run]: Found hosts that have been previously terminated: 0
2012-12-05 14:45:20 INFO  com.netflix.turbine.discovery.InstanceObservable$1:289 [InstanceObservable$1] [run]: Hosts up:1, hosts down: 0
Dec 5, 2012 2:45:20 PM org.apache.coyote.http11.Http11Protocol start
INFO: Starting Coyote HTTP/1.1 on http-8080
Dec 5, 2012 2:45:20 PM org.apache.coyote.http11.Http11Protocol start
INFO: Starting Coyote HTTP/1.1 on http-8443
Dec 5, 2012 2:45:20 PM org.apache.jk.common.ChannelSocket init
INFO: JK: ajp13 listening on /0.0.0.0:8009
Dec 5, 2012 2:45:20 PM org.apache.jk.server.JkMain start
INFO: Jk running ID=0 time=0/22  config=null
Dec 5, 2012 2:45:20 PM org.apache.catalina.startup.Catalina start
INFO: Server startup in 874 ms

You will be able to see InstanceObservable discovering your instances and then Turbine will init a connection to your hosts.

Connect to Turbine

Now connect with Turbine and you should see the aggregate output similar to what is shown below. Note that Turbine needs to know what cluster metrics you want, and you can have multiple clusters being monitored simultaneously. Hence you must provide the cluster name. If you don't have one, then you should use the name default, but you need to ensure that the rest of your config (for instances, and connection url path et all) is all setup to work with default

curl "http://localhost:8080/turbine.stream?cluster=weather-svc-prod" 

Sample output

:ping

:ping 

data: {"threadActiveCount":5,"queueSize":25,"totalTaskCount":717919087, "completedTaskCount":717919056,
"type":"DependencyCommandThreadPool","reportingHosts":521,"currentTime":4600489157131,
"maxActiveThreadsInRollingCounter":1125,"largestPoolSize":5190,"rollingThreadExecutions":209774,
"name":"DTS","threadExecutions":717917140}

data: {"threadActiveCount":5,"queueSize":25,"totalTaskCount":717919087, "completedTaskCount":717919056,
"type":"DependencyCommandThreadPool","reportingHosts":521,"currentTime":4600489157131,
"maxActiveThreadsInRollingCounter":1125,"largestPoolSize":5190,"rollingThreadExecutions":209774,
"name":"DTS","threadExecutions":717917140}

data: {"threadActiveCount":5,"queueSize":25,"totalTaskCount":717919087, "completedTaskCount":717919056,
"type":"DependencyCommandThreadPool","reportingHosts":521,"currentTime":4600489157131,
"maxActiveThreadsInRollingCounter":1125,"largestPoolSize":5190,"rollingThreadExecutions":209774,
"name":"DTS","threadExecutions":717917140}