brut 0.9.2 → 0.11.0

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.

data/brutrb.com/recipes/form-errors.md

@@ -0,0 +1,148 @@
+# Styling Form Errors
+
+Brut makes it as easy as possible to unify client-side and server-side constraint violation handling, including
+how you style those messages.
+
+## Requirements
+
+What you want:
+
+* When a form is rendered for the first time, there should be errors shown.
+* When a visitor interacts with a form before submissions, no errors are shown.
+* When the form is submitted, client-side constraint violations should be shown.
+* When JavaScript is circumvented and the form is submitted with client-side constraint violations, the form should be re-generated, showing those violations the same is if JavaScripts was *not* circumvented
+* When there are no client-side constraint violations, but there *are* server-side violations, the form should be re-generated, showing those violations the same is if JavaScripts was *not* circumvented
+
+This can be achieved through CSS.
+
+## Recipe
+
+### Create Pages and HTML
+
+First, create a form and handler:
+
+```
+bin/scaffold form /new_widget
+```
+
+Edit `app/src/front_end/forms/new_widget_form.rb`
+
+```ruby
+class NewWidgetForm < AppForm
+  input :name, minlength: 3
+  input :description
+end
+```
+
+Now, implement the handler in `app/src/front_end/handlers/new_widget_handler.rb` to check for client-side violations *and* require that the description have at
+least 5 words in it.
+
+```ruby
+class NewWidgetHandler < AppHandler
+  def initialize(form:)
+    @form = form
+  end
+
+  def handle
+    if @form.valid?
+      if @form.description.split(/\s+/).length < 5
+      @form.server_side_constraint_violation(
+        input_name: :description,
+        key: :not_enough_words
+      )
+    end
+
+    if @form.constraint_violations?
+      NewWidgetPage.new(form: @form)
+    else
+      redirect_to(HomePage)
+    end
+  end
+end
+```
+
+Add the new error message to `app/config/i18n/en/2_app.rb`
+
+```ruby {6}
+{
+  en: {
+    nevermind: "Nevermind",
+    cv: {
+      ss: {
+        not_enough_words: "%{field} must have at least %{minwords} words",
+      },
+      # ...
+```
+
+Now, build a minimal `NewWidgetPage`:
+
+```
+bin/scaffold page /new_widget`
+```
+
+We'll create the bare minimum in `app/src/front_end/pages/new_widget_page.rb`
+
+```ruby
+class NewWidgetPage < AppPage
+  def initialize(form: nil)
+    @form = form || NewWidgetForm.new
+  end
+
+  def page_template
+    brut_form do
+      FormTag(for: @form) do
+        label do
+          Inputs::InputTag(form: @form, input_name: :name)
+          ConstraintViolations(form: @form, input_name: :name)
+          span { "Name" }
+        end
+        label do
+          Inputs::TextareaTag(form: @form, input_name: :name)
+          ConstraintViolations(form: @form, input_name: :name)
+          span { "Description" }
+        end
+      end
+    end
+  end
+end
+```
+
+### Create CSS
+
+The most minimal CSS would be as followed, which you can place in `app/src/front_end/css/index.css`
+
+```css
+brut-cv {
+  display: none;
+}
+
+brut-form[submitted-invalid] brut-cv,
+brut-cv[server-generated] {
+  display: block;
+  color: red;
+}
+```
+
+This will show the messages in `<brut-cv>` *only* if:
+
+* Form submission was attempted (`submitted-invalid` would be set on `<brut-form>`)
+* The server generated via `ConstraintViolations` (only if the handler was triggered)
+
+Because more than one `<brut-cv>` could be generated or inserted, you may want to style the
+`<brut-cv-messages>` that contains them, but you only want it to show up if it has contents.
+
+You can't just do `brut-cv-messages:has(brut-cv)`, because your container would show up before the form
+submission was attempted.
+
+Here is what you want instead. This will put the error messages in a red box:
+
+```css
+brut-form[submitted-invalid] brut-cv-messages:has(brut-cv),
+brut-cv-messages:has(brut-cv[server-generated]) {
+  color: red;
+  background-color: pink;
+  border: solid thin red;
+  border-radius: 1rem;
+}
+```
+