YARD docs for structured logger

Author: solnic

sentry-ruby/lib/sentry-ruby.rb

@@ -96,7 +96,24 @@ def exception_locals_tp
     attr_reader :metrics_aggregator
 
     # @!attribute [r] logger
-    #   @return [Logging::Device]
+    #   Returns the structured logger instance that implements Sentry's SDK telemetry logs protocol.
+    #   This logger is only available when logs are enabled in the configuration.
+    #
+    #   @example Enable logs in configuration
+    #     Sentry.init do |config|
+    #       config.dsn = "YOUR_DSN"
+    #       config._experiments = { enable_logs: true }
+    #     end
+    #
+    #   @example Basic usage
+    #     Sentry.logger.info("User logged in successfully", user_id: 123)
+    #     Sentry.logger.error("Failed to process payment",
+    #       transaction_id: "tx_123",
+    #       error_code: "PAYMENT_FAILED"
+    #     )
+    #
+    #   @see https://develop.sentry.dev/sdk/telemetry/logs/ Sentry SDK Telemetry Logs Protocol
+    #   @return [StructuredLogger, nil] The structured logger instance or nil if logs are disabled
     attr_reader :logger
 
     ##### Patch Registration #####
@@ -244,7 +261,9 @@ def init(&block)
       config = Configuration.new
       yield(config) if block_given?
 
-      # Public-facing Structured Logger
+      # Initialize the public-facing Structured Logger if logs are enabled
+      # This creates a StructuredLogger instance that implements Sentry's SDK telemetry logs protocol
+      # @see https://develop.sentry.dev/sdk/telemetry/logs/
       @logger = StructuredLogger.new(config) if config._experiments[:enable_logs]
 
       config.detect_release
@@ -499,12 +518,19 @@ def capture_check_in(slug, status, **options)
     end
 
     # Captures a log event and sends it to Sentry via the currently active hub.
+    # This is the underlying method used by the StructuredLogger class.
     #
     # @param message [String] the log message
     # @param [Hash] options Extra log event options
-    # @option options [Symbol] level The log level
+    # @option options [Symbol] level The log level (:trace, :debug, :info, :warn, :error, :fatal)
+    # @option options [Integer] severity The severity number according to the Sentry Logs Protocol
+    # @option options [Hash] Additional attributes to include with the log
     #
-    # @return [LogEvent, nil]
+    # @example Direct usage (prefer using Sentry.logger instead)
+    #   Sentry.capture_log("User logged in", level: :info, user_id: 123)
+    #
+    # @see https://develop.sentry.dev/sdk/telemetry/logs/ Sentry SDK Telemetry Logs Protocol
+    # @return [LogEvent, nil] The created log event or nil if logging is disabled
     def capture_log(message, **options)
       return unless initialized?
       get_current_hub.capture_log_event(message, **options)

sentry-ruby/lib/sentry/structured_logger.rb

@@ -1,8 +1,27 @@
 # frozen_string_literal: true
 
 module Sentry
+  # The StructuredLogger class implements Sentry's SDK telemetry logs protocol.
+  # It provides methods for logging messages at different severity levels and
+  # sending them to Sentry with structured data.
+  #
+  # This class follows the Sentry Logs Protocol as defined in:
+  # https://develop.sentry.dev/sdk/telemetry/logs/
+  #
+  # @example Basic usage
+  #   Sentry.logger.info("User logged in", user_id: 123)
+  #
+  # @example With structured data
+  #   Sentry.logger.warn("API request failed",
+  #     status_code: 404,
+  #     endpoint: "/api/users",
+  #     request_id: "abc-123"
+  #   )
+  #
+  # @see https://develop.sentry.dev/sdk/telemetry/logs/ Sentry SDK Telemetry Logs Protocol
   class StructuredLogger
-    # https://develop.sentry.dev/sdk/telemetry/logs/#log-severity-number
+    # Severity number mapping for log levels according to the Sentry Logs Protocol
+    # @see https://develop.sentry.dev/sdk/telemetry/logs/#log-severity-number
     LEVELS = {
       "trace" => 1,
       "debug" => 5,
@@ -12,36 +31,68 @@ class StructuredLogger
       "fatal" => 21
     }.freeze
 
+    # @return [Configuration] The Sentry configuration
     attr_reader :config
 
+    # Initializes a new StructuredLogger instance
+    # @param config [Configuration] The Sentry configuration
     def initialize(config)
       @config = config
     end
 
+    # Logs a message at TRACE level
+    # @param message [String] The log message
+    # @param payload [Hash] Additional attributes to include with the log
+    # @return [LogEvent, nil] The created log event or nil if logging is disabled
     def trace(message, payload = {})
       log(:trace, message, payload)
     end
 
+    # Logs a message at DEBUG level
+    # @param message [String] The log message
+    # @param payload [Hash] Additional attributes to include with the log
+    # @return [LogEvent, nil] The created log event or nil if logging is disabled
     def debug(message, payload = {})
       log(:debug, message, payload)
     end
 
+    # Logs a message at INFO level
+    # @param message [String] The log message
+    # @param payload [Hash] Additional attributes to include with the log
+    # @return [LogEvent, nil] The created log event or nil if logging is disabled
     def info(message, payload = {})
       log(:info, message, payload)
     end
 
+    # Logs a message at WARN level
+    # @param message [String] The log message
+    # @param payload [Hash] Additional attributes to include with the log
+    # @return [LogEvent, nil] The created log event or nil if logging is disabled
     def warn(message, payload = {})
       log(:warn, message, payload)
     end
 
+    # Logs a message at ERROR level
+    # @param message [String] The log message
+    # @param payload [Hash] Additional attributes to include with the log
+    # @return [LogEvent, nil] The created log event or nil if logging is disabled
     def error(message, payload = {})
       log(:error, message, payload)
     end
 
+    # Logs a message at FATAL level
+    # @param message [String] The log message
+    # @param payload [Hash] Additional attributes to include with the log
+    # @return [LogEvent, nil] The created log event or nil if logging is disabled
     def fatal(message, payload = {})
       log(:fatal, message, payload)
     end
 
+    # Logs a message at the specified level
+    # @param level [Symbol] The log level (:trace, :debug, :info, :warn, :error, :fatal)
+    # @param message [String] The log message
+    # @param payload [Hash] Additional attributes to include with the log
+    # @return [LogEvent, nil] The created log event or nil if logging is disabled
     def log(level, message, payload)
       Sentry.capture_log(message, level: level, severity: LEVELS[level], **payload)
     end