update.

src/core/ext/census/trace_label.h

@@ -36,10 +36,13 @@
 
 #include "src/core/ext/census/trace_string.h"
 
-/* Trace label (key/value pair) stores a label name and the label value. */
+/* Trace label (key/value pair) stores a label name and the label value. The
+   value can be one of trace_string/int64_t/bool. */
 typedef struct trace_label {
   trace_string key;
   enum label_type {
+    /* Unknown value for debugging/error purposes */
+    LABEL_UNKNOWN = 0,
     /* A string value */
     LABEL_STRING = 1,
     /* An integer value. */
@@ -53,7 +56,6 @@ typedef struct trace_label {
     int64_t label_int;
     bool label_bool;
   } value;
-  size_t val_len;
 } trace_label;
 
 #endif

src/core/ext/census/trace_propagation.h

@@ -36,7 +36,7 @@
 
 #include "src/core/ext/census/tracing.h"
 
-/* Encoding and decoding functions for receiving and sending propagating data
+/* Encoding and decoding functions for receiving and sending trace contexts
    over the wire.  Only RPC libraries should be calling these
    functions.  These functions return the number of bytes encoded/decoded
    (0 if a failure has occurred). buf_size indicates the size of the
@@ -44,18 +44,19 @@
    trace ID, span ID, and a set of option flags (is_sampled, etc.). */
 
 /* Converts a span context to a binary byte buffer. */
-size_t trace_span_context_to_binary(const trace_span_context *ctxt, char *buf,
-                                    size_t buf_size);
+size_t trace_span_context_to_binary(const trace_span_context *ctxt,
+                                    uint8_t *buf, size_t buf_size);
 
 /* Reads a binary byte buffer and populates a span context structure. */
-size_t binary_to_trace_span_context(const char *buf, size_t buf_size,
+size_t binary_to_trace_span_context(const uint8_t *buf, size_t buf_size,
                                     trace_span_context *ctxt);
 
-/* Converts a span context to a http format buffer. */
+/* Converts a span context to an http metadata compatible string. */
 size_t trace_span_context_to_http_format(const trace_span_context *ctxt,
                                          char *buf, size_t buf_size);
 
-/* Reads a http format buffer and populates a span context structure. */
+/* Reads an http metadata compatible string and populates a span context
+   structure. */
 size_t http_format_to_trace_span_context(const char *buf, size_t buf_size,
                                          trace_span_context *ctxt);
 

src/core/ext/census/trace_status.h

@@ -38,7 +38,7 @@
 
 /* Stores a status code and status message for a trace. */
 typedef struct trace_status {
-  int errorCode;
+  int64_t errorCode;
   trace_string errorMessage;
 } trace_status;
 

src/core/ext/census/trace_string.h

@@ -42,6 +42,9 @@
    This will also be more efficient when copying, as we have an explicitly
    specified length.  Also, grpc_slice has reference counting which allows for
    interning. */
-typedef struct trace_string { grpc_slice string_slice; } trace_string;
+typedef struct trace_string {
+  char *string;
+  size_t length;
+} trace_string;
 
 #endif

src/core/ext/census/tracing.h

@@ -40,23 +40,31 @@
 #include "src/core/ext/census/trace_label.h"
 #include "src/core/ext/census/trace_status.h"
 
+/* This is the low level tracing API that other languages will interface with.
+   This is not intended to be accessed by the end-user, therefore it has been
+   designed with performance in mind rather than ease of use. */
+
 /* The tracing level. */
 enum TraceLevel {
   /* Annotations on this context will be silently discarded. */
   NO_TRACING = 0,
   /* Annotations will not be saved to a persistent store. They will be
-     available via local APIs only. It is not propagated to the child. */
+     available via local APIs only. This setting is not propagated to child
+     spans. */
   TRANSIENT_TRACING = 1,
   /* Annotations are recorded for the entire distributed trace and they are
-     saved to a persistent store. It is propagated to the child. */
+     saved to a persistent store. This setting is propagated to child spans. */
   PERSISTENT_TRACING = 2,
 };
 
 typedef struct trace_span_context {
   /* Trace span context stores Span ID, Trace ID, and option flags. */
+  /* Trace ID is 128 bits split into 2 64-bit chunks (hi and lo). */
   uint64_t trace_id_hi;
   uint64_t trace_id_lo;
+  /* Span ID is 64 bits. */
   uint64_t span_id;
+  /* Span-options is 32-bit value which contains flag options. */
   uint32_t span_options;
 } trace_span_context;
 
@@ -64,7 +72,10 @@ typedef struct start_span_options {
   /* If set, this will override the Span.local_start_time for the Span. */
   gpr_timespec local_start_timestamp;
 
-  /* If set, the Spans are linked to the created Span. */
+  /* Linked spans can be used to identify spans that are linked to this span in
+     a different trace.  This can be used (for example) in batching operations,
+     where a single batch handler processes multiple requests from different
+     traces. If set, points to a list of Spans are linked to the created Span.*/
   trace_span_context *linked_spans;
   /* The number of linked spans. */
   size_t n_linked_spans;
@@ -79,8 +90,9 @@ void trace_start_span(const trace_span_context *span_ctxt,
                       trace_span_context *new_span_ctxt,
                       bool has_remote_parent);
 
-/* Add a new Annotation to the Span. The description corresponds to
-   Span->annotations[].description. */
+/* Add a new Annotation to the Span. Annotations consist of a description
+   (trace_string) and a set of n labels (trace_label).  This can be populated
+   with arbitrary user data. */
 void trace_add_span_annotation(const trace_string description,
                                const trace_label *labels, const size_t n_labels,
                                trace_span_context *span_ctxt);