Integrations
LogStruct integrates with many popular gems and Rails components to provide comprehensive structured logging throughout your application. These integrations automatically hook into important events and capture relevant context for better observability.
ActionMailer Integration
The ActionMailer integration automatically logs email delivery events and handles errors during email delivery.
Example Log
{
"ts": "2025-09-05T16:23:03.159Z",
"lvl": "info",
"src": "mailer",
"evt": "delivery",
"to": [
"olga.santos@outlook.com"
],
"from": "notifications@example.com",
"subject": "Important notification",
"mailer": "SystemMailer",
"action": "notification"
}ActiveJob Integration
The ActiveJob integration logs job enqueuing, execution, and completion events with detailed information about the job.
Example Log
{
"ts": "2025-09-05T16:23:03.159Z",
"lvl": "info",
"src": "job",
"evt": "enqueue",
"job_id": "ad7b4fd3",
"job_class": "ReportGenerationJob",
"queue_name": "low",
"arguments": [
32,
{
"action": "create"
}
],
"retries": 2,
"scheduled_at": "2025-08-31T04:01:20.589Z"
}ActiveStorage Integration
The ActiveStorage integration logs uploads, downloads, deletes, and other file operations with detailed information about the file and storage service.
Example Log
{
"ts": "2025-09-05T16:23:03.160Z",
"lvl": "info",
"src": "storage",
"evt": "delete",
"op": "delete",
"storage": "local",
"file_id": "49e5fe853e",
"filename": "document.pdf",
"mime_type": "text/plain",
"size": 916844,
"metadata": {
"width": 800,
"height": 600
},
"duration": 1866.61,
"checksum": "8468a135900bff921180a6d2610cbf71",
"exist": true,
"url": "https://storage.example.com/2f948719",
"prefix": "uploads",
"range": "bytes=0-1000"
}CarrierWave Integration
The CarrierWave integration adds structured logging for file upload operations, including file metadata and operation duration.
Example Log
{
"ts": "2025-09-05T16:23:03.160Z",
"lvl": "info",
"src": "carrierwave",
"evt": "upload",
"op": "upload",
"storage": "cloud_storage",
"file_id": "5fbf2f4c6c",
"filename": "data.xlsx",
"mime_type": "image/png",
"size": 111776,
"metadata": {
"width": 800,
"height": 600
},
"duration": 1834.3,
"uploader": "AvatarUploader",
"model": "User",
"mount_point": "avatar",
"versions": [
"thumb",
"medium",
"large"
]
}Error Handling
LogStruct provides structured error logging across your application, capturing error class, message, backtrace, and contextual data for better debugging.
Example Log
{
"ts": "2025-09-05T16:23:03.161Z",
"lvl": "error",
"src": "carrierwave",
"evt": "error",
"err_class": "NoMethodError",
"msg": "invalid value for Integer()",
"backtrace": [
"app/models/subscription.rb:76:in `renew'",
"app/services/search_service.rb:112:in `execute_query'"
],
"context": "Error context 0964"
}Request Logs (via Lograge)
LogStruct configures Lograge to output request logs in a structured JSON format compatible with the rest of your logs.
Configuration
# Provide a custom proc to extend Lograge options
LogStruct.configure do |config|
config.integrations.lograge_custom_options = T.let(->(event, options) do
# Add custom fields to the options hash
options[:user_id] = event.payload[:user_id] if event.payload[:user_id]
options[:account_id] = event.payload[:account_id] if event.payload[:account_id]
options
end,
LogStruct::Handlers::LogrageCustomOptions)
endExample Log
{
"ts": "2025-09-05T16:23:03.161Z",
"lvl": "info",
"src": "rails",
"evt": "request",
"method": "DELETE",
"path": "/login/49",
"controller": "CommentsController",
"action": "update",
"status": 500,
"duration": 601.85,
"view": 13.79,
"db": 24.06,
"format": "json",
"params": {
"id": 36,
"action": "update",
"controller": "CommentsController"
},
"source_ip": "10.0.0.123",
"user_agent": "Mozilla/5.0",
"referer": "https://example.com",
"request_id": "5718038b9f34b490"
}Security Logging
LogStruct includes security-focused logging for Rails applications.
Example Log
{
"ts": "2025-09-05T16:23:03.161Z",
"lvl": "warn",
"src": "security",
"evt": "ip_spoof",
"msg": "Security violation detected",
"blocked_host": "malicious-site.com",
"blocked_hosts": [
"malicious-site.com",
"evil-domain.net"
],
"client_ip": "10.0.0.123",
"x_forwarded_for": "172.16.254.1",
"path": "/posts/60",
"method": "POST",
"source_ip": "10.0.0.123",
"user_agent": "Mozilla/5.0",
"referer": "https://example.com",
"request_id": "da3842ae9b58ebf7",
"attempted_action": "suspicious_activity"
}Shrine Integration
The Shrine integration adds structured logging for file uploads and other Shrine operations, including file metadata and operation duration.
Example Log
{
"ts": "2025-09-05T16:23:03.161Z",
"lvl": "info",
"src": "shrine",
"evt": "upload",
"storage": "s3",
"location": "uploads/5144e450d17e",
"upload_opts": {
"public": true
},
"download_opts": {},
"opts": {
"metadata": true
},
"uploader": "ImageUploader",
"duration": 2791.58,
"content_type": "text/plain",
"filename": "report.csv"
}Sidekiq Integration
The Sidekiq integration configures structured JSON logging for Sidekiq worker and client logs, maintaining consistent format with other logs.
Example Log
{
"ts": "2025-09-05T16:23:03.161Z",
"lvl": "info",
"src": "sidekiq",
"evt": "log",
"pid": 6285,
"tid": "7542ea5a",
"msg": "Job processing",
"ctx": {
"queue": "default",
"job_id": "779cacb13e77"
}
}Sorbet Integration
LogStruct integrates with Sorbet to handle type checking errors appropriately based on the environment. We raise any logging-related errors in test/development and log or report them in production to avoid crashing your application.
Configuration
config.integrations.enable_sorbet_error_handlers = true
# This configures the following error handlers for Sorbet:
# - T::Configuration.inline_type_error_handler
# - T::Configuration.call_validation_error_handler
# - T::Configuration.sig_builder_error_handler
# - T::Configuration.sig_validation_error_handler