module Logit

Overview

Logit - Annotation-based logging with OpenTelemetry support for Crystal.

Logit provides automatic method instrumentation through annotations, structured logging with wide events, and full OpenTelemetry compatibility. Simply annotate methods with @[Logit::Log] and Logit handles the rest.

Quick Start

require "logit"

# Configure Logit (optional - defaults to console output)
Logit.configure do |config|
  config.console(level: Logit::LogLevel::Debug)
end

class MyService
  @[Logit::Log]
  def process(data : String) : String
    data.upcase
  end
end

Annotation Options

The @[Logit::Log] annotation supports the following options:

• 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

Key Features

• Automatic instrumentation: No manual log calls needed
• OpenTelemetry semantics: Trace IDs, span IDs, and semantic attributes
• Fiber-aware context: Spans are tracked per-fiber for safe concurrency
• Flexible backends: Console, file, or custom backends
• Namespace filtering: Control log levels per namespace pattern
• Redaction support: Automatically redact sensitive data

See Logit.configure for configuration options and Logit::Backend for available output backends.

Defined in:

Constant Summary

VERSION = "0.1.0"

Class Method Summary

• .add_context(hash : Hash(String, String)) : Nil

  Adds method-local context from a hash.

• .add_context(named_tuple : NamedTuple) : Nil

  Adds method-local context from a named tuple.

• .add_context(**kwargs) : Nil

  Adds method-local context that is cleared after the current method completes.

• .add_fiber_context(hash : Hash(String, String)) : Nil

  Adds fiber-local context from a hash.

• .add_fiber_context(named_tuple : NamedTuple) : Nil

  Adds fiber-local context from a named tuple.

• .add_fiber_context(**kwargs) : Nil

  Adds fiber-local context that persists across method calls in this fiber.

• .clear_context : Nil

  Clears all method-local context.

• .clear_fiber_context : Nil

  Clears all fiber-local context.

• .configure(&) : Config

  Configures Logit with the provided block and applies the configuration.

• .debug(message : String, **kwargs) : Nil

  Logs a message at Debug level.

• .debug(**kwargs, &block : -> String) : Nil

  Logs a message at Debug level with lazy evaluation.

• .error(message : String, **kwargs) : Nil

  Logs a message at Error level.

• .error(**kwargs, &block : -> String) : Nil

  Logs a message at Error level with lazy evaluation.

• .exception(message : String, ex : Exception, level : LogLevel, **kwargs) : Nil

  Logs an exception at a specific level.

• .exception(message : String, ex : Exception, **kwargs) : Nil

  Logs an exception with full details at Error level.

• .fatal(message : String, **kwargs) : Nil

  Logs a message at Fatal level.

• .fatal(**kwargs, &block : -> String) : Nil

  Logs a message at Fatal level with lazy evaluation.

• .get_context(key : String) : String | Nil

  Gets a method-local context value.

• .get_fiber_context(key : String) : String | Nil

  Gets a fiber-local context value.

• .info(message : String, **kwargs) : Nil

  Logs a message at Info level.

• .info(**kwargs, &block : -> String) : Nil

  Logs a message at Info level with lazy evaluation.

• .trace(message : String, **kwargs) : Nil

  Logs a message at Trace level.

• .trace(**kwargs, &block : -> String) : Nil

  Logs a message at Trace level with lazy evaluation.

• .warn(message : String, **kwargs) : Nil

  Logs a message at Warn level.

• .warn(**kwargs, &block : -> String) : Nil

  Logs a message at Warn level with lazy evaluation.

Macro Summary

• logit_add_context(**kwargs)

  Add key-value pairs to the current logging context

• logit_with_context(**kwargs, &block)

  Execute a block with additional context that is automatically removed after

• setup_instrumentation(type_name)

  Setup macro to be called at the END of a class definition (for manual instrumentation) This generates wrapper methods for all @Log annotated methods Note: In most cases, you should rely on the global macro finished hook instead

Class Method Detail

@[Logit::Log]
def process(item : Item) : Bool
  Logit.add_context(item_type: item.type)
  # ... context is included in this method's log event
  true
end  # context cleared here

# At the start of a request
Logit.add_fiber_context(request_id: request.id, user_id: current_user.id)

# All logs in this fiber now include request_id and user_id
process_request
save_data

# At the end of the request
Logit.clear_fiber_context

Logit.configure do |config|
  config.console(level: Logit::LogLevel::Debug)
  config.file("logs/app.log")
  config.redact_common_patterns
end

Macro Detail