uptrace 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6fed520ea5aa64b60260f976f155c618852f95c36e0eacfca80dd3b0654cf00f
-  data.tar.gz: b93d8bb971d72e571b9f87c098779c0aede9157d698ea522ea360801d9f133e3
+  metadata.gz: a05b7c62ea6f2a2fb078f3b8272951c1d114f8062ff833c14c3b5a9183524cb1
+  data.tar.gz: 2876c7b4803b791d5955665a5fb8e97754355f9929c2a6b5ea39b511a839f54c
 SHA512:
-  metadata.gz: d6f4ae143df5432535606e745907a7dd8ac9e22d9ac08280826b457ad6fd15d9c16fc368baab5616ec655fa0d9a9596edb7dfd0c7802563fe70e1b4cad2aa70d
-  data.tar.gz: 29156234fe786b7ceefa118511153fea5afbc2e4fe7890cdc32eac0cb6d6274a40e6630a3c4fee95aa94203c876438434c17e87f8a443260f480c2b6d437b85a
+  metadata.gz: 9ce7612b3d87b3a32605996de564ce4f44821590bca24af38c6ef267d0a5c7c3d141a8241042bb36f86e532e4e38d971d3f82c9a096f69a1a58af5262efbd0af
+  data.tar.gz: b9b4d42c52cdfac6ae3444a3d782c83c7d410941a8b4a63aaf05d318863fa229d30e588484746df86a60358d57c5eefc718611bc94987987c5082bd8017887a1

data/README.md

@@ -1,89 +1,21 @@
 # Uptrace Ruby exporter for OpenTelemetry
 
 [![Build Status](https://travis-ci.org/uptrace/uptrace-ruby.svg?branch=master)](https://travis-ci.org/uptrace/uptrace-ruby)
+[![Documentation](https://img.shields.io/badge/uptrace-documentation-informational)](https://docs.uptrace.dev/ruby/)
 
-## Introduction
-
-uptrace-ruby is an exporter for [OpenTelemetry](https://opentelemetry.io/) that
-sends your traces/spans and metrics to [Uptrace.dev](https://uptrace.dev).
-Briefly the process is the following:
-
-- OpenTelemetry API is used to instrument your application with spans and
-  metrics.
-- OpenTelemetry SDK and this exporter send collected information to Uptrace.dev.
-- Uptrace.dev uses that information to help you pinpoint failures and find
-  performance bottlenecks.
-
-## Instrumenting code
-
-You instrument your application by wrapping potentially interesting operations
-with spans. Each span has:
-
-- an operation name;
-- a start time and end time;
-- a set of key/value attributes containing data about the operation;
-- a set of timed events representing events, errors, logs, etc.
-
-You create spans using a tracer:
+<a href="https://docs.uptrace.dev/ruby/">
+  <img src="https://docs.uptrace.dev/devicons/ruby-original.svg" height="200px" />
+</a>
 
-```ruby
-require 'opentelemetry'
+## Installation
 
-// Create a named tracer using your repo as an identifier.
-tracer = OpenTelemetry.tracer_provider.tracer('github.com/username/app-name', 'semver:1.0')
+```bash
+gem install uptrace
 ```
 
-To create a span:
-
-```ruby
-tracer.in_span('operation-name') do |span|
-  do_some_work
-end
-```
-
-Internally that does roughly the following:
-
-```ruby
-// Create a span.
-span = tracer.start_span('operation-name')
-
-// Activate the span within the current context.
-tracer.with_span(span) do |span|
-  do_some_work
-end
-
-// Finish the span when operation is completed.
-span.finish
-```
-
-To get the active span from the context:
-
-```ruby
-span = tracer.current_span
-```
-
-Once you have a span you can start adding attributes:
-
-```ruby
-span.set_attribute('enduser.id', '123')
-span.set_attribute('enduser.role', 'admin')
-```
-
-or events:
-
-```ruby
-span.add_event(name: 'log', attributes: {
-  'log.severity': 'error',
-  'log.message': 'User not found',
-  'enduser.id': '123',
-})
-```
+## Introduction
 
-To record an error use `record_error` which internally uses `add_event`. Note
-that `tracer.in_span` already records resqued exceptions.
+uptrace-ruby is the official Uptrace client for Ruby that sends your traces/spans and metrics to
+[Uptrace.dev](https://uptrace.dev).
 
-```ruby
-rescue Exception => e
-  span.record_error(e)
-end
-```
+See [uptrace-ruby documentation](https://docs.uptrace.dev/ruby/) for details.

data/lib/uptrace/client.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'opentelemetry/sdk'
+
+module Uptrace
+  # Uptrace client that configures OpenTelemetry SDK to use Uptrace exporter.
+  class Client
+    ##
+    # @yieldparam config [Uptrace::Config]
+    # @return [void]
+    #
+    def initialize
+      @cfg = Uptrace::Trace::Config.new
+      yield @cfg if block_given?
+
+      begin
+        @cfg.dsno
+      rescue ArgumentError => e
+        Uptrace.logger.error(e.message)
+        @cfg.disabled = true
+
+        @cfg.dsn = 'https://TOKEN@api.uptrace.dev/PROJECT_ID'
+      end
+
+      setup_tracing unless @cfg.disabled
+    end
+
+    # @param [optional Numeric] timeout An optional timeout in seconds.
+    def shutdown(timeout: nil)
+      return if @cfg.disabled
+
+      OpenTelemetry.tracer_provider.shutdown(timeout: timeout)
+    end
+
+    # @return [OpenTelemetry::Trace::Span]
+    def trace_url(span)
+      dsn = @cfg.dsno
+      host = dsn.host.delete_prefix('api.')
+      trace_id = span.context.hex_trace_id
+      "#{dsn.scheme}://#{host}/#{dsn.project_id}/search?q=#{trace_id}"
+    end
+
+    private
+
+    def setup_tracing
+      exp = Uptrace::Trace::Exporter.new(@cfg)
+
+      OpenTelemetry::SDK.configure do |c|
+        bsp = OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(exporter: exp, max_queue_size: 1000, max_export_batch_size: 1000, schedule_delay: 5_000)
+        c.add_span_processor(bsp)
+
+        c.service_name = @cfg.service_name
+        c.service_version = @cfg.service_version
+      end
+    end
+  end
+end

data/lib/uptrace/dsn.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Uptrace
+  # Uptrace DSN
+  class DSN
+    KEYS = %w[scheme host project_id token].freeze
+
+    attr_reader :dsn, :port, *KEYS
+
+    def initialize(dsn)
+      raise ArgumentError, "uptrace: DSN can't be empty" if dsn.empty?
+
+      begin
+        uri = URI.parse(dsn)
+      rescue URI::InvalidURIError => e
+        raise ArgumentError, %(uptrace: can't parse DSN=#{dsn.inspect}: #{e})
+      end
+
+      @dsn = dsn
+      @project_id = uri.path.delete_prefix('/')
+      @token = uri.user
+      @host = uri.host
+      @port = uri.port
+      @scheme = uri.scheme
+
+      KEYS.each do |k|
+        v = public_send(k)
+        raise ArgumentError, %(uptrace: DSN does not have #{k} (DSN=#{dsn.inspect})) if v.nil? || v.empty?
+      end
+    end
+
+    def to_s
+      @dsn
+    end
+  end
+end

data/lib/uptrace/trace/config.rb

@@ -1,12 +1,30 @@
 # frozen_string_literal: true
 
+require 'uptrace/dsn'
+
 module Uptrace
   module Trace
     # Config is a configuration for Uptrace span exporter.
     class Config
-      # @return [String] a data source name to connect to uptrace.dev.
-      # @api public
+      # @return [string] a data source name to connect to uptrace.dev.
       attr_accessor :dsn
+
+      # @return [string] `service.name` resource attribute.
+      attr_accessor :service_name
+
+      # @return [string] `service.name` resource attribute.
+      attr_accessor :service_version
+
+      # @return [boolean] disables the exporter.
+      attr_accessor :disabled
+
+      def initialize
+        @dsn = ENV.fetch('UPTRACE_DSN', '')
+      end
+
+      def dsno
+        @dsno ||= DSN.new(@dsn)
+      end
     end
   end
 end

data/lib/uptrace/trace/exporter.rb

@@ -1,104 +1,124 @@
 # frozen_string_literal: true
 
 require 'uri'
+require 'net/http'
+require 'json'
 
+require 'opentelemetry/sdk'
 require 'msgpack'
-require 'lz4-ruby'
+require 'zstd-ruby'
 
 module Uptrace
   module Trace
-    # @!visibility private
-    ExpoSpan = Struct.new(
-      :id,
-      :parentId,
-      :name,
-      :kind,
-      :startTime,
-      :endTime,
-      :statusCode,
-      :statusMessage,
-      :attrs,
-      :events,
-      :links,
-      :resource
-    )
-
     # Exporter is a span exporter for OpenTelemetry.
     class Exporter
+      SUCCESS = OpenTelemetry::SDK::Trace::Export::SUCCESS
+      FAILURE = OpenTelemetry::SDK::Trace::Export::FAILURE
+      TIMEOUT = OpenTelemetry::SDK::Trace::Export::TIMEOUT
+      private_constant(:SUCCESS, :FAILURE, :TIMEOUT)
+
       ##
       # @param [Config] cfg
       #
       def initialize(cfg)
         @cfg = cfg
 
-        begin
-          @uri = URI.parse(cfg.dsn)
-        rescue URI::InvalidURIError => e
-          @disabled = true
-          Uptrace.logger.error("can't parse dsn=#{cfg.dsn}: #{e}")
-        else
-          @endpoint = "#{@uri.scheme}://#{@uri.host}/api/v1/tracing#{@uri.path}/spans"
-        end
+        dsn = @cfg.dsno
+        @endpoint = "/api/v1/tracing/#{dsn.project_id}/spans"
+
+        @http = Net::HTTP.new(dsn.host, 443)
+        @http.use_ssl = true
+        @http.open_timeout = 5
+        @http.read_timeout = 5
+        @http.keep_alive_timeout = 30
       end
 
-      def export(spans)
-        return if @disabled
+      # Called to export sampled {OpenTelemetry::SDK::Trace::SpanData} structs.
+      #
+      # @param [Enumerable<OpenTelemetry::SDK::Trace::SpanData>] spans the
+      #   list of recorded {OpenTelemetry::SDK::Trace::SpanData} structs to be
+      #   exported.
+      # @param [optional Numeric] timeout An optional timeout in seconds.
+      # @return [Integer] the result of the export.
+      def export(spans, timeout: nil)
+        return SUCCESS if @disabled
+        return FAILURE if @shutdown
 
-        traces = {}
+        out = []
 
         spans.each do |span|
-          trace = traces[span.trace_id]
+          out.push(uptrace_span(span))
+        end
 
-          if trace.nil?
-            trace = []
-            traces[span.trace_id] = trace
-          end
+        send({ spans: out }, timeout: timeout)
+      end
 
-          expose = expo_span(span)
-          trace.push(expose)
-        end
+      # Called when {OpenTelemetry::SDK::Trace::Tracer#shutdown} is called, if
+      # this exporter is registered to a {OpenTelemetry::SDK::Trace::Tracer}
+      # object.
+      #
+      # @param [optional Numeric] timeout An optional timeout in seconds.
+      def shutdown(timeout: nil) # rubocop:disable Lint/UnusedMethodArgument
+        @shutdown = true
+        @http.finish if @http.started?
       end
 
       private
 
-      def send(traces)
-        req = build_request(traces: traces)
-        connection.request(req)
-      end
-
       ##
-      # @return [ExpoSpan]
+      # @return [hash]
       #
-      def expo_span(span)
-        expose = ExpoSpan.new
+      def uptrace_span(span)
+        out = {
+          id: span.span_id.unpack1('Q'),
+          traceId: span.trace_id,
 
-        expose.id = span.id
-        expose.parentId = span.parent_span_id
+          name: span.name,
+          kind: kind_as_str(span.kind),
+          startTime: as_unix_nano(span.start_timestamp),
+          endTime: as_unix_nano(span.end_timestamp),
 
-        expose.name = span.name
-        expose.kind = span.kind
-        expose.startTime = span.start_timestamp.to_i
-        expose.endTime = span.end_timestamp.to_i
-        expose.statusCode = span.status.canonical_code
-        expose.statusMessage = span.status.description
-        expose.attrs = span.attributes
+          resource: uptrace_resource(span.resource),
+          attrs: span.attributes,
 
-        expose
+          statusCode: status_code_as_str(span.status.code),
+          statusMessage: span.status.description,
+
+          tracer: uptrace_tracer(span.instrumentation_library)
+        }
+
+        out['parentId'] = span.parent_span_id.unpack1('Q') if span.parent_span_id
+
+        out['events'] = uptrace_events(span.events) unless span.events.nil?
+        out['links'] = uptrace_links(span.links) unless span.links.nil?
+
+        out
       end
 
-      ##
-      # @return [Net::HTTP]
-      #
-      def connection
-        unless @conn
-          @conn = Net::HTTP.new(@uri.host, @uri.port)
-          @conn.use_ssl = @uri.is_a?(URI::HTTPS)
-          @conn.open_timeout = 5
-          @conn.read_timeout = 5
-          @conn.keep_alive_timeout = 30
+      def send(data, timeout: nil) # rubocop:disable Lint/UnusedMethodArgument
+        req = build_request(data)
+
+        begin
+          resp = @http.request(req)
+        rescue Net::OpenTimeout, Net::ReadTimeout
+          return FAILURE
         end
 
-        @conn
+        case resp
+        when Net::HTTPOK
+          resp.body # Read and discard body
+          SUCCESS
+        when Net::HTTPBadRequest
+          data = JSON.parse(resp.body)
+          Uptrace.logger.error("status=#{data['status']}: #{data['message']}")
+          FAILURE
+        when Net::HTTPInternalServerError
+          resp.body
+          FAILURE
+        else
+          @http.finish
+          FAILURE
+        end
       end
 
       ##
@@ -106,18 +126,107 @@ module Uptrace
       # @return [Net::HTTP::Post]
       #
       def build_request(data)
-        data = data.to_msgpack
-        data = LZ4.compress data
+        data = MessagePack.pack(data)
+        data = Zstd.compress(data, 3)
 
         req = Net::HTTP::Post.new(@endpoint)
-        req['Authorization'] = @uri.user
-        req['Content-Type'] = 'application/msgpack'
-        req['Content-Encoding'] = 'lz4'
-        req['Connection'] = 'keep-alive'
+        req.add_field('Authorization', "Bearer #{@cfg.dsno.token}")
+        req.add_field('Content-Type', 'application/msgpack')
+        req.add_field('Content-Encoding', 'zstd')
+        req.add_field('Connection', 'keep-alive')
         req.body = data
 
         req
       end
+
+      # @param [SpanKind] kind
+      # @return [String]
+      def kind_as_str(kind)
+        case kind
+        when OpenTelemetry::Trace::SpanKind::SERVER
+          'server'
+        when OpenTelemetry::Trace::SpanKind::CLIENT
+          'client'
+        when OpenTelemetry::Trace::SpanKind::PRODUCER
+          'producer'
+        when OpenTelemetry::Trace::SpanKind::CONSUMER
+          'consumer'
+        else
+          'internal'
+        end
+      end
+
+      ##
+      # @param [Integer] timestamp
+      # @return [Integer]
+      #
+      def as_unix_nano(timestamp)
+        (timestamp.to_r * 1_000_000_000).to_i
+      end
+
+      ##
+      # @param [Integer] code
+      # @return [String]
+      #
+      def status_code_as_str(code)
+        case code
+        when OpenTelemetry::Trace::Status::OK
+          'ok'
+        when OpenTelemetry::Trace::Status::ERROR
+          'error'
+        else
+          'unset'
+        end
+      end
+
+      ##
+      # @param [OpenTelemetry::SDK::Resources::Resource] resource
+      # @return [Hash]
+      #
+      def uptrace_resource(resource)
+        out = {}
+        resource.attribute_enumerator.map { |key, value| out[key] = value }
+        out
+      end
+
+      def uptrace_events(events)
+        out = []
+        events.each do |event|
+          out.push(
+            {
+              name: event.name,
+              attrs: event.attributes,
+              time: as_unix_nano(event.timestamp)
+            }
+          )
+        end
+        out
+      end
+
+      def uptrace_links(links)
+        out = []
+        links.each do |link|
+          out.push(
+            {
+              trace_id => link.span_context.trace_id,
+              span_id => link.span_context.span_id.unpack1('Q'),
+              attrs => link.attributes
+            }
+          )
+        end
+        out
+      end
+
+      ##
+      # @param [OpenTelemetry::SDK::InstrumentationLibrary] il
+      # @return [Hash]
+      #
+      def uptrace_tracer(il)
+        {
+          name: il.name,
+          version: il.version
+        }
+      end
     end
   end
 end

data/lib/uptrace/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Uptrace
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/lib/uptrace.rb

@@ -8,8 +8,10 @@ module Uptrace
 
   attr_accessor :logger
 
-  self.logger = Logger.new(STDOUT)
+  self.logger = Logger.new($stdout)
 end
 
 require 'uptrace/version'
+require 'uptrace/dsn'
+require 'uptrace/client'
 require 'uptrace/trace'

metadata

@@ -1,43 +1,57 @@
 --- !ruby/object:Gem::Specification
 name: uptrace
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Uptrace Authors
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-06-04 00:00:00.000000000 Z
+date: 2021-02-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: lz4-ruby
+  name: msgpack
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.3
+        version: '1.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.3
+        version: '1.3'
 - !ruby/object:Gem::Dependency
-  name: msgpack
+  name: opentelemetry-sdk
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: 0.14.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: 0.14.0
+- !ruby/object:Gem::Dependency
+  name: zstd-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.4.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.4.5.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -86,14 +100,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.73.0
+        version: 1.10.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.10.0
+- !ruby/object:Gem::Dependency
+  name: rubocop-minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.2
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.73.0
+        version: 0.5.1
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -133,6 +175,8 @@ files:
 - LICENSE
 - README.md
 - lib/uptrace.rb
+- lib/uptrace/client.rb
+- lib/uptrace/dsn.rb
 - lib/uptrace/metric.rb
 - lib/uptrace/trace.rb
 - lib/uptrace/trace/config.rb
@@ -157,7 +201,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
+rubygems_version: 3.1.4
 signing_key: 
 specification_version: 4
 summary: Uptrace Ruby exporter for OpenTelemetry