libhoney 2.1.0 → 2.2.0.pre.dev

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87accb91b956f38c24050ebc8931d49041ab02551c394a7447434730eb827f18
-  data.tar.gz: 899a27302a4e04e2ac50af6f792a8515b252a838bb6b09d9471bf6aab9058cbc
+  metadata.gz: e2acde76ef3fc685e6ea13a5178b08f8f097df45b9731d157d3ef0ed653d1bbf
+  data.tar.gz: 4fe2094102da89e268aa9acc67e10c722b255d846aed078f10212209da45ff52
 SHA512:
-  metadata.gz: 42b5a14b536bdda18f2900e2767c4702dd16e5a441300830c9a6cd7ae15d3e4c7d6b0edb3346bb278f239731b16ca8bc807851d57d3d3ad6da185782a48bf64c
-  data.tar.gz: 1e764f94ded5a848f6a90197f340d31efbc13b2fa6eae9f7be2444a19b8a8e65165356d68cd76dd51f5ce8910e742db9fd8a49546170b4dafa4d99471445979d
+  metadata.gz: e5e52c97beae8e79a44a605260cf6d393461b434ee7fdab2fdb4652819899d8923a3460497b136dfa1c691032544e1276c5c6e8b28f5b38804c6f7d5528e050b
+  data.tar.gz: 64984f592c88602e9033ccc7ed4f5e3fd271edf6c1356791cffab21224e4bdf9c64df2d86e1dd95b203ae62ea7af0e385b9092d12276a4bf0fe770718e01329c

data/.circleci/config.yml

@@ -19,7 +19,7 @@ filters_publish: &filters_publish
 matrix_rubyversions: &matrix_rubyversions
   matrix:
     parameters:
-      rubyversion: ["2.4", "2.5", "2.6", "2.7", "3.0"]
+      rubyversion: ["2.4", "2.5", "2.6", "2.7", "3.0", "3.1"]
 
 # Default version of ruby to use for lint and publishing
 default_rubyversion: &default_rubyversion "3.0"

data/.github/dependabot.yml

@@ -13,3 +13,6 @@ updates:
       - "type: dependencies"
     reviewers:
       - "honeycombio/telemetry-team"
+    commit-message:
+      prefix: "maint"
+      include: "scope"

data/.github/release.yml

@@ -0,0 +1,23 @@
+# .github/release.yml
+
+changelog:
+  exclude:
+    labels:
+      - no-changelog
+  categories:
+    - title: 💥 Breaking Changes 💥
+      labels:
+        - "version: bump major"
+        - breaking-change
+    - title: 💡 Enhancements
+      labels:
+        - "type: enhancement"
+    - title: 🐛 Fixes
+      labels:
+        - "type: bug"
+    - title: 🛠 Maintenance
+      labels:
+        - "type: maintenance"
+    - title: 🤷 Other Changes
+      labels:
+        - "*"

data/.github/workflows/add-to-project-v2.yml

@@ -0,0 +1,15 @@
+name: Add to project
+on:
+  issues:
+    types: [opened]
+  pull_request_target:
+    types: [opened]
+jobs:
+  add-to-project:
+    runs-on: ubuntu-latest
+    name: Add issues and PRs to project
+    steps:
+      - uses: actions/add-to-project@main
+        with:
+          project-url: https://github.com/orgs/honeycombio/projects/11
+          github-token: ${{ secrets.GHPROJECTS_TOKEN }}

data/.github/workflows/validate-pr-title.yml

@@ -0,0 +1,64 @@
+name: "Validate PR Title"
+
+on:
+  pull_request:
+    types:
+      - opened
+      - edited
+      - synchronize
+
+jobs:
+  main:
+    name: Validate PR title
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v5
+        id: lint_pr_title
+        name: "🤖 Check PR title follows conventional commit spec"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          # Have to specify all types because `maint` and `rel` aren't defaults
+          types: |
+            maint
+            rel
+            fix
+            feat
+            chore
+            ci
+            docs
+            style
+            refactor
+            perf
+            test
+          ignoreLabels: |
+            "type: dependencies"
+      # When the previous steps fails, the workflow would stop. By adding this
+      # condition you can continue the execution with the populated error message.
+      - if: always() && (steps.lint_pr_title.outputs.error_message != null)
+        name: "📝 Add PR comment about using conventional commit spec"
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          header: pr-title-lint-error
+          message: |
+            Thank you for contributing to the project! 🎉
+
+            We require pull request titles to follow the [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/) and it looks like your proposed title needs to be adjusted.
+
+            Make sure to prepend with `feat:`, `fix:`, or another option in the list below.
+
+            Once you update the title, this workflow will re-run automatically and validate the updated title.
+
+            Details:
+
+            ```
+            ${{ steps.lint_pr_title.outputs.error_message }}
+            ```
+
+      # Delete a previous comment when the issue has been resolved
+      - if: ${{ steps.lint_pr_title.outputs.error_message == null }}
+        name: "❌ Delete PR comment after title has been updated"
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          header: pr-title-lint-error
+          delete: true

data/.gitignore

@@ -11,6 +11,7 @@
 /test/tmp/
 /test/version_tmp/
 /tmp/
+/examples/wiki-manual-tracing/*.txt
 
 # Used by dotenv library to load environment variables.
 # .env

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [2.2.0] - 2022-04-14
+
+### Added
+
+- Add Environment and Services support (#123) | [@MikeGoldsmith](https://github.com/MikeGoldsmith)
+
 ## [2.1.0] - 2022-02-02
 
 ### Improvements

data/examples/factorial/Gemfile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
+
+gem 'libhoney', path: '../..'

data/{example → examples/factorial}/factorial.rb

@@ -1,6 +1,3 @@
-lib = File.expand_path('../lib', __dir__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-
 require 'libhoney'
 
 # replace this with yours from https://ui.honeycomb.com/account

data/examples/wiki-manual-tracing/Gemfile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
+
+gem 'libhoney', path: '../..'
+gem 'sinatra-base'

data/examples/wiki-manual-tracing/README.md

@@ -0,0 +1,52 @@
+# ruby-wiki-tracing
+
+This example illustrates a simple wiki application instrumented with the bare minimum necessary to utilize Honeycomb's tracing functionality.
+
+## What We'll Do in This Example
+
+We'll instrument a simple application for tracing by following a few general steps:
+
+1. Set a top-level `trace.trace_id` at the origin of the request and set it on the request context. Generate a root span indicated by omitting a `trace.parent_id` field.
+2. To represent a unit of work within a trace as a span, add code to generate a span ID and capture the start time. At the **call site** of the unit of work, pass down a new request context with the newly-generated span ID as the `trace.parent_id`. Upon work completion, send the span with a calculated `duration_ms`.
+3. Rinse and repeat.
+
+**Note**: The [OpenTelemetry for Ruby](https://docs.honeycomb.io/getting-data-in/opentelemetry/ruby/) handles all of this propagation magic for you :)
+
+## Usage
+
+You can [find your API key](https://docs.honeycomb.io/getting-data-in/api-keys/#find-api-keys) in your Environment Settings.
+If you do not have an API key yet, sign up for a [free Honeycomb account](https://ui.honeycomb.io/signup).
+
+
+Once you have your API key, run:
+
+```shell
+bundle install
+```
+
+```shell
+HONEYCOMB_API_KEY=foobarbaz bundle exec ruby wiki.rb
+```
+
+And load [`http://localhost:4567/view/MyFirstWikiPage`](http://localhost:4567/view/MyFirstWikiPage) to create (then view) your first wiki page.
+
+Methods within the simple wiki application have been instrumented with tracing-like calls, with tracing identifiers propagated via thread locals.
+
+## Tips for Instrumenting Your Own Service
+
+- For a given span (e.g. `"loadPage"`), remember that the span definition lives in its parent, and the instrumentation is around the **call site** of `loadPage`:
+    ```ruby
+    with_span("load_page") do
+      # sets the appropriate "parent id" within the scope of the block
+      load_page(title)
+      # span is sent to Honeycomb upon completion of the block
+    end
+    ```
+- If emitting Honeycomb events or structured logs, make sure that the **start** time gets used as the canonical timestamp, not the time at event emission.
+- Remember, the root span should **not** have a `trace.parent_id`.
+- Don't forget to add some metadata of your own! It's helpful to identify metadata in the surrounding code that might be interesting when debugging your application.
+- Check out [OpenTelemetry for Ruby](https://docs.honeycomb.io/getting-data-in/opentelemetry/ruby/) to get this context propagation for free!
+
+## A Note on Code Style
+
+The purpose of this example is to illustrate the **bare minimum necessary** to propagate and set identifiers to enable tracing on an application for consumption by Honeycomb, illustrating the steps described in the top section of this README. We prioritized legibility over style and intentionally resisted refactoring that would sacrifice clarity. :)

data/examples/wiki-manual-tracing/views/edit.erb

@@ -0,0 +1,11 @@
+<h1><%= @page.title %></h1>
+
+<form action='/save/<%= @page.title %>' method='POST'>
+  <div>
+    <textarea name='body' rows='20' cols='80'><%= @page.body %></textarea>
+  </div>
+
+  <div>
+    <input type='submit' value='Save'>
+  </div>
+</form>

data/examples/wiki-manual-tracing/views/view.erb

@@ -0,0 +1,5 @@
+<h1><%= @page.title %></h1>
+
+<p>[<a href='/edit/<%= @page.title %>'>edit</a>]</p>
+
+<div><%= @page.body %></div>

data/examples/wiki-manual-tracing/wiki.rb

@@ -0,0 +1,180 @@
+require 'sinatra/base'
+require 'libhoney'
+
+# Page represents the data (and some basic operations) on a wiki page.
+#
+# While the tracing instrumentation in this example is constrained to the
+# handlers, we could just as easily propagate context down directly into this
+# class if needed.
+class Page
+  attr_reader :filename, :title
+  attr_accessor :body
+
+  def initialize(title)
+    @title = title
+    @filename = "#{title}.txt"
+  end
+
+  def exist?
+    File.exist? @filename
+  end
+
+  def save(body)
+    File.write @filename, body
+    true
+  rescue StandardError
+    false
+  end
+end
+
+# Generate a new unique identifier for our spans and traces. This can be any
+# unique string -- Zipkin uses hex-encoded base64 ints, as we do here; other
+# folks may prefer to use their UUID library of choice.
+def new_id
+  rand(2**63).to_s(16)
+end
+
+# This middleware treats each HTTP request as a distinct "trace." Each trace
+# begins with a top-level ("root") span indicating that the HTTP request has
+# begun.
+VALID_PATH = Regexp.new('^/(edit|save|view)/')
+
+class RequestTracer
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    Thread.current[:request_id] = new_id
+    match = env['REQUEST_PATH'].match(VALID_PATH)
+
+    @app.with_span(match ? match[1] : env['REQUEST_PATH']) do
+      @app.call env
+    end
+  end
+end
+
+# This is our basic wiki webapp. It uses our RequestTracer middleware to track
+# all HTTP requests with a root span, then defines a handful of handlers to
+# handle the display / edit / saving of wiki pages on disk.
+class App < Sinatra::Base
+  use RequestTracer
+
+  # Initialize our Honeycomb client once, and pull Honeycomb credentials from
+  # an environment variable.
+  configure do
+    set :libhoney, Libhoney::Client.new(
+      writekey: ENV['HONEYCOMB_API_KEY'],
+      dataset: 'ruby-wiki-tracing-example'
+    )
+  end
+
+  # Redirect to a default wiki page.
+  get '/' do
+    redirect '/view/Index'
+  end
+
+  # Our "View" handler. Tries to load a page from disk and render it. Falls back
+  # to the Edit handler if the page does not yet exist.
+  get '/view/:title' do |title|
+    @page = with_span('load_page', title: title) do
+      load_page title
+    end
+
+    return redirect "/edit/#{title}" if @page.nil?
+
+    with_span('render_template', template: 'view') do
+      erb :view
+    end
+  end
+
+  # Our "Edit" handler. Tries to load a page from disk to seed the edit screen,
+  # then renders a form to allow the user to define the content of the requested
+  # wiki page.
+  get '/edit/:title' do |title|
+    @page = with_span('load_page', title: title) do
+      load_page title
+    end
+
+    @page = Page.new(title) if @page.nil?
+
+    with_span('render_template', template: 'edit') do
+      erb :edit
+    end
+  end
+
+  # Our "Save" handler simply persists a page to disk.
+  post '/save/:page' do |title|
+    saved = with_span('File.write', title: title, body_len: params['body'].size) do
+      page = Page.new(title)
+      page.save(params['body'])
+    end
+
+    return redirect "/view/#{title}" if saved
+
+    'error'
+  end
+
+  # This wrapper takes a span name, some optional metadata, and a block; then
+  # emits a "span" to Honeycomb as part of the trace begun in the RequestTracer
+  # middleware.
+  #
+  # The special sauce in this method is the definition / resetting of thread
+  # local variables in order to correctly propagate "parent" identifiers down
+  # into the block.
+  def with_span(name, metadata = nil)
+    id = new_id
+    start = Time.new
+    # Field keys to trigger Honeycomb's tracing functionality on this dataset
+    # defined at:
+    # https://docs.honeycomb.io/getting-data-in/tracing/send-trace-data/#opentelemetry
+    data = {
+      name: name,
+      id: id,
+      "trace.trace_id": Thread.current[:request_id],
+      "service.name": 'wiki'
+    }
+
+    # Capture the calling scope's span ID, then restore it at the end of the
+    # method.
+    parent_id = Thread.current[:span_id]
+    data[:"trace.parent_id"] = parent_id if parent_id
+
+    # Set the current span ID before invoking the provided block, then capture
+    # the return value to return after emitting the Honeycomb event.
+    Thread.current[:span_id] = id
+    output = yield
+
+    data[:duration_ms] = (Time.new - start) * 1000
+    data.merge!(metadata) if metadata
+
+    event = settings.libhoney.event
+    # NOTE: Don't forget to set the timestamp to `start` -- because spans are
+    # emitted at the *end* of their execution, we want to be doubly sure that
+    # our manually-emitted events are timestamped with the time that the work
+    # (the span's actual execution) really begun.
+    event.timestamp = start
+    event.add data
+    event.send
+
+    output
+  ensure
+    Thread.current[:span_id] = parent_id
+  end
+
+  private
+
+  # Helper method for returning a Page object for easy rendering
+  def load_page(title)
+    page = Page.new(title)
+    return nil unless page.exist?
+
+    with_span('File.read') do
+      page.body = File.read(page.filename)
+      page
+    end
+  end
+end
+
+# Let's go!
+App.run!

data/lib/libhoney/client.rb

@@ -34,6 +34,7 @@ module Libhoney
     extend Forwardable
 
     API_HOST = 'https://api.honeycomb.io/'.freeze
+    DEFAULT_DATASET = 'unknown_dataset'.freeze
 
     # Instantiates libhoney and prepares it to send events to Honeycomb.
     #
@@ -81,7 +82,7 @@ module Libhoney
       @builder = Builder.new(self, nil)
 
       @builder.writekey    = writekey
-      @builder.dataset     = dataset
+      @builder.dataset     = get_dataset(dataset, writekey)
       @builder.sample_rate = sample_rate
       @builder.api_host    = api_host
 
@@ -275,5 +276,24 @@ module Libhoney
     rescue URI::Error => e
       warn "#{self.class.name}: unable to parse proxy_config. Detail: #{e.class}: #{e.message}"
     end
+
+    def get_dataset(dataset, write_key)
+      return dataset if classic_write_key?(write_key)
+
+      if dataset.nil? || dataset.empty?
+        warn "nil or empty dataset - sending data to '#{DEFAULT_DATASET}'"
+        dataset = DEFAULT_DATASET
+      end
+      trimmed = dataset.strip
+      if dataset != trimmed
+        warn "dataset contained leading or trailing whitespace - sending data to '#{trimmed}'"
+        dataset = trimmed
+      end
+      dataset
+    end
+
+    def classic_write_key?(write_key)
+      write_key.nil? || write_key.length == 32
+    end
   end
 end

data/lib/libhoney/version.rb

@@ -1,3 +1,3 @@
 module Libhoney
-  VERSION = '2.1.0'.freeze
+  VERSION = '2.2.0-dev'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: libhoney
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.0.pre.dev
 platform: ruby
 authors:
 - The Honeycomb.io Team
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-02-02 00:00:00.000000000 Z
+date: 2023-01-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bump
@@ -256,10 +256,11 @@ files:
 - ".github/ISSUE_TEMPLATE/security-vulnerability-report.md"
 - ".github/PULL_REQUEST_TEMPLATE.md"
 - ".github/dependabot.yml"
-- ".github/workflows/add-to-project.yml"
+- ".github/release.yml"
+- ".github/workflows/add-to-project-v2.yml"
 - ".github/workflows/apply-labels.yml"
-- ".github/workflows/re-triage.yml"
 - ".github/workflows/stale.yml"
+- ".github/workflows/validate-pr-title.yml"
 - ".gitignore"
 - ".rubocop.yml"
 - ".rubocop_todo.yml"
@@ -276,7 +277,13 @@ files:
 - Rakefile
 - SECURITY.md
 - SUPPORT.md
-- example/factorial.rb
+- examples/factorial/Gemfile
+- examples/factorial/factorial.rb
+- examples/wiki-manual-tracing/Gemfile
+- examples/wiki-manual-tracing/README.md
+- examples/wiki-manual-tracing/views/edit.erb
+- examples/wiki-manual-tracing/views/view.erb
+- examples/wiki-manual-tracing/wiki.rb
 - lib/libhoney.rb
 - lib/libhoney/builder.rb
 - lib/libhoney/cleaner.rb
@@ -311,11 +318,11 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
-rubygems_version: 3.2.32
+rubygems_version: 3.3.26
 signing_key: 
 specification_version: 4
 summary: send data to Honeycomb

data/.github/workflows/add-to-project.yml

@@ -1,14 +0,0 @@
-name: Apply project management flow
-on:
-  issues:
-    types: [opened]
-  pull_request_target:
-    types: [opened]
-jobs:
-  project-management:
-    runs-on: ubuntu-latest
-    name: Apply project management flow
-    steps:
-      - uses: honeycombio/oss-management-actions/projects@v1
-        with:
-          ghprojects-token: ${{ secrets.GHPROJECTS_TOKEN }}

data/.github/workflows/re-triage.yml

@@ -1,12 +0,0 @@
-name: Re-triage issues with new comments
-on:
-  issue_comment:
-    types: [created]
-jobs:
-  re-triage:
-    runs-on: ubuntu-latest
-    name: Re-triage issues with new comments
-    steps:
-      - uses: honeycombio/oss-management-actions/re-triage@v1
-        with:
-          ghprojects-token: ${{ secrets.GHPROJECTS_TOKEN }}