Added camel-zipkin 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/b6680168 Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/b6680168 Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/b6680168 Branch: refs/heads/master Commit: b6680168d8c77be7a7ad8af666c5733b58f902b7 Parents: 4c3c058 Author: Andrea Cosentino <anco...@gmail.com> Authored: Thu Jun 9 13:18:45 2016 +0200 Committer: Andrea Cosentino <anco...@gmail.com> Committed: Thu Jun 9 13:18:45 2016 +0200 ---------------------------------------------------------------------- .../camel-zipkin/src/main/docs/zipkin.adoc | 257 +++++++++++++++++++ docs/user-manual/en/SUMMARY.md | 1 + 2 files changed, 258 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/b6680168/components/camel-zipkin/src/main/docs/zipkin.adoc ---------------------------------------------------------------------- diff --git a/components/camel-zipkin/src/main/docs/zipkin.adoc b/components/camel-zipkin/src/main/docs/zipkin.adoc new file mode 100644 index 0000000..369517b --- /dev/null +++ b/components/camel-zipkin/src/main/docs/zipkin.adoc @@ -0,0 +1,257 @@ +[[Zipkin-ZipkinComponent]] +Zipkin Component +~~~~~~~~~~~~~~~~ + +*Available as of Camel 2.18* + +The camel-zipkin component is used for tracing and timing incoming and +outgoing Camel messages using http://zipkin.io/[zipkin]. + +Events (span) are captured for incoming and outgoing messages being sent +to/from Camel. + +This means you need to configure which which Camel endpoints that maps +to zipkin service names. + +The mapping can be configured using: + +* route id - A Camel route id +* endpoint url - A Camel endpoint url + +For both kinds you can use wildcards and regular expressions to match, +which is using the rules from link:intercept.html[Intercept]. + +To match all Camel messages you can use * in the pattern and configure +that to the same service name. + +If no mapping has been configured then Camel will fallback and use +endpoint uri's as service names. + +However its recommended to configure service mappings so you can use +human logic names instead of Camel endpoint uris in the names. + +Camel will auto-configure a ScribeSpanCollector if no SpanCollector +explicit has been configured, and if the hostname and port to the span +collector has been configured as environment variables: + +* ZIPKIN_COLLECTOR_THRIFT_SERVICE_HOST - The hostname +* ZIPKIN_COLLECTOR_THRIFT_SERVICE_PORT - The port number + +This makes it easy to use camel-zipkin in container platforms where the +platform can run your application in a linux container where service +configurations are provided as environment variables. + +[[camel-zipkin-Options]] +Options +^^^^^^^ + +[width="100%",cols="10%,10%,80%",options="header",] +|======================================================================= +|Option |Default |Description + +|rate |1.0f |Configures a rate that decides how many events should be traced by +zipkin. The rate is expressed as a percentage (1.0f = 100%, 0.5f is 50%, 0.1f is +10%). + +|spanCollector | |*Mandatory:* The collector to use for sending zipkin span events to the +zipkin server. + +|serviceName | | To use a global service name that matches all Camel events + +|clientServiceMappings | | Sets the *client* service mappings that matches Camel events to the +given zipkin service name. The content is a Map<String, String> where the key is a pattern and the +value is the service name. The pattern uses the rules from link:intercept.html[Intercept]. + +|serverServiceMappings | | Sets the *server* service mappings that matches Camel events to the +given zipkin service name. The content is a Map<String, String> where the key is a pattern and the +value is the service name. The pattern uses the rules from link:intercept.html[Intercept]. + +|excludePatterns | | Sets exclude pattern(s) that will disable tracing with zipkin for Camel +messages that matches the pattern. The content is a Set<String> where the key is a pattern. The pattern +uses the rules from link:intercept.html[Intercept]. + +|includeMessageBody |false |Whether to include the Camel message body in the zipkin traces. +This is not recommended for production usage, or when having big +payloads. You can limit the size by configuring the +link:how-do-i-set-the-max-chars-when-debug-logging-messages-in-camel.html[max +debug log size]. + +|includeMessageBodyStreams |false |Whether to include message bodies that are stream based in the zipkin +traces. This requires enabling streamlink:stream-caching.html[caching] on the +routes or globally on the CamelContext. This is not recommended for production usage, or when having big +payloads. You can limit the size by configuring the +link:how-do-i-set-the-max-chars-when-debug-logging-messages-in-camel.html[max +debug log size].  +|======================================================================= + +[[camel-zipkin-Example]] +Example +^^^^^^^ + +To enable camel-zipkin you need to configure first + +[source,java] +-------------------------------------------------------------------------------------------------- +ZipkinTracer zipkin = new ZipkinTracer(); +// configure the scribe span collector with the hostname and port for the Zipkin Collector Server +zipkin.setSpanCollector(new ScribeSpanCollector("192.168.90.100", 9410); +// and then add zipkin to the CamelContext +zipkin.init(camelContext); +-------------------------------------------------------------------------------------------------- + +The configuration about will the trace all incoming and outgoing +messages in Camel routes. + +To use ZipinTracer in XML all you need to do is to setup scribe an the +zipkin tracer as <bean> and then they are automatic discovered and used +by Camel. + +[source,xml] +--------------------------------------------------------------------------------------------------------- + <!-- configure the scribe span collector with the hostname and port for the Zipkin Collector Server --> + <bean id="scribe" class="com.github.kristofa.brave.scribe.ScribeSpanCollector"> + <constructor-arg index="0" value="192.168.90.100"/> + <constructor-arg index="1" value="9410"/> + </bean> + + <!-- setup zipkin tracer --> + <bean id="zipkinTracer" class="org.apache.camel.zipkin.ZipkinTracer"> + <property name="serviceName" value="dude"/> + <property name="spanCollector" ref="scribe"/> + </bean> +--------------------------------------------------------------------------------------------------------- + +[[camel-zipkin-ServiceName]] +ServiceName ++++++++++++ + +However if you want to map Camel endpoints to human friendly logical +names, you can add mappings + +* ServiceName * + +You can configure a global service name that all events will fallback +and use, such as: + +[source,java] +---------------------------------- +zipkin.setServiceName("invoices"); +---------------------------------- + +This will use the same service name for all incoming and outgoing zipkin +traces. So if your application uses different services, you need to map +them more fine grained into client vs server mappings + +[[camel-zipkin-ClientandServerServiceMappings]] +Client and Server Service Mappings +++++++++++++++++++++++++++++++++++ + +* ClientServiceMappings +* ServerServiceMappings + +So if your application hosts a service that others can call, you can map +the Camel route endpoint to a server service mapping. For example +support your Camel application has the following route + +[source,java] +---------------------------------- +from("activemq:queue:inbox") + ... + .to("http:someserver/somepath"); +---------------------------------- + +And you want to make that as a server service, you can add the following +mapping + +[source,java] +----------------------------------------------------------------- +zipkin.addServerServiceMapping("activemq:queue:inbox", "orders"); +----------------------------------------------------------------- + +Then when a message is consumed from that inbox queue, it becomes a +zipkin server event with the service name orders. + +Now suppose that the call to http:someserver/somepath is also a service, +which you want to map to a client service name, which can be done as: + +[source,java] +-------------------------------------------------------------------- +zipkin.addClientServiceMapping("http:someserver/somepath", "audit"); +-------------------------------------------------------------------- + +Then in the same Camel application you have mapped incoming and outgoing +endpoints to different zipkin service names. + +You can use wildcards in the service mapping, so to match all outgoing +calls the same HTTP server you can do + +------------------------------------------------------------ +zipkin.addClientServiceMapping("http:someserver*", "audit"); +------------------------------------------------------------ + +[[camel-zipkin-Mappingrules]] +Mapping rules ++++++++++++++ + +The service name mapping for server occurs using the following rules + +1. Is there an exclude pattern that matches the endpoint uri of the +from endpoint? If yes then skip. +2. Is there a match in the serviceServiceMapping that matches the +endpoint uri of the from endpoint? If yes the use the found service name +3. Is there a match in the serviceServiceMapping that matches the route +id of the current route? If yes the use the found service name +4. Is there a match in the serviceServiceMapping that matches the +original route id where the exchange started? If yes the use the found +service name +5. No service name was found, the exchange is not traced by zipkin + +The service name mapping for client occurs using the following rules + +1. Is there an exclude pattern that matches the endpoint uri of the +from endpoint? If yes then skip. +2. Is there a match in the clientServiceMapping that matches the +endpoint uri of endpoint where the message is being sent to? If yes the +use the found service name +3. Is there a match in the clientServiceMapping that matches the route +id of the current route? If yes the use the found service name +4. Is there a match in the clientServiceMapping that matches the +original route id where the exchange started? If yes the use the found +service name +5. No service name was found, the exchange is not traced by zipkin + +[[camel-zipkin-Noclientorservermappings]] +No client or server mappings +++++++++++++++++++++++++++++ + +If there has been no configuration of client or server service mappings, +then CamelZipkin runs in a fallback mode, where it uses the endpoint +uris as the service name. + +So in the example above that would mean the service names would be, as +if you add the following code yourself: + +[source,java] +--------------------------------------------------------------------------------------- +zipkin.addServerServiceMapping("activemq:queue:inbox", "activemq:queue:inbox"); +zipkin.addClientServiceMapping("http:someserver/somepath", "http:someserver/somepath"); +--------------------------------------------------------------------------------------- + +This is not a recommended approach but gets you up and running quickly +without doing any service name mappings. However when you have multiple +systems across your infrastructure, then you should consider using human +logic service names, that you map to instead of using the camel endpoint +uris. + +[[camel-zipkin-camel-zipin-starter]] +camel-zipin-starter +^^^^^^^^^^^^^^^^^^^ + +If you are using link:spring-boot.html[Spring Boot] then you can add +the `camel-zipkin-starter` dependency, and turn on zipkin by annotating +the main class with `@CamelZipkin`. You can then configure camel-zipkin +in the `application.properties` file where you can configure the +hostname and port number for the Zipkin Server, and all the other +options as listed in the options table above. + +You can find an example of this in +the https://github.com/apache/camel/tree/master/examples/camel-example-zipkin[camel-example-zipkin] http://git-wip-us.apache.org/repos/asf/camel/blob/b6680168/docs/user-manual/en/SUMMARY.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md index 66369a6..7e0f244 100644 --- a/docs/user-manual/en/SUMMARY.md +++ b/docs/user-manual/en/SUMMARY.md @@ -275,6 +275,7 @@ * [XML Security](xmlsecurity.adoc) * [XMPP](xmpp.adoc) * [Yammer](yammer.adoc) + * [Zipkin](zipkin.adoc) * [ZooKeeper](zookeeper.adoc) * [Expression Languages](languages.adoc)
