You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by ac...@apache.org on 2016/04/19 13:12:49 UTC
camel git commit: Added camel-hystrix docs to gitbook
Repository: camel
Updated Branches:
refs/heads/master b7addb582 -> 57917b0c6
Added camel-hystrix docs to gitbook
Project: http://git-wip-us.apache.org/repos/asf/camel/repo
Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/57917b0c
Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/57917b0c
Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/57917b0c
Branch: refs/heads/master
Commit: 57917b0c6a58e2a4ea77ec9865f6ab8c394e6c74
Parents: b7addb5
Author: Andrea Cosentino <an...@gmail.com>
Authored: Tue Apr 19 13:12:10 2016 +0200
Committer: Andrea Cosentino <an...@gmail.com>
Committed: Tue Apr 19 13:12:10 2016 +0200
----------------------------------------------------------------------
.../camel-hystrix/src/main/docs/hystrix.adoc | 298 +++++++++++++++++++
docs/user-manual/en/SUMMARY.md | 1 +
2 files changed, 299 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/camel/blob/57917b0c/components/camel-hystrix/src/main/docs/hystrix.adoc
----------------------------------------------------------------------
diff --git a/components/camel-hystrix/src/main/docs/hystrix.adoc b/components/camel-hystrix/src/main/docs/hystrix.adoc
new file mode 100644
index 0000000..62ce2fa
--- /dev/null
+++ b/components/camel-hystrix/src/main/docs/hystrix.adoc
@@ -0,0 +1,298 @@
+[[Hystrix-HystrixComponent]]
+Hystrix Component
+~~~~~~~~~~~~~~~~~
+
+*Available as of Camel 2.18*
+
+The hystrix component provides integration with Netflix
+https://github.com/Netflix/Hystrix[Hystrix]. Hystrix is a latency and
+fault tolerance library designed to isolate points of access to remote
+systems, services and 3rd party libraries, stop cascading failure and
+enable resilience in complex distributed systems where failure is
+inevitable.
+
+The current implementation wraps a Camel endpoint in HystrixCommand and
+provides synchronous execution (using Hystrix thread pools), fallback to
+a different Camel endpoint, request caching (with custom request context
+and cache clearing), timeouts. It does not implement request collapsing
+yet.
+
+Maven users will need to add the following dependency to their pom.xml
+for this component:
+
+[source,xml]
+------------------------------------------------------------------------------------
+<dependency>
+ <groupId>org.apache.camel</groupId>
+ <artifactId>camel-hystrix</artifactId>
+ <version>x.x.x</version><!-- use the same version as your Camel core version -->
+</dependency>
+------------------------------------------------------------------------------------
+
+[[Hystrix-URIformat]]
+URI format
+^^^^^^^^^^
+
+[source,java]
+---------------------------
+hystrix::groupKey[?options]
+---------------------------
+
+[[Hystrix-URIOptions]]
+URI Options
+^^^^^^^^^^^
+
+All URI options can be overriden through message headers. Most of the
+default values are coming from Hystrix itself.
+
+
+// component options: START
+The Hystrix component has no options.
+// component options: END
+
+
+
+// endpoint options: START
+The Hystrix component supports 38 endpoint options which are listed below:
+
+[width="100%",cols="2s,1,1m,1m,5",options="header"]
+|=======================================================================
+| Name | Group | Default | Java Type | Description
+| groupKey | producer | | String | *Required* Specifies the group key to use
+| cacheKey | producer | | String | Specifies the cache key to use. Uses the simple language as the expression. But you can refer to an existing expression using lookup.
+| commandKey | producer | CamelHystrixCommand | String | Used to identify a HystrixCommand instance for statistics circuit-breaker properties etc. By default this will be derived from the instance class name.
+| fallbackEnabled | producer | true | Boolean | Whether link HystrixCommandgetFallback() should be attempted when failure occurs.
+| fallbackEndpoint | producer | | String | Specifies the fallback endpoint to use Specify either an url or name of existing endpoint.
+| metricsEnabled | producer | false | boolean | Whether to include a number of headers with metrics details of the circuit breaker utilization
+| requestCacheEnabled | producer | true | Boolean | Whether link HystrixCommandgetCacheKey() should be used with HystrixRequestCache to provide de-duplication functionality via request-scoped caching.
+| runEndpoint | producer | | String | *Required* Specifies the endpoint to use. Specify either an url or name of existing endpoint.
+| exchangePattern | advanced | InOnly | ExchangePattern | Sets the default exchange pattern when creating an exchange
+| synchronous | advanced | false | boolean | Sets whether synchronous processing should be strictly used or Camel is allowed to use asynchronous processing (if supported).
+| circuitBreakerEnabled | circuitbreaker | true | Boolean | Whether to use a HystrixCircuitBreaker or not. If false no circuit-breaker logic will be used and all requests permitted. This is similar in effect to link setCircuitBreakerForceClosed(Boolean) except that continues tracking metrics and knowing whether it should be open/closed this property results in not even instantiating a circuit-breaker.
+| circuitBreakerErrorThresholdPercentage | circuitbreaker | 50 | Integer | Error percentage threshold (as whole number such as 50) at which point the circuit breaker will trip open and reject requests. It will stay tripped for the duration defined in link getCircuitBreakerSleepWindowInMilliseconds(); The error percentage this is compared against comes from link HystrixCommandMetricsgetHealthCounts().
+| circuitBreakerForceClosed | circuitbreaker | | Boolean | If true the link HystrixCircuitBreakerallowRequest() will always return true to allow requests regardless of the error percentage from link HystrixCommandMetricsgetHealthCounts(). The circuitBreakerForceOpen property takes precedence so if it set to true this property does nothing.
+| circuitBreakerForceOpen | circuitbreaker | | Boolean | If true the link HystrixCircuitBreakerallowRequest() will always return false causing the circuit to be open (tripped) and reject all requests. This property takes precedence over circuitBreakerForceClosed
+| circuitBreakerRequestVolumeThreshold | circuitbreaker | 20 | Integer | Minimum number of requests in the link setMetricsRollingStatisticalWindowInMilliseconds(Integer) that must exist before the HystrixCircuitBreaker will trip. If below this number the circuit will not trip regardless of error percentage.
+| circuitBreakerSleepWindowInMilliseconds | circuitbreaker | 5000 | Integer | The time in milliseconds after a HystrixCircuitBreaker trips open that it should wait before trying requests again.
+| executionIsolationSemaphoreMaxConcurrentRequests | circuitbreaker | 10 | Integer | Number of concurrent requests permitted to link HystrixCommandrun(). Requests beyond the concurrent limit will be rejected. Applicable only when link getExecutionIsolationStrategy() == SEMAPHORE.
+| executionIsolationStrategy | circuitbreaker | THREAD | String | What isolation strategy link HystrixCommandrun() will be executed with. If THREAD then it will be executed on a separate thread and concurrent requests limited by the number of threads in the thread-pool. If SEMAPHORE then it will be executed on the calling thread and concurrent requests limited by the semaphore count.
+| executionIsolationThreadInterruptOnTimeout | circuitbreaker | true | Boolean | Whether the execution thread should attempt an interrupt (using link Futurecancel) when a thread times out. Applicable only when executionIsolationStrategy == THREAD.
+| executionTimeoutEnabled | circuitbreaker | true | Boolean | Whether the timeout mechanism is enabled for this command
+| executionTimeoutInMilliseconds | circuitbreaker | 1000 | Integer | Allow a dynamic override of the HystrixThreadPoolKey that will dynamically change which HystrixThreadPool a HystrixCommand executes on. Typically this should return NULL which will cause it to use the HystrixThreadPoolKey injected into a HystrixCommand or derived from the HystrixCommandGroupKey. When set the injected or derived values will be ignored and a new HystrixThreadPool created (if necessary) and the HystrixCommand will begin using the newly defined pool.
+| fallbackIsolationSemaphoreMaxConcurrentRequests | circuitbreaker | 10 | Integer | Number of concurrent requests permitted to link HystrixCommandgetFallback(). Requests beyond the concurrent limit will fail-fast and not attempt retrieving a fallback.
+| metricsHealthSnapshotIntervalInMilliseconds | monitoring | 500 | Integer | Time in milliseconds to wait between allowing health snapshots to be taken that calculate success and error percentages and affect link HystrixCircuitBreakerisOpen() status. On high-volume circuits the continual calculation of error percentage can become CPU intensive thus this controls how often it is calculated.
+| metricsRollingPercentileBucketSize | monitoring | 100 | Integer | Maximum number of values stored in each bucket of the rolling percentile. This is passed into HystrixRollingPercentile inside HystrixCommandMetrics.
+| metricsRollingPercentileEnabled | monitoring | true | Boolean | Whether percentile metrics should be captured using HystrixRollingPercentile inside HystrixCommandMetrics.
+| metricsRollingPercentileWindowBuckets | monitoring | 6 | Integer | Number of buckets the rolling percentile window is broken into. This is passed into HystrixRollingPercentile inside HystrixCommandMetrics.
+| metricsRollingPercentileWindowInMilliseconds | monitoring | 60000 | Integer | Duration of percentile rolling window in milliseconds. This is passed into HystrixRollingPercentile inside HystrixCommandMetrics.
+| metricsRollingStatisticalWindowBuckets | monitoring | 10 | Integer | Number of buckets the rolling statistical window is broken into. This is passed into HystrixRollingNumber inside HystrixCommandMetrics.
+| metricsRollingStatisticalWindowInMilliseconds | monitoring | 10000 | Integer | Duration of statistical rolling window in milliseconds. This is passed into HystrixRollingNumber inside HystrixCommandMetrics.
+| requestLogEnabled | monitoring | true | Boolean | Whether HystrixCommand execution and events should be logged to HystrixRequestLog.
+| coreSize | threadpool | 10 | Integer | This property sets the core thread-pool size. This is the maximum number of HystrixCommands that can execute concurrently.
+| initializeRequestContext | threadpool | | Boolean | Call this at the beginning of each request (from parent thread) to initialize the underlying context so that HystrixRequestVariableDefault can be used on any children threads and be accessible from the parent thread.
+| keepAliveTime | threadpool | 1 | Integer | This property sets the keep-alive time in minutes.
+| maxQueueSize | threadpool | -1 | Integer | This property sets the maximum queue size of the BlockingQueue implementation.
+| queueSizeRejectionThreshold | threadpool | 5 | Integer | This property sets the queue size rejection threshold an artificial maximum queue size at which rejections will occur even if maxQueueSize has not been reached.
+| threadPoolKey | threadpool | | String | Used to define which thread-pool this command should run in. By default this is derived from the HystrixCommandGroupKey.
+| threadPoolMetricsRollingStatisticalWindowBuckets | threadpool | 10 | Integer | This property sets the number of buckets the rolling statistical window is divided into.
+| threadPoolMetricsRollingStatisticalWindowInMilliseconds | threadpool | 10000 | Integer | This property sets the duration of the statistical rolling window in milliseconds. This is how long metrics are kept for the thread pool.
+|=======================================================================
+// endpoint options: END
+
+
+[[Hystrix-InMessageHeaders]]
+In Message Headers
+^^^^^^^^^^^^^^^^^^
+
+Used to override URI options per message basis.
+
+[width="100%",cols="10%,10%,80%",options="header",]
+|=======================================================================
+
+|Name |Type |Description
+
+|CamelHystrixClearCacheFirst |Boolean |Description and default value provided in the URI options section above.
+
+|CamelHystrixRequestContex |HystrixRequestContext |Description and default value provided in the URI options section above.
+
+|CamelHystrixGroupKey |String |Description and default value provided in the URI options section above.
+
+|CamelHystrixCommandKey |String |Description and default value provided in the URI options section above.
+
+|CamelHystrixThreadPoolKey |String |Description and default value provided in the URI options section above.
+
+|CamelHystrixRunEndpointId |String |Description and default value provided in the URI options section above.
+
+|CamelHystrixFallbackEndpointId |String |Description and default value provided in the URI options section above.
+
+|CamelHystrixCorePoolSize |Integer |Description and default value provided in the URI options section above.
+
+|CamelHystrixKeepAliveTime |Integer |Description and default value provided in the URI options section above.
+
+|CamelHystrixMaxQueueSize |Integer |Description and default value provided in the URI options section above.
+
+|CamelHystrixQueueSizeRejectionThreshold |Integer |Description and default value provided in the URI options section above.
+
+|CamelHystrixThreadPoolMetricsRollingStatisticalWindowInMilliseconds |Integer |Description and default value provided in the URI options section above.
+
+|CamelHystrixThreadPoolRollingNumberStatisticalWindowBuckets |Integer |Description and default value provided in the URI options section above.
+
+|CamelHystrixCircuitBreakerEnabled |Boolean |Description and default value provided in the URI options section above.
+
+|CamelHystrixCircuitBreakerErrorThresholdPercentage |Integer |Description and default value provided in the URI options section above.
+
+|CamelHystrixCircuitBreakerForceClosed |Boolean |Description and default value provided in the URI options section above.
+
+|CamelHystrixCircuitBreakerForceOpen |Boolean |Description and default value provided in the URI options section above.
+
+|CamelHystrixCircuitBreakerRequestVolumeThreshold |Integer |Description and default value provided in the URI options section above.
+
+|CamelHystrixCircuitBreakerSleepWindowInMilliseconds |Integer |Description and default value provided in the URI options section above.
+
+|CamelHystrixExecutionIsolationSemaphoreMaxConcurrentRequests |Integer |Description and default value provided in the URI options section above.
+
+|CamelHystrixExecutionIsolationStrategy |String |Description and default value provided in the URI options section above.
+
+|CamelHystrixExecutionIsolationThreadInterruptOnTimeout |Boolean |Description and default value provided in the URI options section above.
+
+|CamelHystrixExecutionTimeoutInMilliseconds |Integer |Description and default value provided in the URI options section above.
+
+|CamelHystrixExecutionTimeoutEnabled |Boolean |Description and default value provided in the URI options section above.
+
+|CamelHystrixFallbackIsolationSemaphoreMaxConcurrentRequests |Integer |Description and default value provided in the URI options section above.
+
+|CamelHystrixFallbackEnabled |Boolean |Description and default value provided in the URI options section above.
+
+|CamelHystrixMetricsHealthSnapshotIntervalInMilliseconds |Integer |Description and default value provided in the URI options section above.
+
+|CamelHystrixMetricsRollingPercentileBucketSize |Integer |Description and default value provided in the URI options section above.
+
+|CamelHystrixMetricsRollingPercentileEnabled |Boolean |Description and default value provided in the URI options section above.
+
+|CamelHystrixMetricsRollingPercentileWindowInMilliseconds |Integer |Description and default value provided in the URI options section above.
+
+|CamelHystrixMetricsRollingPercentileWindowBuckets |Integer |Description and default value provided in the URI options section above.
+
+|CamelHystrixMetricsRollingStatisticalWindowInMilliseconds |Integer |Description and default value provided in the URI options section above.
+
+|CamelHystrixMetricsRollingStatisticalWindowBuckets |Integer |Description and default value provided in the URI options section above.
+
+|CamelHystrixRequestCacheEnabled |Boolean |Description and default value provided in the URI options section above.
+
+|CamelHystrixRequestLogEnabled |Boolean |Description and default value provided in the URI options section above.
+|=======================================================================
+
+[[Hystrix-OutMessageHeaders]]
+Out Message Headers
+^^^^^^^^^^^^^^^^^^^
+
+Mainly to provide metrics information.
+
+[width="100%",cols="10%,10%,80%",options="header",]
+|=======================================================================
+
+|Name |Type |Description
+
+|CamelHystrixRequestContex |CamelHystrixRequestContex |The default CamelHystrixRequestContex created during producer startup.
+
+|CamelHystrixCommandMetricsTotalRequests |long |Number of requests during rolling window (failure + success + timeout +
+threadPoolRejected + semaphoreRejected).
+
+|CamelHystrixCommandMetricsErrorCount |long |Number of failed requests during rolling window (failure + timeout +
+threadPoolRejected + semaphoreRejected).
+
+|CamelHystrixCommandMetricsErrorPercentage |int |errorCount / totalCount * 100.
+
+|CamelHystrixCommandMetricsCurrentConcurrentExecutionCount |int |Current number of concurrent executions of HystrixCommand#run().
+
+|CamelHystrixCommandMetricsExecutionTimeMean |int |The mean (average) execution time (in milliseconds) for the
+HystrixCommand#run().
+
+|CamelHystrixCommandMetricsRollingMaxConcurrentExecutions |long |Get the max value of values in all buckets for the given
+HystrixRollingNumberEvent.
+
+|CamelHystrixCommandMetricsTotalTimeMean |int |The mean (average) execution time (in milliseconds) for
+HystrixCommand#execute().
+
+|CamelHystrixThreadPoolMetricsCurrentActiveCount |int |Returns the approximate number of threads that are actively executing
+tasks.
+
+|CamelHystrixThreadPoolMetricsCumulativeCountThreadsExecuted |long |Cumulative count of number of threads executed since the start of the
+application.
+
+|CamelHystrixThreadPoolMetricsCurrentCompletedTaskCount |long |Returns the approximate total number of tasks that have completed
+execution.
+
+|CamelHystrixThreadPoolMetricsCurrentCorePoolSize |int |Returns the core number of threads.
+
+|CamelHystrixThreadPoolMetricsCurrentLargestPoolSize |int |Returns the largest number of threads that have ever simultaneously been
+in the pool.
+
+|CamelHystrixThreadPoolMetricsCurrentMaximumPoolSize |int |Returns the maximum allowed number of threads.
+
+|CamelHystrixThreadPoolMetricsCurrentPoolSize |int |Returns the current number of threads in the pool.
+
+|CamelHystrixThreadPoolMetricsCurrentQueueSize |int |Current size of BlockingQueue used by the thread-pool.
+
+|CamelHystrixThreadPoolMetricsCurrentTaskCount |long |Returns the approximate total number of tasks that have ever been
+scheduled for execution.
+
+|CamelHystrixThreadPoolMetricsRollingCountThreadsExecuted |long |Rolling count of number of threads executed during rolling statistical
+window.
+
+|CamelHystrixThreadPoolMetricsRollingMaxActiveThreads |long |Rolling max number of active threads during rolling statistical window.
+|=======================================================================
+
+[[Hystrix-Example]]
+Example
+^^^^^^^
+
+Below is an example route that with Hystrix endpoint that protects
+agains slow operation and fallbacks to a different endpoint.
+
+[source,java]
+----------------------------------------------------------------------------------------------------------------------------
+@Override
+protected CamelContext createCamelContext() throws Exception {
+ SimpleRegistry registry = new SimpleRegistry();
+ CamelContext context = new DefaultCamelContext(registry);
+ registry.put("run", context.getEndpoint("direct:run"));
+ registry.put("fallback", context.getEndpoint("direct:fallback"));
+ registry.put("headerExpression", ExpressionBuilder.headerExpression("key"));
+ return context;
+}
+
+@Override
+protected RouteBuilder createRouteBuilder() {
+ return new RouteBuilder() {
+
+ public void configure() {
+
+ from("direct:fallback")
+ .to("mock:error");
+
+ from("direct:run")
+ .process(new Processor() {
+ @Override
+ public void process(Exchange exchange) throws Exception {
+ Thread.sleep(500); //a slow operation
+ }
+ })
+ .to("mock:result");
+
+ from("direct:start")
+ .to("hystrix:testKey?runEndpointId=run&fallbackEndpointId=fallback&executionTimeoutInMilliseconds=100");
+ }
+ };
+}
+----------------------------------------------------------------------------------------------------------------------------
+
+[[Hystrix-SeeAlso]]
+See Also
+^^^^^^^^
+
+* link:configuring-camel.html[Configuring Camel]
+* link:component.html[Component]
+* link:endpoint.html[Endpoint]
+* link:getting-started.html[Getting Started]
+
http://git-wip-us.apache.org/repos/asf/camel/blob/57917b0c/docs/user-manual/en/SUMMARY.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md
index 61cffef..7ee4174 100644
--- a/docs/user-manual/en/SUMMARY.md
+++ b/docs/user-manual/en/SUMMARY.md
@@ -155,6 +155,7 @@
* [HL7](hl7.adoc)
* [Http](http.adoc)
* [Http4](http4.adoc)
+ * [Hystrix](hystrix.adoc)
* [Ironmq](ironmq.adoc)
* [JMS](jms.adoc)
* [JMX](jmx.adoc)