brut 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb034356c94bcb184b5ded4c4d6d07d46d85e28371cbe7fd17ea999c78e1932e
-  data.tar.gz: 90339e125f3b8b9bde9bda634f4934d0c0a09955141cda41969c9347b7b86877
+  metadata.gz: c8a571939eb22e8583c8c44e8744565ef08cd08930fd3f378bc15ac245bc37da
+  data.tar.gz: 36fae7a408ca4a74d884e5fcc031e68920828bb17414d8b56bf9aff96df8c7e4
 SHA512:
-  metadata.gz: 1ad76fb17f0247373ded5eb4df807eab9f32db39633082afb647b6b268d6d74f1529b433f3a3a06c5cd101e79d841f3533bef589940de3d629af3c7c400096d0
-  data.tar.gz: 50acf68486d2bbcb6600fb2cf0e21f62ec879ba1a3f0767557d29f9e2260229cc4bdad4b869d800cfdc7101723eca7afb4498577f44b22095a24526ec9526a45
+  metadata.gz: e63645bd0090fb42de67b546b691cf2cf062da716938a8009db7caf556c613d64085fdc424c5d0c8d30f5edecb69aa58d6b273930309a221a56f36f8241cca49
+  data.tar.gz: db7fc64ad5d4b9615bd9217e73536a7c708a46ae1723841bc3fd2dfc524bee7a93b0e666533c4ed9ddbcbe0e86bcf8b6168c7146bed70a09fab32fbf87b59066

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Brut CHANGELOG
 
+## v0.11.0 - Aug 27, 2025
+
+* Added `Brut::Instrumentation::Methods` to allow instrumenting existing methods via `instrument`:
+  ```ruby
+  class Widget
+    include Brut::Instrumentation::Methods
+
+    instrument def save
+    end
+  end
+  ```
+  See docs for more options and details.
+* When an exception is caught in a span, the span's status is set to an error.
+
 ## v0.10.0 - Aug 15, 2025
 
 * Changed `ConstraintViolations` HTML to indicate if a `<brut-cv>` is server-generated, even if it's generating  client-side constraint. See #56.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    brut (0.10.0)
+    brut (0.11.0)
       concurrent-ruby
       i18n
       irb
@@ -23,7 +23,7 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (8.0.2)
+    activesupport (8.0.2.1)
       base64
       benchmark (>= 0.3)
       bigdecimal
@@ -47,26 +47,26 @@ GEM
     dotenv (3.1.8)
     drb (2.2.3)
     erb (5.0.2)
-    factory_bot (6.5.4)
+    factory_bot (6.5.5)
       activesupport (>= 6.1.0)
     faker (3.5.2)
       i18n (>= 1.8.11, < 2)
-    google-protobuf (4.31.1)
+    google-protobuf (4.32.0)
       bigdecimal
       rake (>= 13)
-    google-protobuf (4.31.1-aarch64-linux-gnu)
+    google-protobuf (4.32.0-aarch64-linux-gnu)
       bigdecimal
       rake (>= 13)
-    google-protobuf (4.31.1-arm64-darwin)
+    google-protobuf (4.32.0-arm64-darwin)
       bigdecimal
       rake (>= 13)
-    google-protobuf (4.31.1-x86-linux-gnu)
+    google-protobuf (4.32.0-x86-linux-gnu)
       bigdecimal
       rake (>= 13)
-    google-protobuf (4.31.1-x86_64-darwin)
+    google-protobuf (4.32.0-x86_64-darwin)
       bigdecimal
       rake (>= 13)
-    google-protobuf (4.31.1-x86_64-linux-gnu)
+    google-protobuf (4.32.0-x86_64-linux-gnu)
       bigdecimal
       rake (>= 13)
     googleapis-common-protos-types (1.20.0)
@@ -99,7 +99,7 @@ GEM
       racc (~> 1.4)
     nokogiri (1.18.9-x86_64-linux-gnu)
       racc (~> 1.4)
-    opentelemetry-api (1.5.0)
+    opentelemetry-api (1.6.0)
     opentelemetry-common (0.22.0)
       opentelemetry-api (~> 1.0)
     opentelemetry-exporter-otlp (0.30.0)
@@ -111,7 +111,7 @@ GEM
       opentelemetry-semantic_conventions
     opentelemetry-registry (0.4.0)
       opentelemetry-api (~> 1.1)
-    opentelemetry-sdk (1.8.0)
+    opentelemetry-sdk (1.8.1)
       opentelemetry-api (~> 1.1)
       opentelemetry-common (~> 0.20)
       opentelemetry-registry (~> 0.2)
@@ -149,7 +149,7 @@ GEM
     rdoc (6.14.2)
       erb
       psych (>= 4.0.0)
-    regexp_parser (2.11.1)
+    regexp_parser (2.11.2)
     reline (0.6.2)
       io-console (~> 0.5)
     rspec (3.13.1)
@@ -164,8 +164,8 @@ GEM
     rspec-mocks (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.4)
-    rubocop (1.79.2)
+    rspec-support (3.13.5)
+    rubocop (1.80.1)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -202,7 +202,7 @@ GEM
       concurrent-ruby (~> 1.0)
     tzinfo-data (1.2025.2)
       tzinfo (>= 1.0.0)
-    unicode-display_width (3.1.4)
+    unicode-display_width (3.1.5)
       unicode-emoji (~> 4.0, >= 4.0.4)
     unicode-emoji (4.0.4)
     uri (1.0.3)

data/bin/new-version

@@ -1,8 +1,8 @@
 set -e
 
+VIM=nvim
 if [ -f /.dockerenv ]; then
-  echo "Do not run this inside Docker"
-  exit 1
+  VIM=vim
 fi
 
-nvim -o lib/brut/version.rb mkbrut/lib/mkbrut/version.rb brut-js/package.json brut-css/package.json CHANGELOG.md
+$VIM -o lib/brut/version.rb mkbrut/lib/mkbrut/version.rb brut-js/package.json brut-css/package.json CHANGELOG.md

data/brut-css/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "brut-css",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "brut-css",
-      "version": "0.10.0",
+      "version": "0.11.0",
       "license": "Hippocratic-2.1",
       "devDependencies": {
         "comment-parser": "^1.4.1",

data/brut-css/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brut-css",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Utility CSS Library for Full Stack Developers",
   "keywords": [
     "css"

data/brut-js/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "brut-js",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "brut-js",
-      "version": "0.10.0",
+      "version": "0.11.0",
       "license": "Hippocratic-2.1",
       "devDependencies": {
         "esbuild": "^0.24.0",

data/brut-js/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brut-js",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "type": "module",
   "keywords": [ "WebComponents", "Custom Elements" ],
   "bugs": {

data/brutrb.com/getting-started.md

@@ -9,6 +9,7 @@ The simplest way to use `mkbrut` is to use an existing [Docker image](https://hu
 
 ```
 docker run \
+       --pull always \
        -v "$PWD":"$PWD" \
        -w "$PWD" \
        -u $(id -u):$(id -g) \
@@ -33,6 +34,7 @@ For now:
 
 ``` [Docker-based]
 docker run \
+       --pull always \
        -v "$PWD":"$PWD" \
        -w "$PWD" \
        -u $(id -u):$(id -g) \
@@ -55,6 +57,7 @@ To create your app without the demo components:
 
 ``` [Docker-based]
 docker run \
+       --pull always \
        -v "$PWD":"$PWD" \
        -w "$PWD" \
        -u $(id -u):$(id -g) \

data/brutrb.com/instrumentation.md

@@ -80,7 +80,99 @@ Here is a non-exhaustive list of what Brut automatically instruments:
 
 ### Adding Your Own Instrumentation
 
-You can add instrumentation in a few ways:
+You can add instrumentation in two main ways, both of which can be used together.
+
+#### Instrumenting Existing Methods
+
+Although Brut instruments the entrypoints to pages, handlers, and components, you will likely have your own set of back-end business logic that needs to be instrumented.  If you aren't trying to diagnose a specific problem and just want to see your back-end class' methods show up in your instrumentation vendor's dashboard, `Brut::Instrumentation::Methods` will be the easiest way to do that.
+
+`Brut::Instrumentation::Methods` can be included in any class, and provides three class methods, which are *mutually exclusive*:
+
+* `instrument_all` instruments all methods, public and private.
+* `instrument_public` instruments only public methods.
+* `instrument` instruments one or more named methods.
+
+`initialize` is never instrumented.
+
+Consider this class:
+
+```ruby
+class Widget
+  def initialize
+    # ...
+  end
+
+  def search
+    # ...
+  end
+
+  def save
+    # ...
+  end
+
+private
+
+  def delete_orphans
+    # ...
+  end
+end
+```
+
+If we use `instrument_all`…
+
+```ruby
+class Widget
+  include Brut::Instrumentation::Methods
+  instrument_all
+
+  # ...
+end
+```
+
+…`search`, `save`, and `delete_orphans` will be instrumented.  If we use `instrument_public`…
+
+```ruby
+class Widget
+  include Brut::Instrumentation::Methods
+  instrument_public
+
+  # ...
+end
+```
+
+…then only `search` and `save` are instrumented.
+
+We can pick and choose by using `instrument`.
+
+```ruby{2,7,20}
+class Widget
+  include Brut::Instrumentation::Methods
+  def initialize
+    # ...
+  end
+
+  instrument def search
+    # ...
+  end
+
+  def save
+    # ...
+  end
+
+private
+
+  def delete_orphans
+    # ...
+  end
+  instrument :delete_orphans
+end
+```
+
+Above, `search` and `delete_orphans` are instrumented. Since `def` in Ruby returns a symbol, `instrument def search` is the same as `instrument :search`.
+
+#### Explicit Instrumentation with Spans, Attributes, and Events
+
+To add explicit instrumentation, you'll create one or more of the following:
 
 * *Spans* record a block of code. They are shown as a sub-span if one is already in effect.  When you
 create a span, that means it will be shown in the context of the HTTP request.
@@ -164,6 +256,39 @@ aforementioned `InstrumentationHandler`.
 
 You should then see client-side tracing information as a sub-span of your HTTP request.  The information available depends on the browser, and some browsers don't send much. Also keep in mind that clock drift is real and while client-side timings are accurate, the timestamps will not be.
 
+### Logging
+
+Brut configures [SemanticLogger](https://logger.rocketjob.io/), but uses it sparingly.  Currently, Brut performs very little logging, and no request logging.  You may have noticed that your app doesn't produce a lot of output in development.  Brut's assumption is that you will use an OpenTelemetry vendor to understand your app in production or the otel-desktop-viewer in developoment.
+
+That said, since SemanticLogger is configured, you can use it at will:
+
+```ruby
+class HomePage
+  def page_template
+    SemanticLogger[self.class].debug "page being rendered"
+    
+    # ...
+
+  end
+end
+```
+
+The logging system is currently not very configurable, and works as follows:
+
+* In development, log messages are written to the standard output and to `logs/development.log`
+* In test, log messages are written to `logs/test.log`
+* In production, log messages are written to the standard output
+
+The default log level is "debug" for the web app at "fatal" for CLI apps.  You can set `LOG_LEVEL` in the environment to change this:
+
+* `"debug"` - Show all messages
+* `"info"` -  Show info and above (not debug messages)
+* `"warn"` -  Show warnings and above (not info, not debug)
+* `"error"` -  Show errors and fatals only
+* `"fatal"` -  Show fatals only
+
+Most CLIs also allow `--log-level` to accept one of these strings as wel ass `--verbose` to set the log level to debug.
+
 ## Testing
 
 Generally you don't want to test instrumentation unless it's highly complex and critical to the app's
@@ -182,11 +307,25 @@ specific issues.
 > Technical Notes are for deeper understanding and debugging. While we will try to keep them up-to-date with changes to Brut's
 > internals, the source code is always more correct.
 
-_Last Updated June 12, 2025_
+_Last Updated Aug 27, 2025_
+
+OpenTelemetry is notoriously opaque and, ironically, unobservable in its own behavior.  Thus, the implementation is subject to change as I figure out what actually does what.
 
+### Web Requests
 
-Brut does not have plans to support non-OTel instrumentation, nor does it have plans to provide hooks to use proprietary formats.
+`Brut::FrontEnd::Middlewares::OpenTelemetrySpan` is configured in `Brut::Framework::MCP` as the first middleware.  It sets up the outer span for all web requests.  Inside each request block (the code internal to Brut that calls handlers or pages), this span's name is modified with the HTTP method and path via the `brut.otel.root_span` in the Rack environment.
+
+### Client-Side
 
 The client-side portion of this is highly customized.  The Otel open source code for the client side is
 massive and hugely complex, so Brut decided to try to produce something simple and straightforward as a
 start. This can and will evolve over time.
+
+### CLI Commands
+
+Brut CLI commands are instrumented as well,
+in `Brut::CLI::App` in `execute!`, however the trace only begins if the underlying command is going to be executed. This may change.
+
+### Sidekiq Jobs
+
+Although Brut currently does not provide a default Sidekiq configuration, if you set up Sidekiq and include the `opentelemetry-instrumentation-sidekiq` gem in your app's `Gemfile`, you should see instrumentation of your Sidekiq jobs.  In practice, this default set up doesn't seem to work very well, so expect this to change for the better.