Logcraft

https://github.com/zormandi/logcraft
Admin
A zero-configuration structured logging solution for pure Ruby or Ruby on Rails projects.
Tokens:4,031
Snippets:49
Trust Score:6.6
License:MIT
Update:4 months ago
Show doc for...
Tokens:
Raw
### Formatted Logcraft Access Log Example

Source: https://github.com/zormandi/logcraft/blob/main/README.md

A human-readable, pretty-printed JSON representation of a Logcraft access log entry.

```json
{
  "timestamp": "2022-06-26T18:07:08.103+02:00",
  "level": "INFO",
  "logger": "AccessLog",
  "hostname": "MacbookPro.local",
  "pid": 80908, 
  "request_id": "9a43631b-284c-4677-9d08-9c1cc5c7d3a7",
  "message": "GET /welcome?subsession_id=34ea8596f9764f475f81158667bc2654 - 200 (OK)",
  "remote_ip": "127.0.0.1",
  "method": "GET",
  "path": "/welcome?subsession_id=34ea8596f9764f475f81158667bc2654",
  "params": {
    "subsession_id": "34ea8596f9764f475f81158667bc2654",
    "controller": "pages",
    "action": "welcome"
  }, 
  "response_status_code": 200, 
  "duration": 31, 
  "duration_sec": 0.031
}
```

--------------------------------

### Rails Default vs. Logcraft Access Log

Source: https://github.com/zormandi/logcraft/blob/main/README.md

Compares the verbose default Rails logging for a GET request with Logcraft's concise, single-line JSON access log output.

```text
GET /welcome?subsession_id=34ea8596f9764f475f81158667bc2654

With default Rails logging:

Started GET "/welcome?subsession_id=34ea8596f9764f475f81158667bc2654" for 127.0.0.1 at 2022-06-26 18:07:08 +0200
Processing by PagesController#welcome as HTML
  Parameters: {"subsession_id"=>"34ea8596f9764f475f81158667bc2654"}
  Rendering pages/welcome.html.haml within layouts/application
  Rendered pages/welcome.html.haml within layouts/application (5.5ms)
Completed 200 OK in 31ms (Views: 27.3ms | ActiveRecord: 0.0ms)
```

```json
{"timestamp":"2022-06-26T18:07:08.103+02:00","level":"INFO","logger":"AccessLog","hostname":"MacbookPro.local","pid":80908,"request_id":"9a43631b-284c-4677-9d08-9c1cc5c7d3a7","message":"GET /welcome?subsession_id=34ea8596f9764f475f81158667bc2654 - 200 (OK)","remote_ip":"127.0.0.1","method":"GET","path":"/welcome?subsession_id=34ea8596f9764f475f81158667bc2654","params":{"subsession_id":"34ea8596f9764f475f81158667bc2654","controller":"pages","action":"welcome"},"response_status_code":200,"duration":31,"duration_sec":0.031}
```

--------------------------------

### Custom Log Level Formatter in Rails

Source: https://github.com/zormandi/logcraft/blob/main/README.md

Implement a custom formatter for the log level, such as Ougai-like numbers. The example shows how a custom level formatter can alter the output level.

```ruby
config.logcraft.layout_options.level_formatter = ->(level_number) { (level_number + 2) * 10 }
```

```ruby
Rails.logger.error('Boom!')
# => {...,"level":50,"message":"Boom!"}
```

--------------------------------

### Custom Log Event Formatter in Rails

Source: https://github.com/zormandi/logcraft/blob/main/README.md

Define a custom formatter for the entire log event. This must return a single string. Examples show YAML and pretty-printed JSON output.

```ruby
config.logcraft.layout_options.formatter = ->(event) { YAML.dump event }
```

```ruby
config.logcraft.layout_options.formatter = ->(event) { JSON.pretty_generate(event) + "\n----------------\n" }
```

--------------------------------

### Configure DataDog Global Context

Source: https://github.com/zormandi/logcraft/blob/main/README.md

Set up global context for DataDog tracing by providing a lambda that returns a hash. This context is included in every log message when DataDog tracing is enabled.

```ruby
config.logcraft.global_context = -> do
  return {} unless Datadog::Tracing.enabled?

  correlation = Datadog::Tracing.correlation
  {
    dd: {
      trace_id: correlation.trace_id.to_s,
      span_id: correlation.span_id.to_s,
      env: correlation.env.to_s,
      service: correlation.service.to_s,
      version: correlation.version.to_s
    },
    ddsource: 'ruby'
  }
end
```

--------------------------------

### Create and Use a Logcraft Logger

Source: https://github.com/zormandi/logcraft/blob/main/README.md

Instantiate a logger with a name and log messages. Logcraft automatically adds timestamp, level, logger name, hostname, and PID to each log entry.

```ruby
logger = Logcraft.logger 'Application'

logger.info 'Log message'
# => {"timestamp":"2022-06-26T17:52:57.845+02:00","level":"INFO","logger":"Application","hostname":"MacbookPro.local","pid":80422,"message":"Log message"}
```

```ruby
logger.info message: 'User logged in', user_id: 42
# => {"timestamp":"2022-06-26T17:44:01.926+02:00","level":"INFO","logger":"Application","hostname":"MacbookPro.local","pid":80422,"message":"User logged in","user_id":42}
```

--------------------------------

### Initialize Logcraft in Non-Rails Application

Source: https://github.com/zormandi/logcraft/blob/main/README.md

For non-Rails applications, add the Logcraft gem to your Gemfile and call Logcraft.initialize during application startup.

```ruby
gem 'logcraft'
```

```ruby
Logcraft.initialize
```

--------------------------------

### Initialize Logcraft for Non-Rails Projects

Source: https://github.com/zormandi/logcraft/blob/main/README.md

Configure Logcraft for non-Rails applications using the initialization mechanism. This allows setting the log level, global context, and layout options.

```ruby
Logcraft.initialize log_level: :info, global_context: {}, layout_options: {}
```

--------------------------------

### Logcraft JSON Serialization Comparison

Source: https://github.com/zormandi/logcraft/blob/main/README.md

Compares logging a string with special characters using Logcraft with default ActiveSupport serialization versus using the Oj gem.

```ruby
# With default ActiveSupport serialization
Rails.logger.info 'foo > bar'
#=> {...,"message":"foo \u003e bar"}

# With Oj
Rails.logger.info 'foo > bar'
#=> {...,"message":"foo > bar"}
```

--------------------------------

### Whitelist Parameters for Access Log in Rails

Source: https://github.com/zormandi/logcraft/blob/main/README.md

Enable parameter whitelisting for the access log to prevent sensitive data from being logged. Only specified parameters will be included.

```ruby
config.logcraft.access_log.log_only_whitelisted_params = true
```

--------------------------------

### Require RSpec Support

Source: https://github.com/zormandi/logcraft/blob/main/README.md

Include this line in your RSpec helper file to enable Logcraft's testing utilities and matchers.

```ruby
require 'logcraft/rspec'
```

--------------------------------

### Set Global Log Context in Rails

Source: https://github.com/zormandi/logcraft/blob/main/README.md

Configure a global context to be included in every log message. This context can be a static hash or a lambda/proc that returns a hash, evaluated each time a log message is emitted.

```ruby
config.logcraft.global_context = -> do
  {
    environment: ENV['RAILS_ENV'],
    timestamp_linux: Time.current.to_i # evaluated every time when emitting a log message
  }
end
```

--------------------------------

### Log an Error with Logcraft

Source: https://github.com/zormandi/logcraft/blob/main/README.md

Log an exception object directly. Logcraft formats the error, including its class, message, backtrace, and any chained causes, into the JSON output.

```ruby
logger.error error
# Formatted for better readability (the original is a single line string):
# => {
#      "timestamp": "2022-06-26T17:46:42.418+02:00",
#      "level": "ERROR",
#      "logger": "Application",
#      "hostname": "MacbookPro.local",
#      "pid": 80422,
#      "message": "wrapping error",
#      "error": {
#        "class": "StandardError",
#        "message": "wrapping error",
#        "backtrace": [...],
#        "cause": {
#          "class": "RuntimeError",
#          "message": "original error",
#          "backtrace": [...] 
#        }
#      }
#    }
```

--------------------------------

### RSpec: Expect Operation with Complex Matchers

Source: https://github.com/zormandi/logcraft/blob/main/README.md

Demonstrates using RSpec's built-in matchers within the `log` matcher for more complex assertions on log content, such as request IDs or durations.

```ruby
# RSpec's matchers can be used inside the expectation
expect { get '/' }.to log message: 'GET / - 200 (OK)',
                          request_id: match(/["\w-"]+/),
                          duration: be_within(100).of(100)
```

--------------------------------

### RSpec: Expect Log Message at Specific Level

Source: https://github.com/zormandi/logcraft/blob/main/README.md

Verify that a log message appears at a particular log level (e.g., :info) using the `at_level` method chained with `include_log_message` or `log`.

```ruby
# Expect a certain log level
log_output_is_expected.to include_log_message(message: 'Test message').at_level(:info)
expect { operation }.to log(message: 'Test message').at_level(:info)
```

--------------------------------

### RSpec: Expect Operation to Log Message

Source: https://github.com/zormandi/logcraft/blob/main/README.md

Use the `log` matcher to assert that a specific operation logs a message with certain attributes. It checks if the message is present after the operation executes.

```ruby
# Check that the message is not present in the logs before the operation but is present after it 
expect { operation }.to log message: 'Test message',
                            user_id: 123456
```

--------------------------------

### Exclude Paths from Access Log in Rails

Source: https://github.com/zormandi/logcraft/blob/main/README.md

Specify paths to exclude from the access log. This can be an array of strings or regular expressions.

```ruby
config.logcraft.access_log.exclude_paths = ['/healthcheck', %r(/monitoring/.*)]
```

--------------------------------

### Add Logcraft Gem to Rails Application

Source: https://github.com/zormandi/logcraft/blob/main/README.md

Include the Logcraft gem in your Rails application's Gemfile. The 'oj' gem is optional but recommended for improved JSON serialization performance.

```ruby
gem 'logcraft'
gem 'oj' # Optional, but recommended; see the "JSON serialization" section in the README
```

--------------------------------

### RSpec: Check for Log Message Inclusion

Source: https://github.com/zormandi/logcraft/blob/main/README.md

Use `include_log_message` to verify that a specific message exists in the log output. This can be used directly on `log_output` or as a shorthand with `log_output_is_expected`.

```ruby
# Check that the log output contains a certain message
expect(log_output).to include_log_message message: 'Test message'
log_output_is_expected.to include_log_message message: 'Test message'
```

--------------------------------

### ActiveSupport JSON Encoding Quirks

Source: https://github.com/zormandi/logcraft/blob/main/README.md

Demonstrates how ActiveSupport's default JSON encoder escapes special characters like '>' in string values.

```ruby
ActiveSupport::JSON.encode test: 'foo > bar'
#=> "{\"test\":\"foo \u003e bar\"}"

{test: 'foo > bar'}.to_json
#=> "{\"test\":\"foo \u003e bar\"}"
```

--------------------------------

### Add context to log messages within a block

Source: https://github.com/zormandi/logcraft/blob/main/README.md

Use `within_log_context` to execute a block of code where all log messages will include the provided context. The context is automatically cleaned up after the block finishes.

```ruby
within_log_context customer_id: 1234 do
  logger.info 'test 1'
end
logger.info 'test 2'

#=> {...,"level":"INFO","customer_id":1234,"message":"test 1"}
#=> {...,"level":"INFO","message":"test 2"}
```

--------------------------------

### Log Custom Error Message with Logcraft

Source: https://github.com/zormandi/logcraft/blob/main/README.md

When logging an error, you can customize the main 'message' field and use another field (e.g., 'warning') to hold the exception object for structured logging.

```ruby
# Any top-level field of the log message can be an Exception (so the error message can be customized):
logger.warn message: 'An error occured', warning: error
# => {
#      "timestamp": "2022-06-26T17:46:42.418+02:00",
#      "level": "WARN",
#      "logger": "Application",
#      "hostname": "MacbookPro.local",
#      "pid": 80422,

```
Tokens:
Raw