libhoney 2.2.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0867b211b613819cb14a3d4001d4a119d94a889a4aa8090f05f9233309786b63'
-  data.tar.gz: '0810087e42caf6553f088bad7744e650f7061e76c4ea89a5dc6ff1bf334b1b7e'
+  metadata.gz: 3fded3aff49e82adca1103c69e01bfcf6c25096f381b35b8d4506de69743a03a
+  data.tar.gz: fda0eecd31f9c23d206ad5eb85bd9a46979f2489fa2b0f6872551c3b79e898df
 SHA512:
-  metadata.gz: 7b3a51a0211491964afa320c12c25c919ac82362f1e42a1dfbbd27f8e6d0c5d09089ed9c4517d32e34dd2d884a9e5891c9878dce73a4668255a413854defe1de
-  data.tar.gz: 98faec4862aabf78f61f3f92c7374ec3e55a15bd517b8f9f04f3909defd56b89feb47dc6268df659463e8f219582985923a212644619027f782ccc90e0ce2c42
+  metadata.gz: a60d2c1de54c08e418cd2af91dd61d3656567cf6597c7e0ae7dbb812f4d94009d35f6de83f1c0f83cc0944034a40ee777483cc3aa9994a9c5893e42334d6df79
+  data.tar.gz: 1f2ab384a92d6125c69a93b8ef537b7ce80139b68e891ff22b1ad10f7c1f5ed754cb8bfd1df7359793b801bde2c0b7342a56ffc7c6f7ca6959e1180090d50700

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/CODEOWNERS

@@ -2,4 +2,4 @@
 # This file controls who is tagged for review for any given pull request.
 
 # For anything not explicitly taken by someone else:
-* @honeycombio/telemetry-team
+* @honeycombio/pipeline-team

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,25 @@
+# .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"
+        - "type: dependencies"
+        - "type: documentation"
+    - 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/27
+          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,24 @@
+## [2.3.0] - 2024-03-07
+
+### Enhancements
+
+- feat: support classic-flavored ingest keys (#138) | [robbkidd](https://github.com/robbkidd)
+
+### Maintenance
+
+- maint: add labels to release.yml for auto-generated grouping (#139) | [JamieDanielson](https://github.com/JamieDanielson)
+- maint: update codeowners to pipeline-team (#137) | [JamieDanielson](https://github.com/JamieDanielson)
+- maint: update codeowners to pipeline (#136) | [JamieDanielson](https://github.com/JamieDanielson)
+- docs: add development.md (#135) | [vreynolds](https://github.com/vreynolds)
+- chore: update dependabot title (#134) | [pkanal](https://github.com/pkanal)
+- ci: update validate PR title workflow (#133) | [pkanal](https://github.com/pkanal)
+- ci: validate PR title (#132) | [pkanal](https://github.com/pkanal)
+- maint: add wiki tracing example (#131) | [vreynolds](https://github.com/vreynolds)
+- maint: delete workflows for old board (#130) | [vreynolds](https://github.com/vreynolds)
+- maint: add release file (#129) | [vreynolds](https://github.com/vreynolds)
+- maint: add new project workflow (#128) | [vreynolds](https://github.com/vreynolds)
+- maint: add ruby 3.1 to CI matrix (#127) | [vreynolds](https://github.com/vreynolds)
+
 ## [2.2.0] - 2022-04-14
 
 ### Added

data/DEVELOPMENT.md

@@ -0,0 +1,31 @@
+# Local Development
+
+## Requirements
+
+Ruby: https://www.ruby-lang.org/en/documentation/installation/
+
+Rake:
+
+```shell
+gem install rake
+```
+
+## Install dependencies
+
+```shell
+bundle install
+```
+
+## Run Tests
+
+To run all tests:
+
+```shell
+bundle exec rake test
+```
+
+To run individual tests:
+
+```shell
+bundle exec rake test TEST=test/log_transmission_test.rb
+```

data/README.md

@@ -15,6 +15,8 @@ For tracing support and automatic instrumentation of Rails, Sinatra, Rack, Activ
 
 ## Contributions
 
+See [DEVELOPMENT.md](./DEVELOPMENT.md)
+
 Features, bug fixes and other changes to `libhoney` are gladly accepted. Please
 open issues or a pull request with your change. Remember to add your name to the
 CONTRIBUTORS file!

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

@@ -278,7 +278,7 @@ module Libhoney
     end
 
     def get_dataset(dataset, write_key)
-      return dataset if classic_write_key?(write_key)
+      return dataset if classic_api_key?(write_key)
 
       if dataset.nil? || dataset.empty?
         warn "nil or empty dataset - sending data to '#{DEFAULT_DATASET}'"
@@ -292,8 +292,9 @@ module Libhoney
       dataset
     end
 
-    def classic_write_key?(write_key)
-      write_key.nil? || write_key.length == 32
+    # @api private
+    def classic_api_key?(write_key)
+      Libhoney.classic_api_key?(write_key)
     end
   end
 end

data/lib/libhoney/version.rb

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

data/lib/libhoney.rb

@@ -6,3 +6,25 @@ require 'libhoney/version'
 require 'libhoney/builder'
 require 'libhoney/response'
 require 'libhoney/transmission'
+
+module Libhoney
+  # Determines if the given string is a Honeycomb API key for Classic environments.
+  #
+  # @param api_key [String] the string to check
+  # @return [Boolean] true if the string is nil or a classic API key, false otherwise
+  def self.classic_api_key?(api_key)
+    api_key.nil? || # default to classic behavior if no API key is provided
+      CLASSIC_KEY_ORIGINAL_FLAVOR.match?(api_key) ||
+      CLASSIC_KEY_V3_INGEST.match?(api_key)
+  end
+
+  # Private constant for key format detection.
+  # @api private
+  CLASSIC_KEY_ORIGINAL_FLAVOR = Regexp.new(/\A[[:alnum:]]{32}\z/)
+  private_constant :CLASSIC_KEY_ORIGINAL_FLAVOR
+
+  # Private constant for key format detection.
+  # @api private
+  CLASSIC_KEY_V3_INGEST = Regexp.new(/\Ahc[a-z]ic_[[:alnum:]]{58}\z/)
+  private_constant :CLASSIC_KEY_V3_INGEST
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: libhoney
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.3.0
 platform: ruby
 authors:
 - The Honeycomb.io Team
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-04-14 00:00:00.000000000 Z
+date: 2024-03-07 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"
@@ -267,6 +268,7 @@ files:
 - CODE_OF_CONDUCT.md
 - CONTRIBUTING.md
 - CONTRIBUTORS
+- DEVELOPMENT.md
 - Gemfile
 - LICENSE
 - NOTICE
@@ -276,7 +278,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
@@ -315,7 +323,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.11
+rubygems_version: 3.4.19
 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 }}