Skip to content

Commit 93d990e

Browse files
dalexandrovdalexandrov
authored
OpenTracing add missing documentation (helidon-io#3368)
* MP document aligned with SE * Applied comments by Tomas Langer.
1 parent 6c0d2c5 commit 93d990e

3 files changed

Lines changed: 140 additions & 53 deletions

File tree

‎docs/mp/tracing/01_tracing.adoc‎

Lines changed: 68 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ include::{common-deps-page-prefix-inc}[tag=maven-dependency]
3636
3737
== Configuring Tracing with Helidon MP
3838
Tracing support is implemented for both for Helidon MP Server and for Jersey client.
39-
In addition you need to add one of the tracer implementations:
39+
In addition, you need to add one of the tracer implementations:
4040
4141
- <<tracing/02_zipkin.adoc,Zipkin>>
4242
- <<tracing/03_jaeger.adoc,Jaeger>>
@@ -55,6 +55,19 @@ tracing.service=event-service
5555
5656
include::../../shared/tracing/common-config.adoc[]
5757
58+
To disable Helidon tracing for web server and security:
59+
[source,properties]
60+
----
61+
tracing.components.web-server.enabled=false
62+
tracing.components.security.enabled=false
63+
----
64+
65+
To disables MP Tracing as by specification:
66+
[source,properties]
67+
----
68+
mp.opentracing.server.skip-pattern=.*
69+
----
70+
5871
== Creating custom spans
5972
6073
Helidon MP fully supports MicroProfile OpenTracing.
@@ -94,3 +107,57 @@ Response response = client.target(serviceEndpoint)
94107
.get();
95108
----
96109
110+
include::../../shared/tracing/common-spans.adoc[]
111+
112+
==== Configuration using MP Config
113+
114+
Tracing configuration can be defined in `microprofile-config.properties` file.
115+
116+
[source, properties]
117+
.Tracing configuration
118+
----
119+
tracing.components.web-server.spans.0.name="HTTP Request"
120+
tracing.components.web-server.spans.0.logs.0.name="content-write"
121+
tracing.components.web-server.spans.0.logs.0.enabled=false
122+
----
123+
124+
==== Path based configuration in Helidon Web Server
125+
126+
For Web Server we have a path based support for configuring tracing, in addition
127+
to the configuration described above.
128+
129+
Configuration of path can use any path string supported by the
130+
Web Server. The configuration itself has the same possibilities
131+
as traced configuration described above. The path specific configuration
132+
will be merged with global configuration (path is the "newer" configuration, global is the "older")
133+
134+
[source,properties]
135+
.Configuration properties
136+
----
137+
tracing.paths.0.path="/favicon.ico"
138+
tracing.paths.0.enabled=false
139+
tracing.paths.1.path="/metrics"
140+
tracing.paths.1.enabled=false
141+
tracing.paths.2.path="/health"
142+
tracing.paths.2.enabled=false
143+
----
144+
145+
==== Renaming top level span using request properties
146+
147+
To have a nicer overview in search pane of a tracer, you can customize the top-level span name using configuration.
148+
149+
Example:
150+
[source,properties]
151+
.Configuration properties
152+
----
153+
tracing.components.web-server.spans.0.name="HTTP Request"
154+
tracing.components.web-server.spans.0.new-name: "HTTP %1$s %2$s"
155+
----
156+
157+
This is supported ONLY for the span named "HTTP Request" on component "web-server".
158+
159+
Parameters provided:
160+
161+
1. Method - HTTP method
162+
2. Path - path of the request (such as '/greet')
163+
3. Query - query of the request (may be null)

‎docs/se/tracing/01_tracing.adoc‎

Lines changed: 1 addition & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -118,58 +118,7 @@ Response response = client.target(serviceEndpoint)
118118
.get();
119119
----
120120
121-
== Traced spans
122-
123-
The following table lists all spans traced by Helidon components:
124-
125-
|===
126-
|component |span name |description
127-
128-
|`web-server` |`HTTP Request` |The overall span of the Web Server from request intitiation until response
129-
Note that in `Zipkin` the name is replaced with `jax-rs` span name if `jax-rs` tracing
130-
is used.
131-
|`web-server` |`content-read` |Span for reading the request entity
132-
|`web-server` |`content-write` |Span for writing the response entity
133-
|`security` |`security` |Processing of request security
134-
|`security` |`security:atn` |Span for request authentication
135-
|`security` |`security:atz` |Span for request authorization
136-
|`security` |`security:response` |Processing of response security
137-
|`security` |`security:outbound` |Processing of outbound security
138-
|`jax-rs` |A generated name |Span for the resource method invocation, name is generated from class and method name
139-
|`jax-rs` |`jersey-client-call` |Span for outbound client call
140-
|===
141-
142-
Some of these spans `log` to the span. These log events can be (in most cases) configured:
143-
144-
|===
145-
|span name |log name |configurable |enabled by default |description
146-
147-
|`HTTP Request` |`handler.class` |YES |YES |Each handler has its class and event logged
148-
|`security` |`status` |YES |YES |Logs either "status: PROCEED" or "status: DENY"
149-
|`security:atn` |`security.user` |YES |NO |The username of the user if logged in
150-
|`security:atn` |`security.service` |YES |NO |The name of the service if logged in
151-
|`security:atn` |`status` |YES |YES |Logs the status of security response (such as `SUCCESS`)
152-
|`security:atz` |`status` |YES |YES |Logs the status of security response (such as `SUCCESS`)
153-
|`security:outbound`|`status` |YES |YES |Logs the status of security response (such as `SUCCESS`)
154-
|===
155-
156-
There are also tags that are set by Helidon components. These are not configurable.
157-
158-
|===
159-
|span name |tag name |description
160-
161-
|`HTTP Request` |`component` |name of the component - `helidon-webserver`, or `jaxrs` when using MP
162-
|`HTTP Request` |`http.method` |HTTP method of the request, such as `GET`, `POST`
163-
|`HTTP Request` |`http.status_code` |HTTP status code of the response
164-
|`HTTP Request` |`http.url` |The path of the request (for SE without protocol, host and port)
165-
|`HTTP Request` |`error` |If the request ends in error, this tag is set to `true`, usually accompanied by logs with details
166-
|`content-read` |`requested.type` |Type (class) of the requested entity (if entity is read)
167-
|`content-write` |`response.type` |Type (class) of the entity being sent (if enitty is sent)
168-
|`security` |`security.id` |ID of the security context created for this request (if security is used)
169-
|`jersey-client-call` |`http.method` |HTTP method of the client request
170-
|`jersey-client-call` |`http.status_code` |HTTP status code of client response
171-
|`jersey-client-call` |`http.url` |Full URL of the request (such as `http://localhost:8080/greet`)
172-
|===
121+
include::../../shared/tracing/common-spans.adoc[]
173122
174123
=== Traced spans configuration
175124

‎docs/shared/tracing/common-spans.adoc‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
///////////////////////////////////////////////////////////////////////////////
2+
3+
Copyright (c) 2021 Oracle and/or its affiliates.
4+
5+
Licensed under the Apache License, Version 2.0 (the "License");
6+
you may not use this file except in compliance with the License.
7+
You may obtain a copy of the License at
8+
9+
http://www.apache.org/licenses/LICENSE-2.0
10+
11+
Unless required by applicable law or agreed to in writing, software
12+
distributed under the License is distributed on an "AS IS" BASIS,
13+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
See the License for the specific language governing permissions and
15+
limitations under the License.
16+
17+
///////////////////////////////////////////////////////////////////////////////
18+
19+
== Traced spans
20+
21+
The following table lists all spans traced by Helidon components:
22+
23+
|===
24+
|component |span name |description
25+
26+
|`web-server` |`HTTP Request` |The overall span of the Web Server from request intitiation until response
27+
Note that in `Zipkin` the name is replaced with `jax-rs` span name if `jax-rs` tracing
28+
is used.
29+
|`web-server` |`content-read` |Span for reading the request entity
30+
|`web-server` |`content-write` |Span for writing the response entity
31+
|`security` |`security` |Processing of request security
32+
|`security` |`security:atn` |Span for request authentication
33+
|`security` |`security:atz` |Span for request authorization
34+
|`security` |`security:response` |Processing of response security
35+
|`security` |`security:outbound` |Processing of outbound security
36+
|`jax-rs` |A generated name |Span for the resource method invocation, name is generated from class and method name
37+
|`jax-rs` |`jersey-client-call` |Span for outbound client call
38+
|===
39+
40+
Some of these spans `log` to the span. These log events can be (in most cases) configured:
41+
42+
|===
43+
|span name |log name |configurable |enabled by default |description
44+
45+
|`HTTP Request` |`handler.class` |YES |YES |Each handler has its class and event logged
46+
|`security` |`status` |YES |YES |Logs either "status: PROCEED" or "status: DENY"
47+
|`security:atn` |`security.user` |YES |NO |The username of the user if logged in
48+
|`security:atn` |`security.service` |YES |NO |The name of the service if logged in
49+
|`security:atn` |`status` |YES |YES |Logs the status of security response (such as `SUCCESS`)
50+
|`security:atz` |`status` |YES |YES |Logs the status of security response (such as `SUCCESS`)
51+
|`security:outbound`|`status` |YES |YES |Logs the status of security response (such as `SUCCESS`)
52+
|===
53+
54+
There are also tags that are set by Helidon components. These are not configurable.
55+
56+
|===
57+
|span name |tag name |description
58+
59+
|`HTTP Request` |`component` |name of the component - `helidon-webserver`, or `jaxrs` when using MP
60+
|`HTTP Request` |`http.method` |HTTP method of the request, such as `GET`, `POST`
61+
|`HTTP Request` |`http.status_code` |HTTP status code of the response
62+
|`HTTP Request` |`http.url` |The path of the request (for SE without protocol, host and port)
63+
|`HTTP Request` |`error` |If the request ends in error, this tag is set to `true`, usually accompanied by logs with details
64+
|`content-read` |`requested.type` |Type (class) of the requested entity (if entity is read)
65+
|`content-write` |`response.type` |Type (class) of the entity being sent (if enitty is sent)
66+
|`security` |`security.id` |ID of the security context created for this request (if security is used)
67+
|`jersey-client-call` |`http.method` |HTTP method of the client request
68+
|`jersey-client-call` |`http.status_code` |HTTP status code of client response
69+
|`jersey-client-call` |`http.url` |Full URL of the request (such as `http://localhost:8080/greet`)
70+
|===
71+

0 commit comments

Comments
 (0)