[ Get-Started | Features | Use Cases | Motivation | Demos | Performance | Compare | About | 中文介绍 ]

[ API Overview | Generate & Submit Task | Track Status & Examine Responses | Configurations ]

Parallec is a fast parallel async HTTP(S)/SSH/TCP/Ping client java library. Scalably aggregate and handle API responses anyway and send it anywhere by writing 20 lines of code. A special super convenient response context let you pass in/out any object when handling the responses. Now you can conduct scalable API calls, then effortlessly pass aggregated data anywhere to elastic search, kafka, MongoDB, graphite, memcached, etc. Parallec means Parallel Client, and is pronounced as "Para-like".

Donwload the latest JAR or grab from Maven:

<dependency>
	<groupId>io.parallec</groupId>
	<artifactId>parallec-core</artifactId>
	<version>0.9.0</version>
</dependency>

or Gradle:

compile 'io.parallec:parallec-core:0.9.0'

6 Line Example

In the example below, simply changing prepareHttpGet() to prepareSsh(), prepareTcp(), preparePing() enables you to conduct parallel SSH/TCP/Ping. Details please refer to the Java Doc and Example Code.

import io.parallec.core.*;
import java.util.Map;

ParallelClient pc = new ParallelClient(); 
pc.prepareHttpGet("").setTargetHostsFromString("www.google.com www.ebay.com www.yahoo.com")
.execute(new ParallecResponseHandler() {
    public void onCompleted(ResponseOnSingleTask res,
        Map<String, Object> responseContext) {
        System.out.println( res.toString() );  }
});

20 Line Example

Now that you have learned the basics, check out how easy to pass an elastic search client using the convenient response context to aggregate data anywhere you like.

ParallelClient pc = new ParallelClient();
org.elasticsearch.node.Node node = nodeBuilder().node(); //elastic client initialize
HashMap<String, Object> responseContext = new HashMap<String, Object>();
responseContext.put("Client", node.client());
pc.prepareHttpGet("")
        .setConcurrency(1000).setResponseContext(responseContext)
        .setTargetHostsFromLineByLineText("http://www.parallec.io/userdata/sample_target_hosts_top100_old.txt", HostsSourceType.URL)
        .execute( new ParallecResponseHandler() {
            public void onCompleted(ResponseOnSingleTask res,
                    Map<String, Object> responseContext) {
                Map<String, Object> metricMap = new HashMap<String, Object>();
                metricMap.put("StatusCode", res.getStatusCode().replaceAll(" ", "_"));
                metricMap.put("LastUpdated",PcDateUtils.getNowDateTimeStrStandard());
                metricMap.put("NodeGroupType", "Web100");
                Client client = (Client) responseContext.get("Client");
                client.prepareIndex("local", "parallec", res.getHost()).setSource(metricMap).execute();
            }
        });
node.close(); pc.releaseExternalResources();

Different Requests to the Same Target

Now see how easy to use the request template to send multiple different requests to the same target. Read more..

pc.prepareHttpGet("/userdata/sample_weather_$ZIP.txt")
    .setReplaceVarMapToSingleTargetSingleVar("ZIP",
        Arrays.asList("95037","48824"), "www.parallec.io")
    .execute(new ParallecResponseHandler() {...}...

• http://www.parallec.io/userdata/sample_weather_48824.txt
• http://www.parallec.io/userdata/sample_weather_95037.txt

###More Readings

• More Examples on setting context, send to elastic search, async running, auto progress polling, track progress, TCP/SSH/Ping.
• Set Target Hosts from list, string, line by line text, json path, from local or remote URLs.
• Full Documentation
• Javadoc
• Ping Demo Ping 8000 Servers within 11.1 Seconds, performance test vs. FPing.

###Use Cases

1. Scalable web server monitoring, management, and configuration push, ping check.
2. Asset / server status discovery, remote task execution in agent-less(parallel SSH) or agent based (parallel HTTP/TCP) method.
3. Scalable API aggregation and processing with flexible destination with your favorate message queue / storage / alert engine.
4. Orchestration and work flows on multiple web servers.
5. Parallel different requests with controlled concurrency to a single server.

Parallec is built on Akka actors and Async HTTP Client / Netty / Jsch. The library focuses on HTTP while also enables scalable communication over SSH/Ping/TCP.

90%+ Test coverage assures you always find an example of each of feature.

1. Exceedingly intuitive interface with builder pattern similar to that in Async HTTP Client, but handles concurrency behind the scenes.
2. Generic response handler with context. Special response context enables total freedom and convenience of processing each response your way. Process and aggregate data anywhere to Kafka, Redis, Elastic Search, mongoDB, CMS and etc.
3. Flexible on when to invoke the handler: before (in worker thread) or after the aggregation (in master/manager thread).
4. Flexible Input of target hosts: Input target hosts from a list, string, JSON Path from local files or a remote URL
5. Scalable and fast, infinitely scalable with built-in Concurrency control.
6. Auto-progress polling to enable task level concurrency with Async API for long jobs and orchestrations.
7. Request template to handle non-uniform requests.
8. Convenient single place handling success and failure cases. Handle in a single function where you can get the response including the actual response if success; or stacktrace and error details if failures.
9. Capacity aware task scheduler helps you to auto queue up and fire tasks when capacity is insufficient. (e.g. submit consecutively 5 tasks each hitting 100K websites with default concurrency will result in a queue up)
10. Fine-grained task progress tracking helps you track the the progress each individual task status. Of a parallel task on 1000 target hosts, you may check status on any single host task, and percentage progress on how many are completed.
11. Fine-grained task cancelation on whole/individual request level. Of a parallel task on 1000 target hosts, you may cancel a subset of target hosts or cancel the whole parallel task anytime.
12. Status-code-aggregation is provided out of the box.
13. Parallel Ping supports both InetAddress.reachable ICMP (requires root) and Process based ping with retries. Performance testing shows it is ** 2x the speed of** than best-effort tuned FPing on pinging on 1500 targets. (2.2 vs 4.5 sec)
14. Parallel SSH supports both key and password based login and task cancellation.
15. Parallel TCP supports idle timeout based channel closes.

##Motivation

• Flexible response handling and immediate processing embedded in other applications.
• Handle async APIs with auto progress polling for task level concurrency control.
• Support of other protocols, and more..

With the feedbacks, lessons, and improvements from the past year of internal usage and open source of REST Commander, we now made the core of REST Commander as an easy to use standalone library. We added 15+ new features, rewritten 70%+ of the code, with 90%+ test coverage for confident usage and contribution. This time we also structure it better so that most internal development can be directly made here.

[Watch Demo](https://www.youtube.com/watch?v=QcavegPMDms"Parallec demo - Click to Watch!"): Parallec Aggregates 100 websites status to elastic search and visualized with 20 lines of code.

[Watch Ping Demo](https://www.youtube.com/watch?v=9m1TFuO1Mys"Parallec Ping vs FPing demo - Click to Watch!"): Parallec is 2x Speed of best-efforted tuned FPing with same accurate results and pings 8000 servers within 11.1 seconds, details check here.

Note that speed varies based on network speed, API response time, the slowest servers, and concurrency settings.

#####HTTP

We conducted remote task execution API on 3,000 servers with response aggregated to elastic search, visualized within 15 seconds, by writing 25 lines of code.

With another faster API, calls to 8,000 servers in the same datacenter with response aggregated in memory in 12 seconds.

#####Ping Parallec 2.2 seconds vs FPing 4.5 seconds on 1500 servers. Parallec is 2x the speed of FPing (after best-effort tuning : -i 1 -r 0 v3.12) of pinging 1500 servers while getting the same ping results. Parallec pings 8000 servers within 11.1 seconds with breeze.

As usual, don't rely on these numbers and perform your own benchmarks.

• Compared with java thread pool based solution, parallec gives you worry free concurrency control without constraints on thread size.
• Compared with single-threaded Node.js solutions, Parallec enables parallel computation-intensive response handling with multiple-cores.
• Similar issues with Python's global interpreter lock, and to use multiple CPU you will need to use costly multi-process. These are more suited for I/O only but no cpu intensive response processing.

In Parallec, you may handle response either in Worker (before aggregation: in parallel) or in Manager (after aggregation: single thread). Read More..

Your name here

Parallec is served to you by Yuanteng (Jeff) Pei and Teng Song, Cloud Infrastructure & Platform Services (CIPS) at eBay Inc.

• We thanks our manager Andy Santosa, project manager Marco Rotelli, Cloud Infrastructure & Platform Services (CIPS) and legal for the big support on this project and the open source effort.
• The auto-progress polling is inspired by lightflow.
• We thank openpojo and the author Osman Shoukry for his help on making the openpojo more accessible for us to use in our project.
• We thank AsyncHttpClient and Stephane Landelle for guidance.

##Contributions

Any helpful feedback is more than welcome. This includes feature requests, bug reports, pull requests, constructive feedback, and etc.

Code licensed under Apache License v2.0

© 2015 eBay Software Foundation