|
| 1 | +<!-- |
| 2 | +
|
| 3 | + DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. |
| 4 | +
|
| 5 | + Copyright (c) 2017 Oracle and/or its affiliates. All rights reserved. |
| 6 | +
|
| 7 | + The contents of this file are subject to the terms of either the GNU |
| 8 | + General Public License Version 2 only ("GPL") or the Common Development |
| 9 | + and Distribution License("CDDL") (collectively, the "License"). You |
| 10 | + may not use this file except in compliance with the License. You can |
| 11 | + obtain a copy of the License at |
| 12 | + http://glassfish.java.net/public/CDDL+GPL_1_1.html |
| 13 | + or packager/legal/LICENSE.txt. See the License for the specific |
| 14 | + language governing permissions and limitations under the License. |
| 15 | +
|
| 16 | + When distributing the software, include this License Header Notice in each |
| 17 | + file and include the License file at packager/legal/LICENSE.txt. |
| 18 | +
|
| 19 | + GPL Classpath Exception: |
| 20 | + Oracle designates this particular file as subject to the "Classpath" |
| 21 | + exception as provided by Oracle in the GPL Version 2 section of the License |
| 22 | + file that accompanied this code. |
| 23 | +
|
| 24 | + Modifications: |
| 25 | + If applicable, add the following below the License Header, with the fields |
| 26 | + enclosed by brackets [] replaced by your own identifying information: |
| 27 | + "Portions Copyright [year] [name of copyright owner]" |
| 28 | +
|
| 29 | + Contributor(s): |
| 30 | + If you wish your version of this file to be governed by only the CDDL or |
| 31 | + only the GPL Version 2, indicate your decision by adding "[Contributor] |
| 32 | + elects to include this software in this distribution under the [CDDL or GPL |
| 33 | + Version 2] license." If you don't indicate a single choice of license, a |
| 34 | + recipient has the option to distribute your version of this file under |
| 35 | + either the CDDL, the GPL Version 2 or to extend the choice of license to |
| 36 | + its licensees as provided above. However, if you add GPL Version 2 code |
| 37 | + and therefore, elected the GPL Version 2 license, then the option applies |
| 38 | + and therefore, elected the GPL Version 2 license, then the option applies |
| 39 | + only if the new code is made subject to such option by the copyright |
| 40 | + holder. |
| 41 | +
|
| 42 | +--> |
| 43 | + |
| 44 | +Jersey OpenTracing Example |
| 45 | +========================== |
| 46 | + |
| 47 | +This example demonstrates Jersey OpenTracing integration. The JAX-RS resource contains several resource method showing various |
| 48 | +possibilities. |
| 49 | + |
| 50 | +This particular example is configured with Jaeger as the GlobalTracer, but can be easily adjusted to use any other tracer |
| 51 | +implementation. |
| 52 | + |
| 53 | +Running the Example |
| 54 | +------------------- |
| 55 | +Example can be launched as is, but does not perform any interesting action out of the box. |
| 56 | +To be able to visualise the traces, it is recommended to start Jaeger (and th UI) locally, e.g. in Docker: |
| 57 | + |
| 58 | +> docker run -d -p 5775:5775/udp -p 16686:16686 jaegertracing/all-in-one:travis-1278 |
| 59 | +
|
| 60 | +Check the UI on [localhost:16686](http://localhost:16686), there should be no traces visible. |
| 61 | + |
| 62 | +Run the example as follows: |
| 63 | + |
| 64 | +> mvn clean compile exec:java |
| 65 | +
|
| 66 | +This deploys the example using [Grizzly](http://grizzly.java.net/) container. |
| 67 | + |
| 68 | +Try to access resources using the URIs listed bellow and look into Jager UI what traces are produced. |
| 69 | +The first example should be visible in the Jaeger UI right after the example application is started. Others can be created by |
| 70 | +doing rest calls to the exposed resource. |
| 71 | + |
| 72 | +1. On start, the example application sends one request demonstrating more complex tracing |
| 73 | +- jersey client (w/ registered OpenTracingFeature) creates the "jersey-client-GET" span |
| 74 | +- the span is propagated to server (via http headers), jersey server (w/ registered OpenTracinfFeature) automatically creates a |
| 75 | + child span of the client span |
| 76 | +- in the resource method, child span of the server span is manually created and propagated into managed client calls |
| 77 | +- the managed clients are also tracing-enabled, so each one creates its own child span, that is propagated to the server, and |
| 78 | +so on |
| 79 | + |
| 80 | +2. No explicit (user-defined) spans. |
| 81 | +- one automatically created "root" span, that measures the processing on the Jersey side and one "resource-level" span to be |
| 82 | +used for logging events on the application level |
| 83 | +- the "root" contains several tags with request and response metadata, such as request headers, status code, etc |
| 84 | +- also, several technical Jersey-level events have been logged |
| 85 | +- to see this simple case, call |
| 86 | +> curl localhost:8080/opentracing/resource/defaultTrace |
| 87 | +
|
| 88 | +3. Explicit logging into resource-level span |
| 89 | +- same as above, but the "resource-level" span was resolved within the application logic, an event was logged and a tag was added |
| 90 | +> curl localhost:8080/opentracing/resource/appLevelLogging |
| 91 | +
|
| 92 | +- similar call with POST: |
| 93 | +> curl -X POST -d "Jersey Rocks" localhost:8080/opentracing/resource/appLevelPost |
| 94 | +
|
| 95 | + |
| 96 | +4. Explicit child span creation |
| 97 | +- same as above, but instead of "resource-level" span, a child span was created and used for logging and adding tags |
| 98 | +- note, that such a span needs to be finished manually, otherwise it won't propagate (the tracing info will be lost) |
| 99 | +> curl localhost:8080/opentracing/resource/childSpan |
| 100 | +
|
| 101 | + |
| 102 | +4. Client calls from the resource |
| 103 | +- more complex case, the resource method invokes two client calls using managed client |
| 104 | +- one request via managed client is triggered within the "provided", resource-level span |
| 105 | +- child span is created and another request via manged client is triggered within the child span |
| 106 | +- the span context needs to be propagated manually using the OpenTracingFeature.SPAN_CONTEXT_PROPERTY |
| 107 | +- in both cases, the span context is propagated using http headers to the server and back to the client |
| 108 | +- the child span (created in the resource) needs to be explicitly finished in the resource (or elsewhere, but needs to be finished) |
| 109 | +> curl localhost:8080/opentracing/resource/traceWithManagedClient |
| 110 | +
|
| 111 | +5. Asynchronous processing |
| 112 | +- either basic case, but using asynchronous request processing |
| 113 | +- there should be no practical difference visible in the tracing info |
| 114 | +> curl localhost:8080/opentracing/resource/async |
| 115 | +
|
| 116 | +6. Failing resource |
| 117 | +- demonstrates exception thrown in the resource method |
| 118 | +- Jaeger shows failed spans with the exclamation mark symbol and the exception is logged in the request span |
| 119 | +> curl localhost:8080/opentracing/resource/error |
0 commit comments