opencensus 0.1.0

data/lib/opencensus/config.rb

@@ -0,0 +1,54 @@
+# Copyright 2017 OpenCensus Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# 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/common/config"
+
+module OpenCensus
+  # The OpenCensus overall configuration.
+  @config = Common::Config.new
+
+  class << self
+    ##
+    # Configure OpenCensus. Most configuration parameters are part of
+    # subconfigurations that live under this main configuration.
+    #
+    # If the OpenCensus Railtie is installed in a Rails application, the
+    # toplevel configuration object is also exposed as `config.opencensus`.
+    #
+    # Generally, you should configure this once at process initialization,
+    # but it can be modified at any time.
+    #
+    # Example:
+    #
+    #     OpenCensus.configure do |config|
+    #       config.trace.default_sampler =
+    #         OpenCensus::Trace::Samplers::AlwaysSample.new
+    #       config.trace.default_max_attributes = 16
+    #     end
+    #
+    def configure
+      if block_given?
+        yield @config
+      else
+        @config
+      end
+    end
+
+    ##
+    # Get the current configuration.
+    # @private
+    #
+    attr_reader :config
+  end
+end

data/lib/opencensus/context.rb

@@ -0,0 +1,72 @@
+# Copyright 2017 OpenCensus Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# 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.
+
+module OpenCensus
+  ##
+  # The Context module provides per-thread storage.
+  #
+  module Context
+    ##
+    # Thread local storage key under which all OpenCensus context data is
+    # stored.
+    #
+    # @private
+    #
+    THREAD_KEY = :__opencensus_context__
+
+    class << self
+      ##
+      # Store a value in the context.
+      #
+      # @param [String, Symbol] key The name of the context value to store.
+      # @param [Object] value The value associated with the key.
+      def set key, value
+        storage[key] = value
+      end
+
+      ##
+      # Return a value from the context. Returns nil if no value is set.
+      #
+      # @param [String, Symbol] key The name of the context value to fetch.
+      # @return [Object, nil] The fetched value.
+      #
+      def get key
+        storage[key]
+      end
+
+      ##
+      # Unsets a value from the context.
+      #
+      # @param [String, Symbol] key The name of the context value to unset.
+      # @return [Object, nil] The value of the context value just unset.
+      #
+      def unset key
+        storage.delete key
+      end
+
+      ##
+      # Clears all values from the context.
+      #
+      def reset!
+        Thread.current[THREAD_KEY] = {}
+      end
+
+      private
+
+      def storage
+        Thread.current[THREAD_KEY] ||= {}
+      end
+    end
+  end
+end

data/lib/opencensus/stats.rb

@@ -0,0 +1,26 @@
+# Copyright 2017 OpenCensus Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# 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.
+
+module OpenCensus
+  ##
+  # The Stats module contains support for OpenCensus stats collection.
+  #
+  # OpenCensus allows users to create typed measures, record measurements,
+  # aggregate the collected data, and export the aggregated data.
+  #
+  # TODO: implement stats
+  #
+  module Stats
+  end
+end

data/lib/opencensus/tags.rb

@@ -0,0 +1,25 @@
+# Copyright 2017 OpenCensus Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# 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.
+
+module OpenCensus
+  ##
+  # The Tags module contains support for OpenCensus tags. Tags are key-value
+  # pairs. Tags provide additional cardinality to the OpenCensus instrumentation
+  # data.
+  #
+  # TODO: implement tags
+  #
+  module Tags
+  end
+end

data/lib/opencensus/trace.rb

@@ -0,0 +1,181 @@
+# Copyright 2017 OpenCensus Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# 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/trace/annotation"
+require "opencensus/trace/config"
+require "opencensus/trace/exporters"
+require "opencensus/trace/formatters"
+require "opencensus/trace/integrations"
+require "opencensus/trace/link"
+require "opencensus/trace/message_event"
+require "opencensus/trace/samplers"
+require "opencensus/trace/span_builder"
+require "opencensus/trace/span_context"
+require "opencensus/trace/span"
+require "opencensus/trace/status"
+require "opencensus/trace/trace_context_data"
+require "opencensus/trace/truncatable_string"
+
+module OpenCensus
+  ##
+  # # OpenCensus Trace API
+  #
+  # This is a Ruby implementation of OpenCensus Trace, providing a common API
+  # for latency trace tools.
+  #
+  module Trace
+    ##
+    # Internal key for storing the current SpanContext in the thread local
+    # Context
+    #
+    # @private
+    #
+    SPAN_CONTEXT_KEY = :__span_context__
+
+    class << self
+      ##
+      # Sets the current thread-local SpanContext, which governs the behavior
+      # of the span creation class methods of OpenCensus::Trace.
+      #
+      # @param [SpanContext] span_context
+      #
+      def span_context= span_context
+        OpenCensus::Context.set SPAN_CONTEXT_KEY, span_context
+      end
+
+      ##
+      # Unsets the current thread-local SpanContext, disabling span creation
+      # class methods of OpenCensus::Trace
+      #
+      def unset_span_context
+        OpenCensus::Context.unset SPAN_CONTEXT_KEY
+      end
+
+      ##
+      # Returns the current thread-local SpanContext, which governs the
+      # behavior of the span creation class methods of OpenCensus::Trace.
+      # Returns `nil` if there is no current SpanContext.
+      #
+      # @return [SpanContext, nil]
+      #
+      def span_context
+        OpenCensus::Context.get SPAN_CONTEXT_KEY
+      end
+
+      ##
+      # 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
+      # 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
+      # SpanContext. You must then call `unset_span_context` yourself at the
+      # end of the request
+      #
+      # @param [TraceContextData] trace_context The request's incoming trace
+      #      context (optional)
+      #
+      def start_request_trace trace_context: nil
+        span_context = SpanContext.create_root trace_context: trace_context
+        self.span_context = span_context
+        if block_given?
+          begin
+            yield span_context
+          ensure
+            unset_span_context
+          end
+        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.
+      #
+      # 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.
+      #
+      # You should always match `start_span` calls with a corresponding call to
+      # `end_span`, which finishes the span and updates the SpanContext
+      # 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 [Sampler] sampler Span-scoped sampler. If not provided,
+      #     defaults to the trace configuration's default sampler.
+      #
+      # @return [SpanBuilder] A SpanBuilder object that you can use to
+      #     set span attributes and create children.
+      #
+      def start_span name, skip_frames: 0, sampler: nil
+        context = span_context
+        raise "No currently active span context" unless context
+        span = context.start_span name, skip_frames: skip_frames + 1,
+                                        sampler: sampler
+        self.span_context = span.context
+        span
+      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.
+      #
+      # 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 [Sampler] sampler Span-scoped sampler. If not provided,
+      #     defaults to the trace configuration's default sampler.
+      #
+      def in_span name, skip_frames: 0, sampler: nil
+        span = start_span name, skip_frames: skip_frames + 1, sampler: sampler
+        begin
+          yield span
+        ensure
+          end_span span
+        end
+      end
+
+      ##
+      # Finish the given span, which must be the span that created the
+      # current thread-local SpanContext. Also updates the thread-local
+      # SpanContext so subsequent calls no longer create subspans of the
+      # finished span.
+      #
+      # @param [SpanBuilder] span The expected currently active span to finish.
+      #
+      def end_span span
+        context = span_context
+        raise "No currently active span context" unless context
+        unless span.equal? context.this_span
+          raise "The given span doesn't match the currently active span"
+        end
+        span.finish!
+        self.span_context = context.parent
+        span
+      end
+    end
+  end
+end

data/lib/opencensus/trace/annotation.rb

@@ -0,0 +1,60 @@
+# Copyright 2017 OpenCensus Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# 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/trace/time_event"
+
+module OpenCensus
+  module Trace
+    ##
+    # A text annotation with a set of attributes.
+    #
+    class Annotation < TimeEvent
+      ##
+      # A user-supplied message describing the event.
+      #
+      # @return [TruncatableString]
+      #
+      attr_reader :description
+
+      ##
+      # A set of attributes on the annotation.
+      #
+      # @return [Hash<String, (TruncatableString, Integer, Boolean)>]
+      #
+      attr_reader :attributes
+
+      ##
+      # The number of attributes that were discarded. Attributes can be
+      # discarded because their keys are too long or because there are too
+      # many attributes. If this value is 0, then no attributes were dropped.
+      #
+      # @return [Integer]
+      #
+      attr_reader :dropped_attributes_count
+
+      ##
+      # Create an Annotation object.
+      #
+      # @private
+      #
+      def initialize description, attributes: {}, dropped_attributes_count: 0,
+                     time: nil
+        super time: time
+        @description = description
+        @attributes = attributes
+        @dropped_attributes_count = dropped_attributes_count
+      end
+    end
+  end
+end

data/lib/opencensus/trace/config.rb

@@ -0,0 +1,119 @@
+# Copyright 2017 OpenCensus Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# 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/trace/exporters"
+require "opencensus/trace/formatters"
+require "opencensus/trace/samplers"
+
+module OpenCensus
+  module Trace
+    # Schema of the Trace configuration. See Trace#configure for more info.
+    @config = Common::Config.new do |config|
+      default_sampler =
+        Samplers::Probability.new Samplers::Probability::DEFAULT_RATE
+      config.add_option! :default_sampler, default_sampler do |value|
+        value.respond_to? :call
+      end
+      default_exporter =
+        Exporters::Logger.new ::Logger.new(STDOUT, ::Logger::INFO)
+      config.add_option! :exporter, default_exporter do |value|
+        value.respond_to? :export
+      end
+      default_formatter =
+        Formatters::TraceContext.new
+      config.add_option! :http_formatter, default_formatter do |value|
+        value.respond_to?(:serialize) &&
+          value.respond_to?(:deserialize) &&
+          value.respond_to?(:header_name) &&
+          value.respond_to?(:rack_header_name)
+      end
+      config.add_option! :default_max_attributes, 32
+      config.add_option! :default_max_stack_frames, 32
+      config.add_option! :default_max_annotations, 32
+      config.add_option! :default_max_message_events, 128
+      config.add_option! :default_max_links, 128
+      config.add_option! :default_max_string_length, 1024
+    end
+
+    # Expose the trace config as a subconfig under the main config.
+    OpenCensus.configure do |config|
+      config.add_alias! :trace, config: @config
+    end
+
+    class << self
+      ##
+      # Configure OpenCensus Trace. These configuration fields include
+      # parameters governing sampling, span creation, and exporting.
+      #
+      # This configuration is also available as the `trace` subconfig under the
+      # main configuration `OpenCensus.configure`. If the OpenCensus Railtie is
+      # installed in a Rails application, the configuration object is also
+      # exposed as `config.opencensus.trace`.
+      #
+      # Generally, you should configure this once at process initialization,
+      # but it can be modified at any time.
+      #
+      # Example:
+      #
+      #     OpenCensus::Trace.configure do |config|
+      #       config.default_sampler =
+      #         OpenCensus::Trace::Samplers::AlwaysSample.new
+      #       config.default_max_attributes = 16
+      #     end
+      #
+      # Supported fields are:
+      #
+      # *   `default_sampler` The default sampler to use. Must be a sampler,
+      #     an object with a `call` method that takes a single options hash.
+      #     See OpenCensus::Trace::Samplers. The initial value is a Probability
+      #     sampler with a default rate.
+      # *   `exporter` The exporter to use. Must be an exporter, an object with
+      #     an export method that takes an array of Span objects. See
+      #     OpenCensus::Trace::Exporters. The initial value is a Logger exporter
+      #     that logs to STDOUT.
+      # *   `http_formatter` The trace context propagation formatter to use.
+      #     Must be a formatter, an object with `serialize`, `deserialize`,
+      #     `header_name`, and `rack_header_name` methods. See
+      #     OpenCensus::Trace::Formatter. The initial value is a TraceContext
+      #     formatter.
+      # *   `default_max_attributes` The maximum number of attributes to add to
+      #     a span. Initial value is 32. Use 0 for no maximum.
+      # *   `default_max_stack_frames` The maximum number of stack frames to
+      #     represent in a span's stack trace. Initial value is 32. Use 0 for
+      #     no maximum.
+      # *   `default_max_annotations` The maximum number of annotations to add
+      #     to a span. Initial value is 32. Use 0 for no maximum.
+      # *   `default_max_message_events` The maximum number of message events
+      #     to add to a span. Initial value is 128. Use 0 for no maximum.
+      # *   `default_max_links` The maximum number of links to add to a span.
+      #     Initial value is 128. Use 0 for no maximum.
+      # *   `default_max_string_length` The maximum length of string fields.
+      #     Initial value is 1024. Use 0 for no maximum.
+      #
+      def configure
+        if block_given?
+          yield @config
+        else
+          @config
+        end
+      end
+
+      ##
+      # Get the current configuration
+      # @private
+      #
+      attr_reader :config
+    end
+  end
+end