opencensus 0.1.0

data/lib/opencensus/trace/exporters.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.
+
+require "opencensus/trace/exporters/logger"
+
+module OpenCensus
+  module Trace
+    ##
+    # The Exporters module provides integrations for exporting collected trace
+    # spans to an external or local service.
+    #
+    module Exporters
+    end
+  end
+end

data/lib/opencensus/trace/exporters/logger.rb

@@ -0,0 +1,149 @@
+# 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 "logger"
+require "json"
+
+module OpenCensus
+  module Trace
+    module Exporters
+      ##
+      # The Logger exporter exports captured spans to a standard Ruby Logger
+      # interface.
+      #
+      class Logger
+        ##
+        # Create a new Logger exporter
+        #
+        # @param [#log] logger The logger to write to.
+        # @param [Symbol] level The log level. This should be a log level
+        #        defined by {https://ruby-doc.org/stdlib-2.5.0/libdoc/logger/rdoc/Logger.html
+        #        Logger Standard Library}.
+        #
+        def initialize logger, level: ::Logger::INFO
+          @logger = logger
+          @level = level
+        end
+
+        ##
+        # Export the captured spans to the configured logger.
+        #
+        # @param [Array<Span>] spans The captured spans.
+        # @return [Boolean]
+        #
+        def export spans
+          @logger.log @level, spans.map { |span| format_span(span) }.to_json
+        end
+
+        private
+
+        def format_span span
+          {
+            name: format_value(span.name),
+            trace_id: span.trace_id,
+            span_id: span.span_id,
+            parent_span_id: span.parent_span_id,
+            start_time: span.start_time,
+            end_time: span.end_time,
+            attributes: format_attributes(span.attributes),
+            dropped_attributes_count: span.dropped_attributes_count,
+            stack_trace: span.stack_trace,
+            dropped_frames_count: span.dropped_frames_count,
+            time_events: span.time_events.map { |te| format_time_event(te) },
+            dropped_annotations_count: span.dropped_annotations_count,
+            dropped_message_events_count: span.dropped_message_events_count,
+            links: span.links.map { |link| format_link(link) },
+            dropped_links_count: span.dropped_links_count,
+            status: format_status(span.status),
+            same_process_as_parent_span: span.same_process_as_parent_span,
+            child_span_count: span.child_span_count
+          }
+        end
+
+        def format_time_event time_event
+          case time_event
+          when Annotation
+            format_annotation time_event
+          when MessageEvent
+            format_message_event time_event
+          end
+        end
+
+        def format_annotation annotation
+          {
+            description: format_value(annotation.description),
+            attributes: format_attributes(annotation.attributes),
+            dropped_attributes_count: annotation.dropped_attributes_count,
+            time: annotation.time
+          }
+        end
+
+        def format_message_event message_event
+          {
+            type: message_event.type,
+            id: message_event.id,
+            uncompressed_size: message_event.uncompressed_size,
+            compressed_size: message_event.compressed_size,
+            time: message_event.time
+          }
+        end
+
+        def format_link link
+          {
+            trace_id: link.trace_id,
+            span_id: link.span_id,
+            type: link.type,
+            attributes: format_attributes(link.attributes),
+            dropped_attributes_count: link.dropped_attributes_count
+          }
+        end
+
+        def format_status status
+          return nil if status.nil?
+
+          {
+            code: status.code,
+            message: status.message
+          }
+        end
+
+        def format_attributes attrs
+          result = {}
+          attrs.each do |k, v|
+            result[k] = format_value v
+          end
+          result
+        end
+
+        def format_value value
+          case value
+          when String, Integer, true, false
+            value
+          when TruncatableString
+            if value.truncated_byte_count.zero?
+              value.value
+            else
+              {
+                value: value.value,
+                truncated_byte_count: value.truncated_byte_count
+              }
+            end
+          else
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/opencensus/trace/formatters.rb

@@ -0,0 +1,29 @@
+# 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/formatters/binary"
+require "opencensus/trace/formatters/cloud_trace"
+require "opencensus/trace/formatters/trace_context"
+
+module OpenCensus
+  module Trace
+    ##
+    # The Formatters module contains several implementations of cross-service
+    # SpanContext propagation. Each formatter can serialize and deserialize a
+    # TraceContextData instance.
+    #
+    module Formatters
+    end
+  end
+end

data/lib/opencensus/trace/formatters/binary.rb

@@ -0,0 +1,66 @@
+# 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
+  module Trace
+    module Formatters
+      ##
+      # This formatter serializes and deserializes span context according to
+      # the OpenCensus' BinaryEncoding specification. See
+      # [documentation](https://github.com/census-instrumentation/opencensus-specs/blob/master/encodings/BinaryEncoding.md).
+      #
+      class Binary
+        ##
+        # Internal format used to (un)pack binary data
+        #
+        # @private
+        #
+        BINARY_FORMAT = "CCH32CH16CC".freeze
+
+        ##
+        # Deserialize a trace context header into a TraceContext object.
+        #
+        # @param [String] binary
+        # @return [TraceContextData, nil]
+        #
+        def deserialize binary
+          data = binary.unpack(BINARY_FORMAT)
+          if data[0].zero? && data[1].zero? && data[3] == 1 && data[5] == 2
+            TraceContextData.new data[2], data[4], data[6]
+          else
+            nil
+          end
+        end
+
+        ##
+        # Serialize a TraceContextData object.
+        #
+        # @param [TraceContextData] trace_context
+        # @return [String]
+        #
+        def serialize trace_context
+          [
+            0, # version
+            0, # field 0
+            trace_context.trace_id,
+            1, # field 1
+            trace_context.span_id,
+            2, # field 2
+            trace_context.trace_options
+          ].pack(BINARY_FORMAT)
+        end
+      end
+    end
+  end
+end

data/lib/opencensus/trace/formatters/cloud_trace.rb

@@ -0,0 +1,102 @@
+# 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
+  module Trace
+    module Formatters
+      ##
+      # This formatter serializes and deserializes span context according to
+      # the Google X-Cloud-Trace header specification.
+      #
+      class CloudTrace
+        ##
+        # Internal regex used to parse fields
+        #
+        # @private
+        #
+        HEADER_FORMAT = %r{([0-9a-fA-F]{32})(?:\/(\d+))?(?:;o=(\d+))?}
+
+        ##
+        # The outgoing header used for the Google Cloud Trace header
+        # specification.
+        #
+        # @private
+        #
+        HEADER_NAME = "X-Cloud-Trace".freeze
+
+        ##
+        # The rack environment header used the the Google Cloud Trace header
+        # specification.
+        #
+        # @private
+        #
+        RACK_HEADER_NAME = "HTTP_X_CLOUD_TRACE".freeze
+
+        ##
+        # Returns the name of the header used for context propagation.
+        #
+        # @return [String]
+        #
+        def header_name
+          HEADER_NAME
+        end
+
+        ##
+        # Returns the name of the rack_environment header to use when parsing
+        # context from an incoming request.
+        #
+        # @return [String]
+        #
+        def rack_header_name
+          RACK_HEADER_NAME
+        end
+
+        ##
+        # Deserialize a trace context header into a TraceContext object.
+        #
+        # @param [String] header
+        # @return [TraceContextData, nil]
+        #
+        def deserialize header
+          match = HEADER_FORMAT.match(header)
+          if match
+            trace_id = match[1].downcase
+            span_id = format("%016x", match[2].to_i)
+            trace_options = match[3].to_i
+            TraceContextData.new trace_id, span_id, trace_options
+          else
+            nil
+          end
+        end
+
+        ##
+        # Serialize a TraceContextData object.
+        #
+        # @param [TraceContextData] trace_context
+        # @return [String]
+        #
+        def serialize trace_context
+          trace_context.trace_id.dup.tap do |ret|
+            if trace_context.span_id
+              ret << "/" << trace_context.span_id.to_i(16).to_s
+            end
+            if trace_context.trace_options
+              ret << ";o=" << trace_context.trace_options.to_s
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/opencensus/trace/formatters/trace_context.rb

@@ -0,0 +1,124 @@
+# 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
+  module Trace
+    module Formatters
+      ##
+      # This formatter serializes and deserializes span context according to
+      # the TraceContext specification. See
+      # [documentation](https://github.com/TraceContext/tracecontext-spec/blob/master/trace_context/HTTP_HEADER_FORMAT.md).
+      #
+      class TraceContext
+        ##
+        # Internal regex used to identify the TraceContext version
+        #
+        # @private
+        #
+        VERSION_PATTERN = /^([0-9a-fA-F]{2})-(.+)$/
+
+        ##
+        # Internal regex used to parse fields in version 0
+        #
+        # @private
+        #
+        HEADER_V0_PATTERN =
+          /^([0-9a-fA-F]{32})-([0-9a-fA-F]{16})(-([0-9a-fA-F]{2}))?$/
+
+        ##
+        # The outgoing header used for the TraceContext header specification.
+        #
+        # @private
+        #
+        HEADER_NAME = "Trace-Context".freeze
+
+        ##
+        # The rack environment header used for the TraceContext header
+        # specification
+        #
+        # @private
+        #
+        RACK_HEADER_NAME = "HTTP_TRACE_CONTEXT".freeze
+
+        ##
+        # Returns the name of the header used for context propagation.
+        #
+        # @return [String]
+        #
+        def header_name
+          HEADER_NAME
+        end
+
+        ##
+        # Returns the name of the rack_environment header to use when parsing
+        # context from an incoming request.
+        #
+        # @return [String]
+        #
+        def rack_header_name
+          RACK_HEADER_NAME
+        end
+
+        ##
+        # Deserialize a trace context header into a TraceContext object.
+        #
+        # @param [String] header
+        # @return [TraceContextData, nil]
+        #
+        def deserialize header
+          match = VERSION_PATTERN.match(header)
+          if match
+            version = match[1].to_i(16)
+            version_format = match[2]
+            case version
+            when 0
+              parse_trace_context_header_version_0 version_format
+            else
+              nil
+            end
+          else
+            nil
+          end
+        end
+
+        ##
+        # Serialize a TraceContextData object.
+        #
+        # @param [TraceContextData] trace_context
+        # @return [String]
+        #
+        def serialize trace_context
+          format(
+            "%02<version>d-%<trace_id>s-%<span_id>s-%02<trace_options>d",
+            version: 0, # version 0,
+            trace_id: trace_context.trace_id,
+            span_id: trace_context.span_id,
+            trace_options: trace_context.trace_options
+          )
+        end
+
+        private
+
+        def parse_trace_context_header_version_0 str
+          match = HEADER_V0_PATTERN.match(str)
+          if match
+            TraceContextData.new match[1].downcase,
+                                 match[2].downcase,
+                                 match[4].to_i(16)
+          end
+        end
+      end
+    end
+  end
+end