opentelemetry-api 0.5.1

data/lib/opentelemetry/trace/span_context.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Trace
+    # A SpanContext contains the state that must propagate to child {Span}s and across process boundaries.
+    # It contains the identifiers (a trace ID and span ID) associated with the {Span}, a set of
+    # {TraceFlags}, a system-specific tracestate, and a boolean indicating that the SpanContext was
+    # extracted from the wire.
+    class SpanContext
+      attr_reader :trace_id, :span_id, :trace_flags, :tracestate
+
+      # Returns a new {SpanContext}.
+      #
+      # @param [optional String] trace_id The trace ID associated with a {Span}.
+      # @param [optional String] span_id The span ID associated with a {Span}.
+      # @param [optional TraceFlags] trace_flags The trace flags associated with a {Span}.
+      # @param [optional String] tracestate The tracestate associated with a {Span}. May be nil.
+      # @param [optional Boolean] remote Whether the {SpanContext} was extracted from the wire.
+      # @return [SpanContext]
+      def initialize(
+        trace_id: Trace.generate_trace_id,
+        span_id: Trace.generate_span_id,
+        trace_flags: TraceFlags::DEFAULT,
+        tracestate: nil,
+        remote: false
+      )
+        @trace_id = trace_id
+        @span_id = span_id
+        @trace_flags = trace_flags
+        @tracestate = tracestate
+        @remote = remote
+      end
+
+      # Returns true if the {SpanContext} has a non-zero trace ID and non-zero span ID.
+      #
+      # @return [Boolean]
+      def valid?
+        @trace_id != INVALID_TRACE_ID && @span_id != INVALID_SPAN_ID
+      end
+
+      # Returns true if the {SpanContext} was propagated from a remote parent.
+      #
+      # @return [Boolean]
+      def remote?
+        @remote
+      end
+
+      # Represents an invalid {SpanContext}, with an invalid trace ID and an invalid span ID.
+      INVALID = new(trace_id: INVALID_TRACE_ID, span_id: INVALID_SPAN_ID)
+    end
+  end
+end

data/lib/opentelemetry/trace/span_kind.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Trace
+    # Type of span. Can be used to specify additional relationships between spans in addition to a
+    # parent/child relationship. For API ergonomics, use of the symbols rather than the constants
+    # may be preferred. For example:
+    #
+    #   span = tracer.start_span('op', kind: :client)
+    module SpanKind
+      # Default value. Indicates that the span is used internally.
+      INTERNAL = :internal
+
+      # Indicates that the span covers server-side handling of an RPC or other remote request.
+      SERVER = :server
+
+      # Indicates that the span covers the client-side wrapper around an RPC or other remote request.
+      CLIENT = :client
+
+      # Indicates that the span describes producer sending a message to a broker. Unlike client and
+      # server, there is no direct critical path latency relationship between producer and consumer
+      # spans.
+      PRODUCER = :producer
+
+      # Indicates that the span describes consumer recieving a message from a broker. Unlike client
+      # and server, there is no direct critical path latency relationship between producer and
+      # consumer spans.
+      CONSUMER = :consumer
+    end
+  end
+end

data/lib/opentelemetry/trace/status.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require 'opentelemetry/trace/util/http_to_status'
+
+module OpenTelemetry
+  module Trace
+    # Status represents the status of a finished {Span}. It is composed of a
+    # canonical code in conjunction with an optional descriptive message.
+    class Status
+      # Convenience utility, not in API spec:
+      extend Util::HttpToStatus
+
+      # Retrieve the canonical code of this Status.
+      #
+      # @return [Integer]
+      attr_reader :canonical_code
+
+      # Retrieve the description of this Status.
+      #
+      # @return [String]
+      attr_reader :description
+
+      # Initialize a Status.
+      #
+      # @param [Integer] canonical_code One of the standard gRPC codes: https://github.com/grpc/grpc/blob/master/doc/statuscodes.md
+      # @param [String] description
+      def initialize(canonical_code, description: '')
+        @canonical_code = canonical_code
+        @description = description
+      end
+
+      # Returns false if this {Status} represents an error, else returns true.
+      #
+      # @return [Boolean]
+      def ok?
+        @canonical_code == OK
+      end
+
+      # The following represents the canonical set of status codes of a
+      # finished {Span}, following the standard gRPC codes:
+      # https://github.com/grpc/grpc/blob/master/doc/statuscodes.md
+
+      # The operation completed successfully.
+      OK = 0
+
+      # The operation was cancelled (typically by the caller).
+      CANCELLED = 1
+
+      # An unknown error.
+      UNKNOWN_ERROR = 2
+
+      # 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.
+      INVALID_ARGUMENT = 3
+
+      # Deadline expired before operation could complete. For operations that
+      # change the state of the system, this error may be returned even if the
+      # operation has completed successfully.
+      DEADLINE_EXCEEDED = 4
+
+      # Some requested entity (e.g., file or directory) was not found.
+      NOT_FOUND = 5
+
+      # Some entity that we attempted to create (e.g., file or directory)
+      # already exists.
+      ALREADY_EXISTS = 6
+
+      # The caller does not have permission to execute the specified operation.
+      # {PERMISSION_DENIED} must not be used if the caller cannot be identified
+      # (use {UNAUTHENTICATED} instead for those errors).
+      PERMISSION_DENIED = 7
+
+      # Some resource has been exhausted, perhaps a per-user quota, or perhaps
+      # the entire file system is out of space.
+      RESOURCE_EXHAUSTED = 8
+
+      # Operation was rejected because the system is not in a state required
+      # for the operation's execution.
+      FAILED_PRECONDITION = 9
+
+      # The operation was aborted, typically due to a concurrency issue like
+      # sequencer check failures, transaction aborts, etc.
+      ABORTED = 10
+
+      # 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.
+      OUT_OF_RANGE = 11
+
+      # Operation is not implemented or not supported/enabled in this service.
+      UNIMPLEMENTED = 12
+
+      # Internal errors. Means some invariants expected by underlying system
+      # has been broken.
+      INTERNAL_ERROR = 13
+
+      # The service is currently unavailable. This is a most likely a transient
+      # condition and may be corrected by retrying with a backoff.
+      UNAVAILABLE = 14
+
+      # Unrecoverable data loss or corruption.
+      DATA_LOSS = 15
+
+      # The request does not have valid authentication credentials for the
+      # operation.
+      UNAUTHENTICATED = 16
+    end
+  end
+end

data/lib/opentelemetry/trace/trace_flags.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Trace
+    # TraceFlags contain details about the trace. Unlike Tracestate values,
+    # TraceFlags are present in all traces. Currently, the only TraceFlag is a
+    # boolean {sampled?} {https://www.w3.org/TR/trace-context/#trace-flags flag}.
+    class TraceFlags
+      class << self
+        private :new # rubocop:disable Style/AccessModifierDeclarations
+
+        # Returns a newly created {TraceFlags} with the specified flags.
+        #
+        # @param [Integer] flags 8-bit byte of bit flags
+        # @return [TraceFlags]
+        def from_byte(flags)
+          flags = 0 unless flags & ~0xFF == 0 # rubocop:disable Style/NumericPredicate
+
+          new(flags)
+        end
+      end
+
+      # @api private
+      # The constructor is private and only for use internally by the class.
+      # Users should use the {from_byte} factory method to obtain a {TraceFlags}
+      # instance.
+      #
+      # @param [Integer] flags 8-bit byte of bit flags
+      # @return [TraceFlags]
+      def initialize(flags)
+        @flags = flags
+      end
+
+      # Returns whether the caller may have recorded trace data. When false,
+      # the caller did not record trace data out-of-band.
+      #
+      # @return [Boolean]
+      def sampled?
+        (@flags & 1) != 0
+      end
+
+      DEFAULT = from_byte(0)
+      SAMPLED = from_byte(1)
+    end
+  end
+end

data/lib/opentelemetry/trace/tracer.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Trace
+    # No-op implementation of Tracer.
+    class Tracer
+      EXTRACTED_SPAN_CONTEXT_KEY = Propagation::ContextKeys.extracted_span_context_key
+      CURRENT_SPAN_KEY = Propagation::ContextKeys.current_span_key
+
+      private_constant :EXTRACTED_SPAN_CONTEXT_KEY, :CURRENT_SPAN_KEY
+
+      # Returns the current span from the current or provided context
+      #
+      # @param [optional Context] context The context to lookup the current
+      #   {Span} from. Defaults to Context.current
+      def current_span(context = Context.current)
+        context.value(CURRENT_SPAN_KEY) || Span::INVALID
+      end
+
+      # Returns the the active span context from the given {Context}, or current
+      # if one is not explicitly passed in. The active span context may refer to
+      # a {SpanContext} that has been extracted. If both a current {Span} and an
+      # extracted, {SpanContext} exist, the context of the current {Span} will be
+      # returned.
+      #
+      # @param [optional Context] context The context to lookup the active
+      #   {SpanContext} from.
+      #
+      def active_span_context(context = nil)
+        context ||= Context.current
+        context.value(CURRENT_SPAN_KEY)&.context ||
+          context.value(EXTRACTED_SPAN_CONTEXT_KEY) ||
+          SpanContext::INVALID
+      end
+
+      # This is a helper for the default use-case of extending the current trace with a span.
+      #
+      # With this helper:
+      #
+      #   OpenTelemetry.tracer.in_span('do-the-thing') do ... end
+      #
+      # Equivalent without helper:
+      #
+      #   OpenTelemetry.tracer.with_span(OpenTelemetry.tracer.start_span('do-the-thing')) do ... end
+      #
+      # On exit, the Span that was active before calling this method will be reactivated. If an
+      # exception occurs during the execution of the provided block, it will be recorded on the
+      # span and reraised.
+      # @yield [span, context] yields the newly created span and a context containing the
+      #   span to the block.
+      def in_span(name, attributes: nil, links: nil, start_timestamp: nil, kind: nil, with_parent: nil, with_parent_context: nil)
+        span = start_span(name, attributes: attributes, links: links, start_timestamp: start_timestamp, kind: kind, with_parent: with_parent, with_parent_context: with_parent_context)
+        with_span(span) { |s, c| yield s, c }
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        span.record_error(e)
+        span.status = Status.new(Status::UNKNOWN_ERROR,
+                                 description: "Unhandled exception of type: #{e.class}")
+        raise e
+      ensure
+        span.finish
+      end
+
+      # Activates/deactivates the Span within the current Context, which makes the "current span"
+      # available implicitly.
+      #
+      # On exit, the Span that was active before calling this method will be reactivated.
+      #
+      # @param [Span] span the span to activate
+      # @yield [span, context] yields span and a context containing the span to the block.
+      def with_span(span)
+        Context.with_value(CURRENT_SPAN_KEY, span) { |c, s| yield s, c }
+      end
+
+      def start_root_span(name, attributes: nil, links: nil, start_timestamp: nil, kind: nil)
+        Span.new
+      end
+
+      # Used when a caller wants to manage the activation/deactivation and lifecycle of
+      # the Span and its parent manually.
+      #
+      # Parent context can be either passed explicitly, or inferred from currently activated span.
+      #
+      # @param [optional Span] with_parent Explicitly managed parent Span, overrides
+      #   +with_parent_context+.
+      # @param [optional Context] with_parent_context Explicitly managed. Overridden by
+      #   +with_parent+.
+      #
+      # @return [Span]
+      def start_span(name, with_parent: nil, with_parent_context: nil, attributes: nil, links: nil, start_timestamp: nil, kind: nil)
+        span_context = with_parent&.context || active_span_context(with_parent_context)
+        if span_context.valid?
+          Span.new(span_context: span_context)
+        else
+          Span.new
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/trace/tracer_provider.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Trace
+    # No-op implementation of a tracer provider.
+    class TracerProvider
+      # Returns a {Tracer} instance.
+      #
+      # @param [optional String] name Instrumentation package name
+      # @param [optional String] version Instrumentation package version
+      #
+      # @return [Tracer]
+      def tracer(name = nil, version = nil)
+        @tracer ||= Tracer.new
+      end
+    end
+  end
+end

data/lib/opentelemetry/trace/util/http_to_status.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Trace
+    module Util
+      # Convenience methods, not necessarily required by the API specification.
+      module HttpToStatus
+        # Implemented according to
+        # https://github.com/open-telemetry/opentelemetry-specification/issues/306
+        # https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/data-http.md#status
+        #
+        # @param code Numeric HTTP status
+        # @return Status
+        def http_to_status(code) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+          case code.to_i
+          when 100..399
+            new(const_get(:OK))
+          when 401
+            new(const_get(:UNAUTHENTICATED))
+          when 403
+            new(const_get(:PERMISSION_DENIED))
+          when 404
+            new(const_get(:NOT_FOUND))
+          when 429
+            new(const_get(:RESOURCE_EXHAUSTED))
+          when 400..499
+            new(const_get(:INVALID_ARGUMENT))
+          when 501
+            new(const_get(:UNIMPLEMENTED))
+          when 503
+            new(const_get(:UNAVAILABLE))
+          when 504
+            new(const_get(:DEADLINE_EXCEEDED))
+          when 500..599
+            new(const_get(:INTERNAL_ERROR))
+          else
+            new(const_get(:UNKNOWN_ERROR))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  ## Current OpenTelemetry version
+  VERSION = '0.5.1'
+end

metadata

@@ -0,0 +1,220 @@
+--- !ruby/object:Gem::Specification
+name: opentelemetry-api
+version: !ruby/object:Gem::Version
+  version: 0.5.1
+platform: ruby
+authors:
+- OpenTelemetry Authors
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-07-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: benchmark-ipsa
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.17'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.17'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.73.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.73.0
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.17'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.17'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: yard-doctest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.6
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.6
+description: A stats collection and distributed tracing framework
+email:
+- cncf-opentelemetry-contributors@lists.cncf.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".yardopts"
+- CHANGELOG.md
+- LICENSE
+- OVERVIEW.md
+- lib/opentelemetry-api.rb
+- lib/opentelemetry.rb
+- lib/opentelemetry/context.rb
+- lib/opentelemetry/context/key.rb
+- lib/opentelemetry/context/propagation.rb
+- lib/opentelemetry/context/propagation/composite_propagator.rb
+- lib/opentelemetry/context/propagation/default_getter.rb
+- lib/opentelemetry/context/propagation/default_setter.rb
+- lib/opentelemetry/context/propagation/noop_extractor.rb
+- lib/opentelemetry/context/propagation/noop_injector.rb
+- lib/opentelemetry/context/propagation/propagation.rb
+- lib/opentelemetry/context/propagation/propagator.rb
+- lib/opentelemetry/correlation_context.rb
+- lib/opentelemetry/correlation_context/builder.rb
+- lib/opentelemetry/correlation_context/manager.rb
+- lib/opentelemetry/correlation_context/propagation.rb
+- lib/opentelemetry/correlation_context/propagation/context_keys.rb
+- lib/opentelemetry/correlation_context/propagation/text_extractor.rb
+- lib/opentelemetry/correlation_context/propagation/text_injector.rb
+- lib/opentelemetry/error.rb
+- lib/opentelemetry/instrumentation.rb
+- lib/opentelemetry/instrumentation/base.rb
+- lib/opentelemetry/instrumentation/registry.rb
+- lib/opentelemetry/internal.rb
+- lib/opentelemetry/metrics.rb
+- lib/opentelemetry/metrics/handles.rb
+- lib/opentelemetry/metrics/instruments.rb
+- lib/opentelemetry/metrics/meter.rb
+- lib/opentelemetry/metrics/meter_provider.rb
+- lib/opentelemetry/trace.rb
+- lib/opentelemetry/trace/event.rb
+- lib/opentelemetry/trace/link.rb
+- lib/opentelemetry/trace/propagation.rb
+- lib/opentelemetry/trace/propagation/context_keys.rb
+- lib/opentelemetry/trace/propagation/trace_context.rb
+- lib/opentelemetry/trace/propagation/trace_context/text_extractor.rb
+- lib/opentelemetry/trace/propagation/trace_context/text_injector.rb
+- lib/opentelemetry/trace/propagation/trace_context/trace_parent.rb
+- lib/opentelemetry/trace/span.rb
+- lib/opentelemetry/trace/span_context.rb
+- lib/opentelemetry/trace/span_kind.rb
+- lib/opentelemetry/trace/status.rb
+- lib/opentelemetry/trace/trace_flags.rb
+- lib/opentelemetry/trace/tracer.rb
+- lib/opentelemetry/trace/tracer_provider.rb
+- lib/opentelemetry/trace/util/http_to_status.rb
+- lib/opentelemetry/version.rb
+homepage: https://github.com/open-telemetry/opentelemetry-ruby
+licenses:
+- Apache-2.0
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: A stats collection and distributed tracing framework
+test_files: []