trace.rb in opencensus-0.4.0

- old
+ new

@@ -10,10 +10,12 @@
 # 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.
 
+
+require "opencensus/context"
 require "opencensus/trace/annotation"
 require "opencensus/trace/config"
 require "opencensus/trace/exporters"
 require "opencensus/trace/formatters"
 require "opencensus/trace/integrations"
@@ -75,11 +77,11 @@
 
       ##
       # Starts tracing a request in the current thread, by creating a new
       # SpanContext and setting it as the current thread-local context.
       # Generally you should call this when beginning the handling of a
-      # request. If there is a rack environment or a provided Trace-Context
+      # request. If there is a rack environment or a provided traceparent
       # header, pass it in so the SpanContext is constructed accordingly.
       #
       # If you pass a block, this method will yield the SpanContext to the
       # block. When the block finishes, the span context will automatically
       # be unset. If you do not pass a block, this method will return the
@@ -101,17 +103,19 @@
           begin
             yield span_context
           ensure
             unset_span_context
           end
+        else
+          span_context
         end
       end
 
       ##
       # Create a new span in the current thread-local 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.
       # Furthermore, the current thread-local SpanContext will be updated so
       # subsequent calls to `start_span` will create spans within the new span.
@@ -121,14 +125,22 @@
       # accordingly. If you want this done automatically, consider using
       # the `in_span` method.
       #
       # Will throw an exception if there is no current SpanContext.
       #
-      # @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
@@ -142,21 +154,29 @@
       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. The
       # SpanBuilder will then be passed to the block you provide. The span will
       # be finished automatically at the end of the block. Within the block,
       # the thread-local SpanContext will be updated so calls to `start_span`
       # will create subspans.
       #
-      # @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,
                                 sampler: sampler
         begin