rspec-trace-formatter 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 523ae0ee65d59fbcc8081aefe0da23355846add224b8465d210eea536a93d9a5
-  data.tar.gz: a94b8c49db8bf4a1cfd0d00ebdab0136120be9d9d7338294a3b9f173dc612503
+  metadata.gz: dae27f097510a3dcb600e0cddcb6d15b79af17db85942d8472696ac4347f7f8f
+  data.tar.gz: 8d23c7632ce92d3f67d18868841c4ddc415f2775962bce512de91078f12cb4dc
 SHA512:
-  metadata.gz: 73903d8f6cc20a9301eb92105ddd0ec80b9152c389ed6c855ae46118a8793a91a356c24200d6f71295e2bec289dc6a0223d158a750b1d8cd6da6fef43f45a9b1
-  data.tar.gz: 6afed85a1363970c45fa72d0c37412998d59e6d29334f70c18fc98ce7316376fe8a41f06dee84e28d5c6a894dd9a27ce18f45ee5002b842bfb3ca3617ade6801
+  metadata.gz: 35edff294bbfb5221b476a208f7848dd43d2082f3e262a41bf48fab2206f7bf6489d133ef0836d5813f04a0d36bd7291e79c65fc3db82f860f9773a42476a50a
+  data.tar.gz: 6b3c9b25ce54d2db82f255d2c1e23b1c7abe789c0e5c4ddc1eb7e6f1b21b473eb904fdbcea49add06e24054c1df44da1fb5b9f842db9c0b2711e261d7b1ca53b

data/.devcontainer/Dockerfile

@@ -0,0 +1,17 @@
+# [Choice] Ruby version (use -bullseye variants on local arm64/Apple Silicon): 3, 3.0, 2, 2.7, 2.6, 3-bullseye, 3.0-bullseye, 2-bullseye, 2.7-bullseye, 2.6-bullseye, 3-buster, 3.0-buster, 2-buster, 2.7-buster, 2.6-buster
+ARG VARIANT=2-bullseye
+FROM mcr.microsoft.com/vscode/devcontainers/ruby:0-${VARIANT}
+
+# [Choice] Node.js version: none, lts/*, 16, 14, 12, 10
+ARG NODE_VERSION="none"
+RUN if [ "${NODE_VERSION}" != "none" ]; then su vscode -c "umask 0002 && . /usr/local/share/nvm/nvm.sh && nvm install ${NODE_VERSION} 2>&1"; fi
+
+# [Optional] Uncomment this section to install additional OS packages.
+# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
+#     && apt-get -y install --no-install-recommends <your-package-list-here>
+
+# [Optional] Uncomment this line to install additional gems.
+# RUN gem install <your-gem-names-here>
+
+# [Optional] Uncomment this line to install global node packages.
+# RUN su vscode -c "source /usr/local/share/nvm/nvm.sh && npm install -g <your-package-here>" 2>&1

data/.devcontainer/base.Dockerfile

@@ -0,0 +1,43 @@
+# [Choice] Ruby version (use -bullseye variants on local arm64/Apple Silicon): 3, 3.0, 2, 2.7, 2.6, 3-bullseye, 3.0-bullseye, 2-bullseye, 2.7-bullseye, 2.6-bullseye, 3-buster, 3.0-buster, 2-buster, 2.7-buster, 2.6-buster
+ARG VARIANT=2-bullseye
+FROM ruby:${VARIANT}
+
+# Copy library scripts to execute
+COPY library-scripts/*.sh library-scripts/*.env /tmp/library-scripts/
+
+# [Option] Install zsh
+ARG INSTALL_ZSH="true"
+# [Option] Upgrade OS packages to their latest versions
+ARG UPGRADE_PACKAGES="true"
+# Install needed packages and setup non-root user. Use a separate RUN statement to add your own dependencies.
+ARG USERNAME=vscode
+ARG USER_UID=1000
+ARG USER_GID=$USER_UID
+RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
+    # Remove imagemagick due to https://security-tracker.debian.org/tracker/CVE-2019-10131
+    && apt-get purge -y imagemagick imagemagick-6-common \
+    # Install common packages, non-root user, rvm, core build tools
+    && bash /tmp/library-scripts/common-debian.sh "${INSTALL_ZSH}" "${USERNAME}" "${USER_UID}" "${USER_GID}" "${UPGRADE_PACKAGES}" "true" "true" \
+    && bash /tmp/library-scripts/ruby-debian.sh "none" "${USERNAME}" "true" "true" \
+    && apt-get autoremove -y && apt-get clean -y && rm -rf /var/lib/apt/lists/*
+
+# [Choice] Node.js version: none, lts/*, 16, 14, 12, 10
+ARG NODE_VERSION="none"
+ENV NVM_DIR=/usr/local/share/nvm
+ENV NVM_SYMLINK_CURRENT=true \
+    PATH=${NVM_DIR}/current/bin:${PATH}
+RUN bash /tmp/library-scripts/node-debian.sh "${NVM_DIR}" "${NODE_VERSION}" "${USERNAME}" \
+    && apt-get clean -y && rm -rf /var/lib/apt/lists/*
+
+ # Remove library scripts for final image
+RUN rm -rf /tmp/library-scripts
+
+# [Optional] Uncomment this section to install additional OS packages.
+# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
+#     && apt-get -y install --no-install-recommends <your-package-list-here>
+
+# [Optional] Uncomment this line to install additional gems.
+# RUN gem install <your-gem-names-here>
+
+# [Optional] Uncomment this line to install global node packages.
+# RUN su vscode -c "source /usr/local/share/nvm/nvm.sh && npm install -g <your-package-here>" 2>&1

data/.devcontainer/devcontainer.json

@@ -0,0 +1,34 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:
+// https://github.com/microsoft/vscode-dev-containers/tree/v0.205.2/containers/ruby
+{
+	"name": "Ruby",
+	"build": {
+		"dockerfile": "Dockerfile",
+		"args": { 
+			// Update 'VARIANT' to pick a Ruby version: 3, 3.0, 2, 2.7, 2.6
+			// Append -bullseye or -buster to pin to an OS version.
+			// Use -bullseye variants on local on arm64/Apple Silicon.
+			"VARIANT": "3-bullseye",
+			// Options
+			"NODE_VERSION": "none"
+		}
+	},
+
+	// Set *default* container specific settings.json values on container create.
+	"settings": {},
+
+	// Add the IDs of extensions you want installed when the container is created.
+	"extensions": [
+		"rebornix.Ruby"
+	],
+	
+	// Use 'forwardPorts' to make a list of ports inside the container available locally.
+	// "forwardPorts": [],
+
+	// Use 'postCreateCommand' to run commands after the container is created.
+	// "postCreateCommand": "ruby --version",
+
+	// Comment out connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
+	"remoteUser": "vscode"
+
+}

data/.github/workflows/ci.yml

@@ -12,7 +12,7 @@ jobs:
       - uses: actions/checkout@v2
       - uses: ruby/setup-ruby@v1
         with:
-          ruby-version: 2.7
+          ruby-version: 3.0
       - name: StandardRB Lint
         run: |
           gem install standardrb

data/.gitignore

@@ -48,6 +48,7 @@ build-iPhoneSimulator/
 Gemfile.lock
 .ruby-version
 .ruby-gemset
+.tool-versions
 
 # unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
 .rvmrc

data/README.md

@@ -52,22 +52,40 @@ However, the rest of this library is _expected_ to work for you, and [specifying
 
 ## How Do I Use It?
 
+You can install this gem by adding the `rspec-trace-formatter` (along with the necessary OpenTelemetry dependencies, if they aren't already included) to your `Gemfile` and running `bundle install`.
+For example:
+
+```ruby
+group :test do
+  gem "rspec-trace-formatter"
+  gem "opentelemetry-api", "~> 1.0"
+  gem "opentelemetry-exporter-otlp", "~> 0.20.0"
+end
+```
+
 This library should be used like [any other RSpec formatter](https://relishapp.com/rspec/rspec-core/v/3-10/docs/command-line/format-option), with the assistance of any environment variables that you need to control the OpenTelemetry data.
 
 Example of using the `RSpec::Trace::OpenTelemetryFormatter` with representative environment variables set:
 
 ```bash
-OTEL_TRACES_EXPORTER=console bundle exec rspec --format RSpec::Trace::OpenTelemetryFormatter
+$ OTEL_TRACES_EXPORTER=console bundle exec rspec --format RSpec::Trace::OpenTelemetryFormatter
 ```
 
 Example of running the `RSpec::Trace::Formatter` by itself and sending the output to `rspec-trace-consumer` separately (in a way that you can surely improve upon):
 
 ```bash
-OTEL_TRACES_EXPORTER=console bundle exec rspec --format RSpec::Trace::Formatter --out /tmp/trace-events.jsonl
+$ OTEL_TRACES_EXPORTER=console bundle exec rspec --format RSpec::Trace::Formatter --out /tmp/trace-events.jsonl
+
+# Piping the input in
+$ rspec-trace-consumer < /tmp/trace-events.jsonl
 
-rspec-trace-consumer < /tmp/trace-events.jsonl
+# Passing a filename as an argument
+$ rspec-trace-consumer /tmp/trace-events.jsonl
 ```
 
+If the `TRACEPARENT` environment variable is set in either of these cases, it will be interpreted as a [W3C Trace Context Traceparent Header value](https://www.w3.org/TR/trace-context/#traceparent-header).
+This will allow you to include the span events generated by this library in a larger distributed trace.
+
 ## How Do I Contribute?
 
 Very carefully, I hope.
@@ -75,14 +93,18 @@ Very carefully, I hope.
 One notable fact is that we use [snapshot testing](https://github.com/levinmr/rspec-snapshot) for the class underpinning `rspec-trace-consumer`.
 To keep this reliable, I've defined a custom OpenTelemetry span exporter that includes meaningful-enough data to test with and no execution-specific fields.
 
-## What's Coming Next?
+### Useful `rake` commands
+
+* `rake build`: Build the gem
+* `rake install`: Builds and installs the gem
+* `rake regenerate_examples`: Rebuilds fixtures for snapshot tests
+* `rake test`: Runs the automated tests (written with RSpec, of course)
+* `rake update_snapshots`: Updates the test snapshots
 
-This does not yet support providing a [parent trace ID with an environment variable](https://github.com/open-telemetry/opentelemetry-specification/issues/740).
-I haven't done it yet because it's not very helpful to me given my primary use case, but I'll add that soon enough.
+### Containers
 
-The fixtures for the snapshot tests for the `Consumer` class are currently system-specific insofar as the exception stack traces are built from real exceptions that include paths from the Ruby installation that generated them.
-Right now they come from my setup, so if anyone else regenerates the fixtures these paths will change.
-I believe that the ideal way to fix this is to provide a containerized development environment for which these paths can be fixed for everyone.
+Configuration for a [dev container](https://code.visualstudio.com/docs/remote/containers) is provided for convenience.
+The main practical benefit of developing in the container is to be able to regenerate the snapshots for the `Consumer` tests with consistent and non-identifying file paths for the stack traces.
 
 ## License
 

data/exe/rspec-trace-consumer

@@ -2,6 +2,23 @@
 
 $LOAD_PATH.unshift("#{__dir__}/../lib")
 
+require "optionparser"
 require "rspec/trace"
 
-RSpec::Trace::Consumer.new($stdin).run
+OptionParser.new do |opts|
+  opts.banner = "Usage: rspec-trace-consumer [path]"
+  opts.on("-v", "--version", "Prints the current library version") do
+    puts RSpec::Trace::VERSION
+    exit 0
+  end
+end.parse!
+
+input_file = ARGV.pop
+input = if input_file
+  File.open(input_file, "r")
+else
+  $stdin
+end
+
+OpenTelemetry::SDK.configure
+RSpec::Trace::Consumer.new(input, ENV["TRACEPARENT"]).run

data/lib/rspec/trace/consumer.rb

@@ -7,18 +7,13 @@ require "opentelemetry/exporter/otlp"
 module RSpec
   module Trace
     class Consumer
-      def initialize(input)
+      def initialize(input, traceparent_string = nil)
         @input = input
-        OpenTelemetry::SDK.configure do |c|
-          c.service_name = ENV.fetch("OTEL_SERVICE_NAME", "rspec")
-        end
         @tracer_provider = OpenTelemetry.tracer_provider
         @tracer_provider.sampler = OpenTelemetry::SDK::Trace::Samplers::ALWAYS_ON
         @tracer = @tracer_provider.tracer("rspec-trace-formatter", RSpec::Trace::VERSION)
         @spans = []
-        # TODO: Not this
-        @current_span_key = OpenTelemetry::Trace.const_get(:CURRENT_SPAN_KEY)
-        @contexts = [OpenTelemetry::Context.empty]
+        @contexts = [load_context_from_traceparent(traceparent_string)]
         @tokens = []
       end
 
@@ -110,6 +105,14 @@ module RSpec
 
       private
 
+      def load_context_from_traceparent(traceparent_string)
+        return OpenTelemetry::Context.current unless traceparent_string
+
+        OpenTelemetry::Trace::Propagation::TraceContext.text_map_propagator.extract(
+          {"traceparent" => traceparent_string}
+        )
+      end
+
       def parse_event(line)
         event = JSON.parse(line, symbolize_names: true)
         event[:timestamp] = Time.parse(event[:timestamp])
@@ -120,8 +123,9 @@ module RSpec
         @tracer.start_span(name, start_timestamp: timestamp, with_parent: @contexts.last).tap do |span|
           yield span if block_given?
           @spans.push(span)
-          @contexts.push(@contexts.last.set_value(@current_span_key, span))
-          @tokens.push(OpenTelemetry::Context.attach(@contexts.last))
+          new_context = OpenTelemetry::Trace.context_with_span(span, parent_context: @contexts.last)
+          @contexts.push(new_context)
+          @tokens.push(OpenTelemetry::Context.attach(new_context))
         end
       end
 

data/lib/rspec/trace/formatter.rb

@@ -3,7 +3,7 @@
 require "active_support/time"
 require "active_support/json"
 require "rspec/core"
-require "rspec/core/formatters/base_text_formatter"
+require "rspec/core/formatters/base_formatter"
 
 require_relative "version"
 

data/lib/rspec/trace/version.rb

@@ -2,6 +2,6 @@
 
 module RSpec
   module Trace
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rspec-trace-formatter
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Zach Thomae
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-12-07 00:00:00.000000000 Z
+date: 2021-12-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: opentelemetry-api
@@ -215,6 +215,9 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".devcontainer/Dockerfile"
+- ".devcontainer/base.Dockerfile"
+- ".devcontainer/devcontainer.json"
 - ".github/workflows/ci.yml"
 - ".gitignore"
 - ".rspec"