camel-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From acosent...@apache.org
Subject [5/8] camel git commit: Added camel-zipkin docs to Gitbook
Date Thu, 09 Jun 2016 12:19:54 GMT
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 <ancosen@gmail.com>
Authored: Thu Jun 9 13:18:45 2016 +0200
Committer: Andrea Cosentino <ancosen@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)


Mime
View raw message