1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
|
/*
* Copyright 2016, Google Inc.
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
* http://www.apache.org/licenses/LICENSE-2.0
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package io.opencensus.trace;
import static com.google.common.base.Preconditions.checkNotNull;
import io.opencensus.common.NonThrowingCloseable;
import io.opencensus.trace.SpanBuilder.NoopSpanBuilder;
import javax.annotation.Nullable;
/**
* Tracer is a simple, thin class for {@link Span} creation and in-process context interaction.
*
* <p>Users may choose to use manual or automatic Context propagation. Because of that this class
* offers APIs to facilitate both usages.
*
* <p>The automatic context propagation is done using {@link io.grpc.Context} which is a gRPC
* independent implementation for in-process Context propagation mechanism which can carry
* scoped-values across API boundaries and between threads. Users of the library must propagate the
* {@link io.grpc.Context} between different threads.
*
* <p>Example usage with automatic context propagation:
*
* <pre>{@code
* class MyClass {
* private static final Tracer tracer = Tracing.getTracer();
* void doWork() {
* try(NonThrowingCloseable ss = tracer.spanBuilder("MyClass.DoWork").startScopedSpan) {
* tracer.getCurrentSpan().addAnnotation("Starting the work.");
* doWorkInternal();
* tracer.getCurrentSpan().addAnnotation("Finished working.");
* }
* }
* }
* }</pre>
*
* <p>Example usage with manual context propagation:
*
* <pre>{@code
* class MyClass {
* private static final Tracer tracer = Tracing.getTracer();
* void doWork(Span parent) {
* Span childSpan = tracer.spanBuilderWithExplicitParent("MyChildSpan", parent).startSpan();
* childSpan.addAnnotation("Starting the work.");
* try {
* doSomeWork(childSpan); // Manually propagate the new span down the stack.
* } finally {
* // To make sure we end the span even in case of an exception.
* childSpan.end(); // Manually end the span.
* }
* }
* }
* }</pre>
*/
public abstract class Tracer {
private static final NoopTracer noopTracer = new NoopTracer();
/**
* Returns the no-op implementation of the {@code Tracer}.
*
* @return the no-op implementation of the {@code Tracer}.
*/
static Tracer getNoopTracer() {
return noopTracer;
}
/**
* Gets the current Span from the current Context.
*
* <p>To install a {@link Span} to the current Context use {@link #withSpan(Span)} OR use {@link
* SpanBuilder#startScopedSpan} methods to start a new {@code Span}.
*
* <p>startSpan methods do NOT modify the current Context {@code Span}.
*
* @return a default {@code Span} that does nothing and has an invalid {@link SpanContext} if no
* {@code Span} is associated with the current Context, otherwise the current {@code Span}
* from the Context.
*/
public final Span getCurrentSpan() {
Span currentSpan = CurrentSpanUtils.getCurrentSpan();
return currentSpan != null ? currentSpan : BlankSpan.INSTANCE;
}
/**
* Enters the scope of code where the given {@link Span} is in the current Context, and returns an
* object that represents that scope. The scope is exited when the returned object is closed.
*
* <p>Supports try-with-resource idiom.
*
* <p>Can be called with {@link BlankSpan} to enter a scope of code where tracing is stopped.
*
* <p>Example of usage:
*
* <pre>{@code
* private static Tracer tracer = Tracing.getTracer();
* void doWork() {
* // Create a Span as a child of the current Span.
* Span span = tracer.spanBuilder("my span").startSpan();
* try (NonThrowingCloseable ws = tracer.withSpan(span)) {
* tracer.getCurrentSpan().addAnnotation("my annotation");
* doSomeOtherWork(); // Here "span" is the current Span.
* }
* span.end();
* }
* }</pre>
*
* <p>Prior to Java SE 7, you can use a finally block to ensure that a resource is closed
* regardless of whether the try statement completes normally or abruptly.
*
* <p>Example of usage prior to Java SE7:
*
* <pre>{@code
* private static Tracer tracer = Tracing.getTracer();
* void doWork() {
* // Create a Span as a child of the current Span.
* Span span = tracer.spanBuilder("my span").startSpan();
* NonThrowingCloseable ws = tracer.withSpan(span);
* try {
* tracer.getCurrentSpan().addAnnotation("my annotation");
* doSomeOtherWork(); // Here "span" is the current Span.
* } finally {
* ws.close();
* }
* span.end();
* }
* }</pre>
*
* @param span The {@link Span} to be set to the current Context.
* @return an object that defines a scope where the given {@link Span} will be set to the current
* Context.
* @throws NullPointerException if {@code span} is {@code null}.
*/
public final NonThrowingCloseable withSpan(Span span) {
return CurrentSpanUtils.withSpan(checkNotNull(span, "span"));
}
/**
* Returns a {@link SpanBuilder} to create and start a new child {@link Span} as a child of to the
* current {@code Span} if any, otherwise creates a root {@code Span}.
*
* <p>See {@link SpanBuilder} for usage examples.
*
* <p>This <b>must</b> be used to create a {@code Span} when automatic Context propagation is
* used.
*
* <p>This is equivalent with:
*
* <pre>{@code
* tracer.spanBuilderWithExplicitParent("MySpanName",tracer.getCurrentSpan());
* }</pre>
*
* @param spanName The name of the returned Span.
* @return a {@code SpanBuilder} to create and start a new {@code Span}.
* @throws NullPointerException if {@code spanName} is {@code null}.
*/
public final SpanBuilder spanBuilder(String spanName) {
return spanBuilderWithExplicitParent(spanName, CurrentSpanUtils.getCurrentSpan());
}
/**
* Returns a {@link SpanBuilder} to create and start a new child {@link Span} (or root if parent
* is {@code null} or has an invalid {@link SpanContext}), with parent being the designated {@code
* Span}.
*
* <p>See {@link SpanBuilder} for usage examples.
*
* <p>This <b>must</b> be used to create a {@code Span} when manual Context propagation is used OR
* when creating a root {@code Span} with a {@code null} parent.
*
* @param spanName The name of the returned Span.
* @param parent The parent of the returned Span. If {@code null} the {@code SpanBuilder} will
* build a root {@code Span}.
* @return a {@code SpanBuilder} to create and start a new {@code Span}.
* @throws NullPointerException if {@code spanName} is {@code null}.
*/
public abstract SpanBuilder spanBuilderWithExplicitParent(String spanName, @Nullable Span parent);
/**
* Returns a {@link SpanBuilder} to create and start a new child {@link Span} (or root if parent
* is {@link SpanContext#INVALID} or {@code null}), with parent being the remote {@link Span}
* designated by the {@link SpanContext}.
*
* <p>See {@link SpanBuilder} for usage examples.
*
* <p>This <b>must</b> be used to create a {@code Span} when the parent is in a different process.
* This is only intended for use by RPC systems or similar.
*
* <p>If no {@link SpanContext} OR fail to parse the {@link SpanContext} on the server side, users
* must call this method with a {@code null} remote parent {@code SpanContext}.
*
* @param spanName The name of the returned Span.
* @param remoteParentSpanContext The remote parent of the returned Span.
* @return a {@code SpanBuilder} to create and start a new {@code Span}.
* @throws NullPointerException if {@code spanName} is {@code null}.
*/
public abstract SpanBuilder spanBuilderWithRemoteParent(
String spanName, @Nullable SpanContext remoteParentSpanContext);
// No-Op implementation of the Tracer.
private static final class NoopTracer extends Tracer {
@Override
public SpanBuilder spanBuilderWithExplicitParent(String spanName, @Nullable Span parent) {
return NoopSpanBuilder.createWithParent(spanName, parent);
}
@Override
public SpanBuilder spanBuilderWithRemoteParent(
String spanName, @Nullable SpanContext remoteParentSpanContext) {
return NoopSpanBuilder.createWithRemoteParent(spanName, remoteParentSpanContext);
}
private NoopTracer() {}
}
protected Tracer() {}
}
|
