feat: add configurable defaults for annotation behavior

- Use has_constant? to check for user-defined LOG_ARGS_DEFAULT, LOG_RETURN_DEFAULT, LOG_EXCEPTION_DEFAULT
- Constants are NOT defined by Logit - users define them BEFORE requiring logit
- If not defined, all default to true (existing behavior)
- Per-method annotation options still override the defaults
- Add missing require for api.cr
- Document usage in library_integration.md

Author: watzon

docs/guide/library_integration.md

@@ -140,6 +140,44 @@ module MyLib
 end
 ```
 
+## Configuring Annotation Defaults
+
+By default, `@[Logit::Log]` logs method arguments, return values, and exceptions. Libraries may want to disable argument/return logging by default for privacy or performance reasons.
+
+Override the compile-time defaults **before** requiring your instrumented files:
+
+```crystal
+# my-lib/src/my-lib.cr
+
+# Override defaults BEFORE any instrumented code is required
+module Logit
+  LOG_ARGS_DEFAULT      = false  # Don't log arguments by default
+  LOG_RETURN_DEFAULT    = false  # Don't log return values by default
+  LOG_EXCEPTION_DEFAULT = true   # Still log exceptions
+end
+
+require "logit"
+require "./my-lib/**"
+```
+
+Now `@[Logit::Log]` will only log timing and exceptions. You can still explicitly enable argument/return logging per-method:
+
+```crystal
+class MyLib::Client
+  # Uses library defaults (no args/return)
+  @[Logit::Log]
+  def get(url : String) : Response
+    # ...
+  end
+
+  # Explicitly enable args for this method
+  @[Logit::Log(log_args: true)]
+  def debug_request(url : String, headers : Hash) : Response
+    # ...
+  end
+end
+```
+
 ## Best Practices
 
 ### 1. Never Configure Backends in Libraries

src/logit/logit.cr

@@ -26,9 +26,9 @@
 #
 # The `@[Logit::Log]` annotation supports the following options:
 #
-# - `log_args` (Bool) - Whether to log method arguments (default: true)
-# - `log_return` (Bool) - Whether to log return values (default: true)
-# - `log_exception` (Bool) - Whether to log exceptions (default: true)
+# - `log_args` (Bool) - Whether to log method arguments (default: true, or LOG_ARGS_DEFAULT if defined)
+# - `log_return` (Bool) - Whether to log return values (default: true, or LOG_RETURN_DEFAULT if defined)
+# - `log_exception` (Bool) - Whether to log exceptions (default: true, or LOG_EXCEPTION_DEFAULT if defined)
 # - `name` (String) - Custom span name (default: method name)
 # - `level` (LogLevel) - Log level for this method (default: Info)
 # - `redact` (Array(String)) - Argument names to redact from logs
@@ -45,6 +45,25 @@
 # See `Logit.configure` for configuration options and `Logit::Backend` for
 # available output backends.
 module Logit
+  # Compile-time defaults for annotation behavior.
+  #
+  # These constants are NOT defined by Logit. If you want to change the defaults,
+  # define them BEFORE requiring logit:
+  #
+  # ```crystal
+  # # In your app's entry point, BEFORE requiring logit:
+  # module Logit
+  #   LOG_ARGS_DEFAULT      = false  # Don't log arguments by default
+  #   LOG_RETURN_DEFAULT    = false  # Don't log return values by default
+  #   LOG_EXCEPTION_DEFAULT = false  # Don't log exceptions by default
+  # end
+  #
+  # require "logit"
+  # require "./my_app"
+  # ```
+  #
+  # If not defined, all default to `true`.
+
   # Annotation to mark methods for automatic logging instrumentation.
   #
   # When a method is annotated with `@[Logit::Log]`, Logit automatically:
@@ -101,4 +120,5 @@ require "./backends/otlp"
 require "./redaction"
 require "./context"
 require "./config"
+require "./api"
 require "./macros/register"

src/logit/macros/wrapper.cr

@@ -16,12 +16,17 @@ module Logit
           &{{block_arg[:name].id}} : {{block_arg[:type].id}}
         {% end %}
       ) {% if return_type && return_type != "" %}: {{return_type.id}}{% end %}
-        # Extract annotation options
+        # Extract annotation options (use global defaults if not specified)
+        # Check for user-defined defaults, otherwise use true
+        {% log_args_default = Logit.has_constant?(:LOG_ARGS_DEFAULT) ? Logit::LOG_ARGS_DEFAULT : true %}
+        {% log_return_default = Logit.has_constant?(:LOG_RETURN_DEFAULT) ? Logit::LOG_RETURN_DEFAULT : true %}
+        {% log_exception_default = Logit.has_constant?(:LOG_EXCEPTION_DEFAULT) ? Logit::LOG_EXCEPTION_DEFAULT : true %}
+
         # TODO: Support custom levels from annotation
         {% level_const = "Logit::LogLevel::Info" %}
-        {% log_args = ann && ann[:log_args] != nil ? ann[:log_args] : true %}
-        {% log_return = ann && ann[:log_return] != nil ? ann[:log_return] : true %}
-        {% log_exception = ann && ann[:log_exception] != nil ? ann[:log_exception] : true %}
+        {% log_args = ann && ann[:log_args] != nil ? ann[:log_args] : log_args_default %}
+        {% log_return = ann && ann[:log_return] != nil ? ann[:log_return] : log_return_default %}
+        {% log_exception = ann && ann[:log_exception] != nil ? ann[:log_exception] : log_exception_default %}
         {% span_name = ann && ann[:name] ? ann[:name] : method_name.stringify %}
         {% redact_list = ann && ann[:redact] ? ann[:redact] : [] of String %}