camel-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From acosent...@apache.org
Subject camel git commit: Added camel-hystrix docs to gitbook
Date Tue, 19 Apr 2016 11:12:49 GMT
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 <ancosen@gmail.com>
Authored: Tue Apr 19 13:12:10 2016 +0200
Committer: Andrea Cosentino <ancosen@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)


Mime
View raw message