Skip to content

Commit 287eae9

Browse files
jkwatsonjkwatson
authored
Update for the more restricted span status codes. (open-telemetry#1701)
* Update for the more restricted span status codes. * Update status codes to match the proposed proto codes
1 parent e7706d6 commit 287eae9

20 files changed

Lines changed: 132 additions & 492 deletions

File tree

‎QUICKSTART.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ try (Scope scope = tracer.withSpan(span)) {
5555
// your use case
5656
...
5757
} catch (Throwable t) {
58-
Status status = Status.UNKNOWN.withDescription("Change it to your error message");
58+
Status status = Status.ERROR.withDescription("Change it to your error message");
5959
span.setStatus(status);
6060
} finally {
6161
span.end(); // closing the scope does not end the span, this has to be done manually

‎api/src/main/java/io/opentelemetry/trace/Status.java‎

Lines changed: 31 additions & 279 deletions
Original file line numberDiff line numberDiff line change
@@ -17,10 +17,9 @@
1717
package io.opentelemetry.trace;
1818

1919
import io.opentelemetry.internal.Utils;
20-
import java.util.ArrayList;
2120
import java.util.Arrays;
2221
import java.util.Collections;
23-
import java.util.List;
22+
import java.util.Map;
2423
import java.util.Objects;
2524
import java.util.TreeMap;
2625
import javax.annotation.Nullable;
@@ -44,163 +43,18 @@ public final class Status {
4443
* @since 0.1.0
4544
*/
4645
public enum CanonicalCode {
47-
/**
48-
* The operation completed successfully.
49-
*
50-
* @since 0.1.0
51-
*/
52-
OK(0),
53-
54-
/**
55-
* The operation was cancelled (typically by the caller).
56-
*
57-
* @since 0.1.0
58-
*/
59-
CANCELLED(1),
60-
61-
/**
62-
* Unknown error. An example of where this error may be returned is if a Status value received
63-
* from another address space belongs to an error-space that is not known in this address space.
64-
* Also errors raised by APIs that do not return enough error information may be converted to
65-
* this error.
66-
*
67-
* @since 0.1.0
68-
*/
69-
UNKNOWN(2),
70-
71-
/**
72-
* Client specified an invalid argument. Note that this differs from FAILED_PRECONDITION.
73-
* INVALID_ARGUMENT indicates arguments that are problematic regardless of the state of the
74-
* system (e.g., a malformed file name).
75-
*
76-
* @since 0.1.0
77-
*/
78-
INVALID_ARGUMENT(3),
79-
80-
/**
81-
* Deadline expired before operation could complete. For operations that change the state of the
82-
* system, this error may be returned even if the operation has completed successfully. For
83-
* example, a successful response from a server could have been delayed long enough for the
84-
* deadline to expire.
85-
*
86-
* @since 0.1.0
87-
*/
88-
DEADLINE_EXCEEDED(4),
89-
90-
/**
91-
* Some requested entity (e.g., file or directory) was not found.
92-
*
93-
* @since 0.1.0
94-
*/
95-
NOT_FOUND(5),
96-
97-
/**
98-
* Some entity that we attempted to create (e.g., file or directory) already exists.
99-
*
100-
* @since 0.1.0
101-
*/
102-
ALREADY_EXISTS(6),
103-
104-
/**
105-
* The caller does not have permission to execute the specified operation. PERMISSION_DENIED
106-
* must not be used for rejections caused by exhausting some resource (use RESOURCE_EXHAUSTED
107-
* instead for those errors). PERMISSION_DENIED must not be used if the caller cannot be
108-
* identified (use UNAUTHENTICATED instead for those errors).
109-
*
110-
* @since 0.1.0
111-
*/
112-
PERMISSION_DENIED(7),
113-
114-
/**
115-
* Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system
116-
* is out of space.
117-
*
118-
* @since 0.1.0
119-
*/
120-
RESOURCE_EXHAUSTED(8),
121-
122-
/**
123-
* Operation was rejected because the system is not in a state required for the operation's
124-
* execution. For example, directory to be deleted may be non-empty, an rmdir operation is
125-
* applied to a non-directory, etc.
126-
*
127-
* <p>A litmus test that may help a service implementor in deciding between FAILED_PRECONDITION,
128-
* ABORTED, and UNAVAILABLE: (a) Use UNAVAILABLE if the client can retry just the failing call.
129-
* (b) Use ABORTED if the client should retry at a higher-level (e.g., restarting a
130-
* read-modify-write sequence). (c) Use FAILED_PRECONDITION if the client should not retry until
131-
* the system state has been explicitly fixed. E.g., if an "rmdir" fails because the directory
132-
* is non-empty, FAILED_PRECONDITION should be returned since the client should not retry unless
133-
* they have first fixed up the directory by deleting files from it.
134-
*
135-
* @since 0.1.0
136-
*/
137-
FAILED_PRECONDITION(9),
138-
139-
/**
140-
* The operation was aborted, typically due to a concurrency issue like sequencer check
141-
* failures, transaction aborts, etc.
142-
*
143-
* <p>See litmus test above for deciding between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE.
144-
*
145-
* @since 0.1.0
146-
*/
147-
ABORTED(10),
14846

14947
/**
150-
* Operation was attempted past the valid range. E.g., seeking or reading past end of file.
151-
*
152-
* <p>Unlike INVALID_ARGUMENT, this error indicates a problem that may be fixed if the system
153-
* state changes. For example, a 32-bit file system will generate INVALID_ARGUMENT if asked to
154-
* read at an offset that is not in the range [0,2^32-1], but it will generate OUT_OF_RANGE if
155-
* asked to read from an offset past the current file size.
156-
*
157-
* <p>There is a fair bit of overlap between FAILED_PRECONDITION and OUT_OF_RANGE. We recommend
158-
* using OUT_OF_RANGE (the more specific error) when it applies so that callers who are
159-
* iterating through a space can easily look for an OUT_OF_RANGE error to detect when they are
160-
* done.
161-
*
162-
* @since 0.1.0
48+
* The operation has been validated by an Application developers or Operator to have completed
49+
* successfully.
16350
*/
164-
OUT_OF_RANGE(11),
165-
166-
/**
167-
* Operation is not implemented or not supported/enabled in this service.
168-
*
169-
* @since 0.1.0
170-
*/
171-
UNIMPLEMENTED(12),
172-
173-
/**
174-
* Internal errors. Means some invariants expected by underlying system has been broken. If you
175-
* see one of these errors, something is very broken.
176-
*
177-
* @since 0.1.0
178-
*/
179-
INTERNAL(13),
180-
181-
/**
182-
* The service is currently unavailable. This is a most likely a transient condition and may be
183-
* corrected by retrying with a backoff.
184-
*
185-
* <p>See litmus test above for deciding between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE.
186-
*
187-
* @since 0.1.0
188-
*/
189-
UNAVAILABLE(14),
51+
OK(0),
19052

191-
/**
192-
* Unrecoverable data loss or corruption.
193-
*
194-
* @since 0.1.0
195-
*/
196-
DATA_LOSS(15),
53+
/** The default status. */
54+
UNSET(1),
19755

198-
/**
199-
* The request does not have valid authentication credentials for the operation.
200-
*
201-
* @since 0.1.0
202-
*/
203-
UNAUTHENTICATED(16);
56+
/** The operation contains an error. */
57+
ERROR(2);
20458

20559
private final int value;
20660

@@ -225,14 +79,14 @@ public int value() {
22579
* @since 0.1.0
22680
*/
22781
public Status toStatus() {
228-
return STATUS_LIST.get(value);
82+
return STATUSES_BY_VALUE.get(value);
22983
}
23084
}
23185

23286
// Create the canonical list of Status instances indexed by their code values.
233-
private static final List<Status> STATUS_LIST = buildStatusList();
87+
private static final Map<Integer, Status> STATUSES_BY_VALUE = buildStatusList();
23488

235-
private static List<Status> buildStatusList() {
89+
private static Map<Integer, Status> buildStatusList() {
23690
TreeMap<Integer, Status> canonicalizer = new TreeMap<>();
23791
for (CanonicalCode code : CanonicalCode.values()) {
23892
Status replaced = canonicalizer.put(code.value(), new Status(code, null));
@@ -244,133 +98,22 @@ private static List<Status> buildStatusList() {
24498
+ code.name());
24599
}
246100
}
247-
return Collections.unmodifiableList(new ArrayList<>(canonicalizer.values()));
101+
return Collections.unmodifiableMap(canonicalizer);
248102
}
249103

250104
// A pseudo-enum of Status instances mapped 1:1 with values in CanonicalCode. This simplifies
251105
// construction patterns for derived instances of Status.
252106
/**
253-
* The operation completed successfully.
254-
*
255-
* @since 0.1.0
107+
* The operation has been validated by an Application developers or Operator to have completed
108+
* successfully.
256109
*/
257110
public static final Status OK = CanonicalCode.OK.toStatus();
258111

259-
/**
260-
* The operation was cancelled (typically by the caller).
261-
*
262-
* @since 0.1.0
263-
*/
264-
public static final Status CANCELLED = CanonicalCode.CANCELLED.toStatus();
265-
266-
/**
267-
* Unknown error. See {@link CanonicalCode#UNKNOWN}.
268-
*
269-
* @since 0.1.0
270-
*/
271-
public static final Status UNKNOWN = CanonicalCode.UNKNOWN.toStatus();
272-
273-
/**
274-
* Client specified an invalid argument. See {@link CanonicalCode#INVALID_ARGUMENT}.
275-
*
276-
* @since 0.1.0
277-
*/
278-
public static final Status INVALID_ARGUMENT = CanonicalCode.INVALID_ARGUMENT.toStatus();
279-
280-
/**
281-
* Deadline expired before operation could complete. See {@link CanonicalCode#DEADLINE_EXCEEDED}.
282-
*
283-
* @since 0.1.0
284-
*/
285-
public static final Status DEADLINE_EXCEEDED = CanonicalCode.DEADLINE_EXCEEDED.toStatus();
286-
287-
/**
288-
* Some requested entity (e.g., file or directory) was not found.
289-
*
290-
* @since 0.1.0
291-
*/
292-
public static final Status NOT_FOUND = CanonicalCode.NOT_FOUND.toStatus();
293-
294-
/**
295-
* Some entity that we attempted to create (e.g., file or directory) already exists.
296-
*
297-
* @since 0.1.0
298-
*/
299-
public static final Status ALREADY_EXISTS = CanonicalCode.ALREADY_EXISTS.toStatus();
300-
301-
/**
302-
* The caller does not have permission to execute the specified operation. See {@link
303-
* CanonicalCode#PERMISSION_DENIED}.
304-
*
305-
* @since 0.1.0
306-
*/
307-
public static final Status PERMISSION_DENIED = CanonicalCode.PERMISSION_DENIED.toStatus();
308-
309-
/**
310-
* The request does not have valid authentication credentials for the operation.
311-
*
312-
* @since 0.1.0
313-
*/
314-
public static final Status UNAUTHENTICATED = CanonicalCode.UNAUTHENTICATED.toStatus();
315-
316-
/**
317-
* Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system
318-
* is out of space.
319-
*
320-
* @since 0.1.0
321-
*/
322-
public static final Status RESOURCE_EXHAUSTED = CanonicalCode.RESOURCE_EXHAUSTED.toStatus();
323-
324-
/**
325-
* Operation was rejected because the system is not in a state required for the operation's
326-
* execution. See {@link CanonicalCode#FAILED_PRECONDITION}.
327-
*
328-
* @since 0.1.0
329-
*/
330-
public static final Status FAILED_PRECONDITION = CanonicalCode.FAILED_PRECONDITION.toStatus();
331-
332-
/**
333-
* The operation was aborted, typically due to a concurrency issue like sequencer check failures,
334-
* transaction aborts, etc. See {@link CanonicalCode#ABORTED}.
335-
*
336-
* @since 0.1.0
337-
*/
338-
public static final Status ABORTED = CanonicalCode.ABORTED.toStatus();
339-
340-
/**
341-
* Operation was attempted past the valid range. See {@link CanonicalCode#OUT_OF_RANGE}.
342-
*
343-
* @since 0.1.0
344-
*/
345-
public static final Status OUT_OF_RANGE = CanonicalCode.OUT_OF_RANGE.toStatus();
112+
/** The default status. */
113+
public static final Status UNSET = CanonicalCode.UNSET.toStatus();
346114

347-
/**
348-
* Operation is not implemented or not supported/enabled in this service.
349-
*
350-
* @since 0.1.0
351-
*/
352-
public static final Status UNIMPLEMENTED = CanonicalCode.UNIMPLEMENTED.toStatus();
353-
354-
/**
355-
* Internal errors. See {@link CanonicalCode#INTERNAL}.
356-
*
357-
* @since 0.1.0
358-
*/
359-
public static final Status INTERNAL = CanonicalCode.INTERNAL.toStatus();
360-
361-
/**
362-
* The service is currently unavailable. See {@link CanonicalCode#UNAVAILABLE}.
363-
*
364-
* @since 0.1.0
365-
*/
366-
public static final Status UNAVAILABLE = CanonicalCode.UNAVAILABLE.toStatus();
367-
368-
/**
369-
* Unrecoverable data loss or corruption.
370-
*
371-
* @since 0.1.0
372-
*/
373-
public static final Status DATA_LOSS = CanonicalCode.DATA_LOSS.toStatus();
115+
/** The operation contains an error. */
116+
public static final Status ERROR = CanonicalCode.ERROR.toStatus();
374117

375118
// The canonical code of this message.
376119
private final CanonicalCode canonicalCode;
@@ -419,13 +162,22 @@ public String getDescription() {
419162
}
420163

421164
/**
422-
* Returns {@code true} if this {@code Status} is OK, i.e., not an error.
165+
* Returns {@code true} if this {@code Status} is UNSET, i.e., not an error.
423166
*
424-
* @return {@code true} if this {@code Status} is OK.
425-
* @since 0.1.0
167+
* @return {@code true} if this {@code Status} is UNSET.
168+
*/
169+
public boolean isUnset() {
170+
return CanonicalCode.UNSET == canonicalCode;
171+
}
172+
173+
/**
174+
* Returns {@code true} if this {@code Status} is ok, i.e., status is not set, or has been
175+
* overridden to be ok by an operator.
176+
*
177+
* @return {@code true} if this {@code Status} is OK or UNSET.
426178
*/
427179
public boolean isOk() {
428-
return CanonicalCode.OK == canonicalCode;
180+
return isUnset() || CanonicalCode.OK == canonicalCode;
429181
}
430182

431183
/**

0 commit comments

Comments
 (0)