docs: update documentation for telemetry logging features

- Added comprehensive logging telemetry section to README
- Documented new log event types and handlers
- Added usage examples for custom telemetry handlers
- Updated CLAUDE.md with logging telemetry information
- Included configuration options for default handler

All documentation now reflects the telemetry-based logging system.

Author: GSMLG-BOT

CLAUDE.md

@@ -157,5 +157,25 @@ The library emits telemetry events for monitoring:
 - File operations: `[:caddy, :file, :read]`, `[:caddy, :file, :write]`
 - Validation: `[:caddy, :validation, :success]`, `[:caddy, :validation, :error]`
 - Adaptation: `[:caddy, :adapt, :success]`, `[:caddy, :adapt, :error]`
+- Logging operations: `[:caddy, :log, :debug]`, `[:caddy, :log, :info]`, `[:caddy, :log, :warning]`, `[:caddy, :log, :error]`
+- Log buffer/store: `[:caddy, :log, :received]`, `[:caddy, :log, :buffered]`, `[:caddy, :log, :buffer_flush]`, `[:caddy, :log, :stored]`, `[:caddy, :log, :retrieved]`
+
+### Telemetry-Based Logging
+
+All logging throughout the codebase uses telemetry events instead of direct Logger calls:
+
+```elixir
+# Application code uses telemetry for logging
+Caddy.Telemetry.log_debug("Server starting", module: __MODULE__)
+Caddy.Telemetry.log_info("Configuration loaded", config_id: 123)
+Caddy.Telemetry.log_warning("Deprecation notice", function: "old_api")
+Caddy.Telemetry.log_error("Operation failed", reason: :timeout)
+```
+
+A default handler (`Caddy.Logger.Handler`) automatically forwards log events to Elixir's Logger. This can be disabled:
+
+```elixir
+config :caddy, attach_default_handler: false
+```
 
 Use `Caddy.Telemetry.list_events/0` to see all available events.

README.md

@@ -74,24 +74,69 @@ The library includes comprehensive telemetry support for monitoring Caddy operat
 - **File operations**: `[:caddy, :file, :read]`, `[:caddy, :file, :write]`
 - **Validation**: `[:caddy, :validation, :success]`, `[:caddy, :validation, :error]`
 - **Adaptation**: `[:caddy, :adapt, :success]`, `[:caddy, :adapt, :error]`
+- **Logging operations**: `[:caddy, :log, :debug]`, `[:caddy, :log, :info]`, `[:caddy, :log, :warning]`, `[:caddy, :log, :error]`
+- **Log buffer/store**: `[:caddy, :log, :received]`, `[:caddy, :log, :buffered]`, `[:caddy, :log, :buffer_flush]`, `[:caddy, :log, :stored]`, `[:caddy, :log, :retrieved]`
+
+### Logging with Telemetry
+
+All logging operations emit telemetry events. By default, a handler automatically forwards log events to Elixir's Logger:
+
+```elixir
+# Use telemetry-based logging (instead of Logger directly)
+Caddy.Telemetry.log_debug("Server starting", module: MyApp)
+Caddy.Telemetry.log_info("Configuration loaded", config_id: 123)
+Caddy.Telemetry.log_warning("Deprecation warning", function: "old_api")
+Caddy.Telemetry.log_error("Failed to connect", reason: :timeout)
+```
+
+Configure logging behavior:
+
+```elixir
+config :caddy,
+  attach_default_handler: true,  # Auto-forward logs to Logger (default: true)
+  log_level: :info               # Minimum level to log (default: :debug)
+```
+
+### Custom Telemetry Handlers
+
+Attach custom handlers to process log events:
+
+```elixir
+# Send errors to external monitoring service
+:telemetry.attach("error_reporter", [:caddy, :log, :error],
+  fn _event, _measurements, metadata, _config ->
+    MyApp.ErrorReporter.report(metadata.message, metadata)
+  end, %{})
+
+# Monitor log buffer performance
+:telemetry.attach("buffer_monitor", [:caddy, :log, :buffered],
+  fn _event, measurements, _metadata, _config ->
+    MyApp.Metrics.track_buffer_size(measurements.buffer_size)
+  end, %{})
+```
 
 ### Usage Example
 
 ```elixir
 # Attach telemetry handler
 :telemetry.attach_many("caddy_handler", [
   [:caddy, :config, :set],
-  [:caddy, :server, :start]
+  [:caddy, :server, :start],
+  [:caddy, :log, :error]
 ], fn event_name, measurements, metadata, _config ->
   IO.inspect({event_name, measurements, metadata})
 end, %{})
 
-# Start telemetry poller
+# Start telemetry poller for system metrics
 Caddy.Telemetry.start_poller(30_000)
 ```
 
 ### Available Functions
 
+- `Caddy.Telemetry.log_debug/2` - Emit debug log event
+- `Caddy.Telemetry.log_info/2` - Emit info log event
+- `Caddy.Telemetry.log_warning/2` - Emit warning log event
+- `Caddy.Telemetry.log_error/2` - Emit error log event
 - `Caddy.Telemetry.emit_config_change/3` - Configuration change events
 - `Caddy.Telemetry.emit_server_event/3` - Server lifecycle events
 - `Caddy.Telemetry.emit_api_event/3` - API operation events