Use enum(CanonicalCode) for status->code

CHANGELOG.md

@@ -10,6 +10,7 @@ All notable changes to this project will be documented in this file.
 - Add support for supplying instrumentation configuration via tracing option. Option argument added to instrumentation interface.
 - Add ignoreIncomingPaths and ignoreOutgoingUrls support to the http and https tracing instrumentations.
 - Add ```opencensus-resource-util``` to auto detect AWS, GCE and Kubernetes(K8S) monitored resource, based on the environment where the application is running.
+- Add a ```setStatus``` method in the Span.
 
  **This release has multiple breaking changes. Please test your code accordingly after upgrading.**
 

packages/opencensus-core/src/trace/model/span-base.ts

@@ -18,6 +18,9 @@ import {Clock} from '../../internal/clock';
 import {randomSpanId} from '../../internal/util';
 import * as types from './types';
 
+const STATUS_OK = {
+  code: types.CanonicalCode.OK
+};
 
 /** Defines a base model for spans. */
 export abstract class SpanBase implements types.Span {
@@ -52,7 +55,7 @@ export abstract class SpanBase implements types.Span {
   /** Kind of span. */
   kind: string = null;
   /** A final status for this span */
-  status: types.Status = {code: 0};
+  status: types.Status = STATUS_OK;
   /** set isRootSpan  */
   abstract get isRootSpan(): boolean;
 
@@ -185,14 +188,11 @@ export abstract class SpanBase implements types.Span {
 
   /**
    * Sets a status to the span.
-   * @param code The status code.
+   * @param code The canonical status code.
    * @param message optional A developer-facing error message.
    */
-  setStatus(code: number, message?: string) {
-    this.status.code = code;
-    if (message) {
-      this.status.message = message;
-    }
+  setStatus(code: types.CanonicalCode, message?: string) {
+    this.status = {code, message};
   }
 
   /** Starts the span. */

packages/opencensus-core/src/trace/model/types.ts

@@ -31,16 +31,151 @@ export interface Attributes {
 }
 
 /**
- * The status of a Span by providing a standard code in conjunction
+ * The status of a Span by providing a standard CanonicalCode in conjunction
  * with an optional descriptive message.
  */
 export interface Status {
-  /** The status code. */
-  code: number;
+  /** The canonical code of this message. */
+  code: CanonicalCode;
   /** A developer-facing error message. */
   message?: string;
 }
 
+/** An enumeration of canonical status codes. */
+export enum CanonicalCode {
+  /**
+   * Not an error; returned on success
+   */
+  OK = 0,
+  /**
+   * The operation was cancelled (typically by the caller).
+   */
+  CANCELLED = 1,
+  /**
+   * Unknown error.  An example of where this error may be returned is
+   * if a status value received from another address space belongs to
+   * an error-space that is not known in this address space.  Also
+   * errors raised by APIs that do not return enough error information
+   * may be converted to this error.
+   */
+  UNKNOWN = 2,
+  /**
+   * Client specified an invalid argument.  Note that this differs
+   * from FAILED_PRECONDITION.  INVALID_ARGUMENT indicates arguments
+   * that are problematic regardless of the state of the system
+   * (e.g., a malformed file name).
+   */
+  INVALID_ARGUMENT = 3,
+  /**
+   * Deadline expired before operation could complete.  For operations
+   * that change the state of the system, this error may be returned
+   * even if the operation has completed successfully.  For example, a
+   * successful response from a server could have been delayed long
+   * enough for the deadline to expire.
+   */
+  DEADLINE_EXCEEDED = 4,
+  /**
+   * Some requested entity (e.g., file or directory) was not found.
+   */
+  NOT_FOUND = 5,
+  /**
+   * Some entity that we attempted to create (e.g., file or directory)
+   * already exists.
+   */
+  ALREADY_EXISTS = 6,
+  /**
+   * The caller does not have permission to execute the specified
+   * operation.  PERMISSION_DENIED must not be used for rejections
+   * caused by exhausting some resource (use RESOURCE_EXHAUSTED
+   * instead for those errors).  PERMISSION_DENIED must not be
+   * used if the caller can not be identified (use UNAUTHENTICATED
+   * instead for those errors).
+   */
+  PERMISSION_DENIED = 7,
+  /**
+   * Some resource has been exhausted, perhaps a per-user quota, or
+   * perhaps the entire file system is out of space.
+   */
+  RESOURCE_EXHAUSTED = 8,
+  /**
+   * Operation was rejected because the system is not in a state
+   * required for the operation's execution.  For example, directory
+   * to be deleted may be non-empty, an rmdir operation is applied to
+   * a non-directory, etc.
+   *
+   * A litmus test that may help a service implementor in deciding
+   * between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE:
+   *
+   *  - Use UNAVAILABLE if the client can retry just the failing call.
+   *  - Use ABORTED if the client should retry at a higher-level
+   *    (e.g., restarting a read-modify-write sequence).
+   *  - Use FAILED_PRECONDITION if the client should not retry until
+   *    the system state has been explicitly fixed.  E.g., if an "rmdir"
+   *    fails because the directory is non-empty, FAILED_PRECONDITION
+   *    should be returned since the client should not retry unless
+   *    they have first fixed up the directory by deleting files from it.
+   *  - Use FAILED_PRECONDITION if the client performs conditional
+   *    REST Get/Update/Delete on a resource and the resource on the
+   *    server does not match the condition. E.g., conflicting
+   *    read-modify-write on the same resource.
+   */
+  FAILED_PRECONDITION = 9,
+  /**
+   * The operation was aborted, typically due to a concurrency issue
+   * like sequencer check failures, transaction aborts, etc.
+   *
+   * See litmus test above for deciding between FAILED_PRECONDITION,
+   * ABORTED, and UNAVAILABLE.
+   */
+  ABORTED = 10,
+  /**
+   * Operation was attempted past the valid range.  E.g., seeking or
+   * reading past end of file.
+   *
+   * Unlike INVALID_ARGUMENT, this error indicates a problem that may
+   * be fixed if the system state changes. For example, a 32-bit file
+   * system will generate INVALID_ARGUMENT if asked to read at an
+   * offset that is not in the range [0,2^32-1], but it will generate
+   * OUT_OF_RANGE if asked to read from an offset past the current
+   * file size.
+   *
+   * There is a fair bit of overlap between FAILED_PRECONDITION and
+   * OUT_OF_RANGE.  We recommend using OUT_OF_RANGE (the more specific
+   * error) when it applies so that callers who are iterating through
+   * a space can easily look for an OUT_OF_RANGE error to detect when
+   * they are done.
+   */
+  OUT_OF_RANGE = 11,
+  /**
+   * Operation is not implemented or not supported/enabled in this service.
+   */
+  UNIMPLEMENTED = 12,
+  /**
+   * Internal errors.  Means some invariants expected by underlying
+   * system has been broken.  If you see one of these errors,
+   * something is very broken.
+   */
+  INTERNAL = 13,
+  /**
+   * The service is currently unavailable.  This is a most likely a
+   * transient condition and may be corrected by retrying with
+   * a backoff.
+   *
+   * See litmus test above for deciding between FAILED_PRECONDITION,
+   * ABORTED, and UNAVAILABLE.
+   */
+  UNAVAILABLE = 14,
+  /**
+   * Unrecoverable data loss or corruption.
+   */
+  DATA_LOSS = 15,
+  /**
+   * The request does not have valid authentication credentials for the
+   * operation.
+   */
+  UNAUTHENTICATED = 16,
+}
+
 /** A text annotation with a set of attributes. */
 export interface Annotation {
   /** A user-supplied message describing the event. */
@@ -215,10 +350,10 @@ export interface Span {
 
   /**
    * Sets a status to the span.
-   * @param code The status code.
+   * @param code The canonical status code.
    * @param message optional A developer-facing error message.
    */
-  setStatus(code: number, message?: string): void;
+  setStatus(code: CanonicalCode, message?: string): void;
 
   /** Starts a span. */
   start(): void;

packages/opencensus-core/test/test-span.ts

@@ -262,7 +262,7 @@ describe('Span', () => {
   /**
    * Should set a status
    */
-  describe('addStatus()', () => {
+  describe('setStatus()', () => {
     it('should return default status', () => {
       const rootSpan = new RootSpan(tracer);
       rootSpan.start();
@@ -281,11 +281,11 @@ describe('Span', () => {
       rootSpan.start();
       const span = new Span(rootSpan);
       span.start();
-      span.setStatus(400, 'This is an error');
+      span.setStatus(types.CanonicalCode.PERMISSION_DENIED, 'This is an error');
 
       assert.equal(rootSpan.status.code, 0);
       assert.equal(rootSpan.status.message, null);
-      assert.equal(span.status.code, 400);
+      assert.equal(span.status.code, 7);
       assert.equal(span.status.message, 'This is an error');
     });
   });

packages/opencensus-exporter-ocagent/src/adapters.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import {Annotation, Attributes, Link, MessageEvent, RootSpan, Span, Status} from '@opencensus/core';
+import {Annotation, Attributes, Link, MessageEvent, RootSpan, Span} from '@opencensus/core';
 
 import {google, opencensus} from './types';
 

packages/opencensus-exporter-ocagent/test/test-ocagent.ts

@@ -15,7 +15,7 @@
  */
 
 import * as protoLoader from '@grpc/proto-loader';
-import {RootSpan, TraceOptions, Tracing} from '@opencensus/core';
+import {CanonicalCode, RootSpan, TraceOptions, Tracing} from '@opencensus/core';
 import * as nodeTracing from '@opencensus/nodejs';
 import * as assert from 'assert';
 import {EventEmitter} from 'events';
@@ -328,7 +328,7 @@ describe('OpenCensus Agent Exporter', () => {
 
     tracing.tracer.startRootSpan(rootSpanOptions, (rootSpan: RootSpan) => {
       // Status
-      rootSpan.setStatus(200);
+      rootSpan.setStatus(CanonicalCode.OK);
 
       // Attribute
       rootSpan.addAttribute('my_attribute_string', 'bar2');
@@ -388,7 +388,7 @@ describe('OpenCensus Agent Exporter', () => {
             if (!span.status) {
               assert.fail('span.status is null or undefined');
             } else {
-              assert.deepEqual(span.status, {code: 200, message: ''});
+              assert.deepEqual(span.status, {code: 0, message: ''});
             }
 
             // Attributes

packages/opencensus-instrumentation-grpc/src/grpc.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import {BasePlugin, HeaderGetter, HeaderSetter, PluginInternalFiles, RootSpan, Span} from '@opencensus/core';
+import {BasePlugin, CanonicalCode, HeaderGetter, HeaderSetter, PluginInternalFiles, RootSpan, Span} from '@opencensus/core';
 import {EventEmitter} from 'events';
 import * as grpcTypes from 'grpc';
 import * as lodash from 'lodash';
@@ -227,8 +227,7 @@ export class GrpcPlugin extends BasePlugin {
         rootSpan.addAttribute(
             GrpcPlugin.ATTRIBUTE_GRPC_ERROR_MESSAGE, err.message);
       } else {
-        rootSpan.setStatus(
-            GrpcPlugin.convertGrpcStatusToSpanStatus(grpcTypes.status.OK));
+        rootSpan.setStatus(CanonicalCode.OK);
         rootSpan.addAttribute(
             GrpcPlugin.ATTRIBUTE_GRPC_STATUS_CODE,
             grpcTypes.status.OK.toString());
@@ -268,8 +267,6 @@ export class GrpcPlugin extends BasePlugin {
     });
 
     call.on('error', (err: grpcTypes.ServiceError) => {
-      rootSpan.setStatus(
-          GrpcPlugin.convertGrpcStatusToSpanStatus(err.code), err.message);
       rootSpan.addAttribute(GrpcPlugin.ATTRIBUTE_GRPC_ERROR_NAME, err.name);
       rootSpan.addAttribute(
           GrpcPlugin.ATTRIBUTE_GRPC_ERROR_MESSAGE, err.message);
@@ -362,8 +359,7 @@ export class GrpcPlugin extends BasePlugin {
           span.addAttribute(
               GrpcPlugin.ATTRIBUTE_GRPC_ERROR_MESSAGE, err.message);
         } else {
-          span.setStatus(
-              GrpcPlugin.convertGrpcStatusToSpanStatus(grpcTypes.status.OK));
+          span.setStatus(CanonicalCode.OK);
           span.addAttribute(
               GrpcPlugin.ATTRIBUTE_GRPC_STATUS_CODE,
               grpcTypes.status.OK.toString());
@@ -417,8 +413,6 @@ export class GrpcPlugin extends BasePlugin {
         let spanEnded = false;
         call.on('error', (err: grpcTypes.ServiceError) => {
           // span.status = plugin.traceStatus(err.code);
-          span.setStatus(
-              GrpcPlugin.convertGrpcStatusToSpanStatus(err.code), err.message);
           span.addAttribute(GrpcPlugin.ATTRIBUTE_GRPC_ERROR_NAME, err.name);
           span.addAttribute(
               GrpcPlugin.ATTRIBUTE_GRPC_ERROR_MESSAGE, err.message);

packages/opencensus-instrumentation-grpc/test/test-grpc.ts

@@ -339,7 +339,6 @@ describe('GrpcPlugin() ', function() {
     if (status !== grpcModule.status.OK) {
       assert.ok(span.attributes[GrpcPlugin.ATTRIBUTE_GRPC_ERROR_NAME]);
       assert.ok(span.attributes[GrpcPlugin.ATTRIBUTE_GRPC_ERROR_MESSAGE]);
-      assert.ok(span.status.message);
     } else {
       assert.equal(span.status.message, undefined);
     }