uptrace 0.1.0 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6fed520ea5aa64b60260f976f155c618852f95c36e0eacfca80dd3b0654cf00f
-  data.tar.gz: b93d8bb971d72e571b9f87c098779c0aede9157d698ea522ea360801d9f133e3
+  metadata.gz: 525b8e2ad45dd955af7095839bfdf024e29b11309e8a0103b36bddb7980f3c41
+  data.tar.gz: 0766a2822dad2acb536aeccba788ac898ce7474ae4d74de355577de544772a4b
 SHA512:
-  metadata.gz: d6f4ae143df5432535606e745907a7dd8ac9e22d9ac08280826b457ad6fd15d9c16fc368baab5616ec655fa0d9a9596edb7dfd0c7802563fe70e1b4cad2aa70d
-  data.tar.gz: 29156234fe786b7ceefa118511153fea5afbc2e4fe7890cdc32eac0cb6d6274a40e6630a3c4fee95aa94203c876438434c17e87f8a443260f480c2b6d437b85a
+  metadata.gz: 36c69755595e07ffee78a62f3f1633fdd62def2d910b50876e8ffc4e2791800869d98f61b338bb2e30a01280610cc5fbeabe58a0f17214b5f2377031c2801f07
+  data.tar.gz: f33956036979a79d2f39e05f8a30f3008ffd967a828a048d88b187867e562bd013cecf9b0958584dc885142341633848739c3fc05dded624c8c16dc7ee8d7848

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/RELEASE.md

@@ -0,0 +1,7 @@
+Bump version and then run:
+
+```shell
+gem build uptrace.gemspec
+bundle install
+gem push uptrace-0.2.0.gem
+```

data/lib/uptrace.rb

@@ -7,9 +7,31 @@ module Uptrace
   extend self
 
   attr_accessor :logger
+  attr_writer :client
 
-  self.logger = Logger.new(STDOUT)
+  self.logger = Logger.new($stdout)
+
+  # @return [Object, Client] registered client or a default no-op implementation of the client.
+  def client
+    @client ||= Client.new
+  end
+
+  def trace_url(span)
+    client.trace_url(span)
+  end
+
+  def configure_tracing(c, dsn: '')
+    upclient = if dsn.empty?
+                 client
+               else
+                 Client.new(dsn: dsn)
+               end
+
+    c.add_span_processor(upclient.span_processor) unless upclient.disabled?
+  end
 end
 
 require 'uptrace/version'
+require 'uptrace/dsn'
+require 'uptrace/client'
 require 'uptrace/trace'

data/lib/uptrace/client.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'opentelemetry/sdk'
+
+module Uptrace
+  # Uptrace client that configures OpenTelemetry SDK to use Uptrace exporter.
+  class Client
+    # @param [string] dsn
+    def initialize(dsn: '')
+      dsn = ENV.fetch('UPTRACE_DSN', '') if dsn.empty?
+
+      begin
+        @dsn = DSN.new(dsn)
+      rescue ArgumentError => e
+        Uptrace.logger.error("Uptrace is disabled: #{e.message}")
+        @disabled = true
+
+        @dsn = DSN.new('https://TOKEN@api.uptrace.dev/PROJECT_ID')
+      end
+    end
+
+    def disabled?
+      @disabled
+    end
+
+    # @param [OpenTelemetry::Trace::Span] span
+    # @return [String]
+    def trace_url(span)
+      host = @dsn.host.delete_prefix('api.')
+      trace_id = span.context.hex_trace_id
+      "#{@dsn.scheme}://#{host}/search/#{@dsn.project_id}?q=#{trace_id}"
+    end
+
+    # @return [OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor]
+    def span_processor
+      exp = Uptrace::Trace::Exporter.new(@dsn)
+      OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
+        exp,
+        max_queue_size: 1000,
+        max_export_batch_size: 1000,
+        schedule_delay: 5_000
+      )
+    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, "DSN can't be empty" if dsn.empty?
+
+      begin
+        uri = URI.parse(dsn)
+      rescue URI::InvalidURIError => e
+        raise ArgumentError, %(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, %(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/exporter.rb

@@ -1,104 +1,125 @@
 # 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
+      def initialize(dsn)
+        @dsn = dsn
+        @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,
+
+          name: span.name,
+          kind: kind_as_str(span.kind),
+          startTime: as_unix_nano(span.start_timestamp),
+          endTime: as_unix_nano(span.end_timestamp),
+
+          resource: uptrace_resource(span.resource),
+          attrs: span.attributes
+        }
 
-        expose.id = span.id
-        expose.parentId = span.parent_span_id
+        out[:parentId] = span.parent_span_id.unpack1('Q') if span.parent_span_id
 
-        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
+        out[:events] = uptrace_events(span.events) unless span.events.nil?
+        out[:links] = uptrace_links(span.links) unless span.links.nil?
 
-        expose
+        status = span.status
+        out[:statusCode] = status_code_as_str(status.code)
+        out[:statusMessage] = status.description unless status.description.empty?
+
+        il = span.instrumentation_library
+        out[:tracerName] = il.name
+        out[:tracerVersion] = il.name unless il.version.empty?
+
+        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 +127,96 @@ 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 #{@dsn.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
     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.4'
 end

metadata

@@ -1,43 +1,57 @@
 --- !ruby/object:Gem::Specification
 name: uptrace
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.4
 platform: ruby
 authors:
 - Uptrace Authors
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-06-04 00:00:00.000000000 Z
+date: 2021-03-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.15.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: 0.15.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
@@ -132,10 +174,12 @@ files:
 - ".yardopts"
 - LICENSE
 - README.md
+- RELEASE.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
 - lib/uptrace/trace/exporter.rb
 - lib/uptrace/version.rb
 homepage: https://github.com/uptrace/uptrace-ruby
@@ -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

data/lib/uptrace/trace/config.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-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
-      attr_accessor :dsn
-    end
-  end
-end