opencensus 0.3.1 → 0.4.0

data/lib/opencensus/trace/span_context.rb

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 module OpenCensus
   module Trace
     ##
@@ -22,30 +23,27 @@ module OpenCensus
     class SpanContext
       ##
       # Internal struct that holds trace-wide data.
-      #
       # @private
       #
-      TraceData = Struct.new :trace_id, :trace_options, :span_map
+      TraceData = Struct.new :trace_id, :span_map
 
       ##
       # Maximum integer value for a `trace_id`
-      #
       # @private
       #
       MAX_TRACE_ID = 0xffffffffffffffffffffffffffffffff
 
       ##
       # Maximum integer value for a `span_id`
-      #
       # @private
       #
       MAX_SPAN_ID = 0xffffffffffffffff
 
       class << self
         ##
-        # Create a new root SpanContext object, given either a Trace-Context
+        # Create a new root SpanContext object, given either a traceparent
         # header value by itself, or an entire Rack environment. If a valid
-        # Trace-Context header can be obtained from either source, it is used
+        # traceparent header can be obtained from either source, it is used
         # to generate the SpanContext. Otherwise, a new root context with a
         # unique `trace_id` and a root `span_id` of "" is used.
         #
@@ -59,15 +57,14 @@ module OpenCensus
         #
         def create_root trace_context: nil, same_process_as_parent: nil
           if trace_context
-            trace_data = TraceData.new \
-              trace_context.trace_id, trace_context.trace_options, {}
+            trace_data = TraceData.new trace_context.trace_id, {}
             new trace_data, nil, trace_context.span_id,
-                same_process_as_parent
+                trace_context.trace_options, same_process_as_parent
           else
             trace_id = rand 1..MAX_TRACE_ID
             trace_id = trace_id.to_s(16).rjust(32, "0")
-            trace_data = TraceData.new trace_id, 0, {}
-            new trace_data, nil, "", nil
+            trace_data = TraceData.new trace_id, {}
+            new trace_data, nil, "", 0, nil
           end
         end
       end
@@ -124,9 +121,7 @@ module OpenCensus
       #
       # @return [Integer]
       #
-      def trace_options
-        @trace_data.trace_options
-      end
+      attr_reader :trace_options
 
       ##
       # The span ID as a 16-character hex string, or the empty string if the
@@ -145,41 +140,41 @@ module OpenCensus
       attr_reader :same_process_as_parent
 
       ##
-      # Whether the context (e.g. the parent span) has been sampled. This
+      # Whether this context (e.g. the parent span) has been sampled. This
       # information may be used in sampling decisions for new spans.
       #
       # @return [boolean]
       #
       def sampled?
-        span = this_span
-        if span
-          span.sampled
-        else
-          trace_options & 0x01 != 0
-        end
+        trace_options & 0x01 != 0
       end
 
       ##
       # Create a new span in this context.
       # You must pass a name for the span. All other span attributes should
-      # be set using the SpanBuilder methods.
+      # be set using {OpenCensus::Trace::SpanBuilder} methods.
       # The span will be started automatically with the current timestamp.
       # However, you are responsible for finishing the span yourself.
       #
-      # @param [String] name Name of the span
-      # @param [Symbol] kind Kind of span. Defaults to unspecified.
-      # @param [Sampler] sampler Span-scoped sampler. If not provided,
-      #     defaults to the trace configuration's default sampler.
+      # @param [String] name Name of the span. Required.
+      # @param [Symbol] kind Kind of span. Optional. Defaults to unspecified.
+      #     Other allowed values are {OpenCensus::Trace::SpanBuilder::SERVER}
+      #     and {OpenCensus::Trace::SpanBuilder::CLIENT}.
+      # @param [Sampler,Boolean,nil] sampler Span-scoped sampler. Optional.
+      #     If provided, the sampler may be a sampler object as defined in the
+      #     {OpenCensus::Trace::Samplers} module docs, or the values `true` or
+      #     `false` as shortcuts for {OpenCensus::Trace::Samplers::AlwaysSample}
+      #     or {OpenCensus::Trace::Samplers::NeverSample}, respectively. If no
+      #     span-scoped sampler is provided, the local parent span's sampling
+      #     decision is used. If there is no local parent span, the configured
+      #     default sampler is used to make a sampling decision.
       #
       # @return [SpanBuilder] A SpanBuilder object that you can use to
       #     set span attributes and create children.
       #
       def start_span name, kind: nil, skip_frames: 0, sampler: nil
-        child_context = create_child
-        sampler ||= OpenCensus::Trace.config.default_sampler
-        sampled = sampler.call span_context: self
-        span = SpanBuilder.new child_context, sampled,
-                               skip_frames: skip_frames + 1
+        child_context = create_child sampler
+        span = SpanBuilder.new child_context, skip_frames: skip_frames + 1
         span.name = name
         span.kind = kind if kind
         span.start!
@@ -189,16 +184,24 @@ module OpenCensus
       ##
       # Create a new span in this context.
       # You must pass a name for the span. All other span attributes should
-      # be set using the SpanBuilder methods.
+      # be set using {OpenCensus::Trace::SpanBuilder} methods.
       #
       # The span will be started automatically with the current timestamp. The
       # SpanBuilder will then be passed to the block you provide. The span will
       # be finished automatically at the end of the block.
       #
-      # @param [String] name Name of the span
-      # @param [Symbol] kind Kind of span. Defaults to unspecified.
-      # @param [Sampler] sampler Span-scoped sampler. If not provided,
-      #     defaults to the trace configuration's default sampler.
+      # @param [String] name Name of the span. Required.
+      # @param [Symbol] kind Kind of span. Optional. Defaults to unspecified.
+      #     Other allowed values are {OpenCensus::Trace::SpanBuilder::SERVER}
+      #     and {OpenCensus::Trace::SpanBuilder::CLIENT}.
+      # @param [Sampler,Boolean,nil] sampler Span-scoped sampler. Optional.
+      #     If provided, the sampler may be a sampler object as defined in the
+      #     {OpenCensus::Trace::Samplers} module docs, or the values `true` or
+      #     `false` as shortcuts for {OpenCensus::Trace::Samplers::AlwaysSample}
+      #     or {OpenCensus::Trace::Samplers::NeverSample}, respectively. If no
+      #     span-scoped sampler is provided, the local parent span's sampling
+      #     decision is used. If there is no local parent span, the configured
+      #     default sampler is used to make a sampling decision.
       #
       def in_span name, kind: nil, skip_frames: 0, sampler: nil
         span = start_span name, kind: kind, skip_frames: skip_frames + 1,
@@ -265,7 +268,7 @@ module OpenCensus
                                 max_links: nil,
                                 max_string_length: nil
         sampled_span_builders = contained_span_builders.find_all do |sb|
-          sb.finished? && sb.sampled
+          sb.finished? && sb.sampled?
         end
         sampled_span_builders.map do |sb|
           sb.to_span max_attributes: max_attributes,
@@ -284,10 +287,12 @@ module OpenCensus
       #
       # @private
       #
-      def initialize trace_data, parent, span_id, same_process_as_parent
+      def initialize trace_data, parent, span_id, trace_options,
+                     same_process_as_parent
         @trace_data = trace_data
         @parent = parent
         @span_id = span_id
+        @trace_options = trace_options
         @same_process_as_parent = same_process_as_parent
       end
 
@@ -327,18 +332,49 @@ module OpenCensus
       ##
       # Create a child of this SpanContext, with a random unique span ID.
       #
+      # @param [Sampler,Boolean,nil] sampler Span-scoped sampler.
       # @return [SpanContext] The created child context.
       #
-      def create_child
+      def create_child sampler
+        sampling_decision = make_sampling_decision sampler
+        child_trace_options = sampling_decision ? 1 : 0
         loop do
           child_span_id = rand 1..MAX_SPAN_ID
           child_span_id = child_span_id.to_s(16).rjust(16, "0")
           unless @trace_data.span_map.key? child_span_id
-            return SpanContext.new @trace_data, self, child_span_id, true
+            return SpanContext.new @trace_data, self, child_span_id,
+                                   child_trace_options, true
           end
         end
       end
 
+      ##
+      # Make a sampling decision in the current context given a span sampler.
+      # Implements the logic specified at:
+      # https://github.com/census-instrumentation/opencensus-specs/blob/master/trace/Sampling.md
+      #
+      # @param [Sampler,Boolean,nil] sampler Span-scoped sampler.
+      # @return [Boolean]
+      #
+      def make_sampling_decision sampler
+        resolved_sampler =
+          case sampler
+          when true
+            OpenCensus::Trace::Samplers::AlwaysSample.new
+          when false
+            OpenCensus::Trace::Samplers::NeverSample.new
+          when nil
+            root? ? OpenCensus::Trace.config.default_sampler : nil
+          else
+            sampler
+          end
+        if resolved_sampler
+          resolved_sampler.call(span_context: self)
+        else
+          sampled?
+        end
+      end
+
       ##
       # Get the SpanBuilder given a Span ID.
       #

data/lib/opencensus/trace/status.rb

@@ -12,17 +12,239 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 module OpenCensus
   module Trace
     ##
     # The `Status` type defines a logical error model that is suitable for
     # different programming environments, including REST APIs and RPC APIs.
-    # This Trace's fields are a subset of those of
-    # [google.rpc.Status](https://github.com/googleapis/googleapis/blob/master/google/rpc/status.Trace),
-    # which is used by [gRPC](https://github.com/grpc).
+    #
     class Status
       ##
-      # The status code.
+      # Not an error; returned on success
+      #
+      # HTTP Mapping: 200 OK
+      #
+      # @return [Integer]
+      #
+      OK = 0
+
+      ##
+      # The operation was cancelled, typically by the caller.
+      #
+      # HTTP Mapping: 499 Client Closed Request
+      #
+      # @return [Integer]
+      #
+      CANCELLED = 1
+
+      ##
+      # Unknown error.  For example, this error may be returned when
+      # 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.
+      #
+      # HTTP Mapping: 500 Internal Server Error
+      #
+      # @return [Integer]
+      #
+      UNKNOWN = 2
+
+      ##
+      # The 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).
+      #
+      # HTTP Mapping: 400 Bad Request
+      #
+      # @return [Integer]
+      #
+      INVALID_ARGUMENT = 3
+
+      ##
+      # The deadline expired before the 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.
+      #
+      # HTTP Mapping: 504 Gateway Timeout
+      #
+      # @return [Integer]
+      #
+      DEADLINE_EXCEEDED = 4
+
+      ##
+      # Some requested entity (e.g., file or directory) was not found.
+      #
+      # Note to server developers: if a request is denied for an entire class
+      # of users, such as gradual feature rollout or undocumented whitelist,
+      # `NOT_FOUND` may be used. If a request is denied for some users within
+      # a class of users, such as user-based access control, `PERMISSION_DENIED`
+      # must be used.
+      #
+      # HTTP Mapping: 404 Not Found
+      #
+      # @return [Integer]
+      #
+      NOT_FOUND = 5
+
+      ##
+      # The entity that a client attempted to create (e.g., file or directory)
+      # already exists.
+      #
+      # HTTP Mapping: 409 Conflict
+      #
+      # @return [Integer]
+      #
+      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). This error code does not imply the
+      # request is valid or the requested entity exists or satisfies
+      # other pre-conditions.
+      #
+      # HTTP Mapping: 403 Forbidden
+      #
+      # @return [Integer]
+      #
+      PERMISSION_DENIED = 7
+
+      ##
+      # Some resource has been exhausted, perhaps a per-user quota, or
+      # perhaps the entire file system is out of space.
+      #
+      # HTTP Mapping: 429 Too Many Requests
+      #
+      # @return [Integer]
+      #
+      RESOURCE_EXHAUSTED = 8
+
+      ##
+      # The operation was rejected because the system is not in a state
+      # required for the operation's execution.  For example, the directory
+      # to be deleted is non-empty, an rmdir operation is applied to
+      # a non-directory, etc.
+      #
+      # Service implementors can use the following guidelines to decide
+      # between `FAILED_PRECONDITION`, `ABORTED`, and `UNAVAILABLE`:
+      #   a. Use `UNAVAILABLE` if the client can retry just the failing call.
+      #   b. Use `ABORTED` if the client should retry at a higher level
+      #      (e.g., when a client-specified test-and-set fails, indicating the
+      #      client should restart a read-modify-write sequence).
+      #   c. 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
+      #      the files are deleted from the directory.
+      #
+      # HTTP Mapping: 400 Bad Request
+      #
+      # @return [Integer]
+      #
+      FAILED_PRECONDITION = 9
+
+      ##
+      # The operation was aborted, typically due to a concurrency issue such as
+      # a sequencer check failure or transaction abort.
+      #
+      # See the guidelines above for deciding between `FAILED_PRECONDITION`,
+      # `ABORTED`, and `UNAVAILABLE`.
+      #
+      # HTTP Mapping: 409 Conflict
+      #
+      # @return [Integer]
+      #
+      ABORTED = 10
+
+      ##
+      # The 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.
+      #
+      # HTTP Mapping: 400 Bad Request
+      #
+      # @return [Integer]
+      #
+      OUT_OF_RANGE = 11
+
+      ##
+      # The operation is not implemented or is not supported/enabled in this
+      # service.
+      #
+      # HTTP Mapping: 501 Not Implemented
+      #
+      # @return [Integer]
+      #
+      UNIMPLEMENTED = 12
+
+      ##
+      # Internal errors.  This means that some invariants expected by the
+      # underlying system have been broken.  This error code is reserved
+      # for serious errors.
+      #
+      # HTTP Mapping: 500 Internal Server Error
+      #
+      # @return [Integer]
+      #
+      INTERNAL = 13
+
+      ##
+      # The service is currently unavailable.  This is most likely a
+      # transient condition, which can be corrected by retrying with
+      # a backoff.
+      #
+      # See the guidelines above for deciding between `FAILED_PRECONDITION`,
+      # `ABORTED`, and `UNAVAILABLE`.
+      #
+      # HTTP Mapping: 503 Service Unavailable
+      #
+      # @return [Integer]
+      #
+      UNAVAILABLE = 14
+
+      ##
+      # Unrecoverable data loss or corruption.
+      #
+      # HTTP Mapping: 500 Internal Server Error
+      #
+      # @return [Integer]
+      #
+      DATA_LOSS = 15
+
+      ##
+      # The request does not have valid authentication credentials for the
+      # operation.
+      #
+      # HTTP Mapping: 401 Unauthorized
+      #
+      # @return [Integer]
+      #
+      UNAUTHENTICATED = 16
+
+      ##
+      # The status code. Allowed values are the Google RPC status codes
+      # defined at https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto
+      # and also provided as constants in this class.
       #
       # @return [Integer]
       #
@@ -36,7 +258,7 @@ module OpenCensus
       attr_reader :message
 
       ##
-      # Create an empty Status object.
+      # Create a Status object.
       #
       # @private
       #