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

The ActionMailer integration automatically logs email delivery events and handles errors during email delivery.

Example Logs

{
  "src": "mailer",
  "evt": "delivery",
  "ts": "2025-10-13T07:21:24.352Z",
  "lvl": "info",
  "to": [
    "[EMAIL:36950a]"
  ],
  "from": "[EMAIL:c1c49e]",
  "subject": "Welcome!",
  "msg_id": "f1ad7b4f",
  "mailer": "UserMailer",
  "mailer_action": "welcome_email",
  "attachments": 3
}

Apply filtering

ActiveJob

The ActiveJob integration logs job enqueuing, execution, and completion events with detailed information about the job.

Example Logs

{
  "src": "job",
  "evt": "enqueue",
  "ts": "2025-10-13T07:21:24.360Z",
  "lvl": "info",
  "job_id": "c6a7df1a",
  "job_class": "HardJob",
  "queue_name": "low",
  "arguments": [
    1
  ],
  "executions": 2,
  "provider_job_id": "b4fd3695",
  "retries": 0
}

Apply filtering

ActiveModelSerializers

Subscribes to *.active_model_serializers notifications and logs serializer, adapter, resource class, and duration (message: "ams.render").

Example Logs

{
  "src": "rails",
  "evt": "generate",
  "ts": "2025-10-13T07:21:24.366Z",
  "lvl": "info",
  "msg": "Example message",
  "serializer": "UserSerializer",
  "adapter": "attributes",
  "resource_class": "User",
  "duration_ms": 1554.1
}

Apply filtering

ActiveStorage

The ActiveStorage integration logs uploads, downloads, deletes, and other file operations with detailed information about the file and storage service.

Example Logs

{
  "src": "storage",
  "evt": "upload",
  "ts": "2025-10-13T07:21:24.369Z",
  "lvl": "info",
  "storage": "store",
  "file_id": "c6a7df1a",
  "filename": "data.json",
  "mime_type": "image/png",
  "size": 719926,
  "metadata": {
    "width": 100,
    "height": 100
  },
  "duration_ms": 604.4,
  "checksum": "fd36950a"
}

Apply filtering

Ahoy

Emits structured logs for analytics events tracked via Ahoy::Tracker#track (message: "ahoy.track").

Example Logs

{
  "src": "app",
  "evt": "log",
  "ts": "2025-10-13T07:21:24.377Z",
  "lvl": "info",
  "msg": "Example message",
  "ahoy_event": "signup",
  "properties": {
    "plan": "pro"
  }
}

Apply filtering

CarrierWave

The CarrierWave integration adds structured logging for file upload operations, including file metadata and operation duration.

Example Logs

{
  "src": "carrierwave",
  "evt": "upload",
  "ts": "2025-10-13T07:21:24.380Z",
  "lvl": "info",
  "storage": "store",
  "file_id": "c6a7df1a",
  "uploader": "AvatarUploader",
  "model": "User",
  "mount_point": "avatar",
  "version": "1.0.0",
  "store_path": "uploads/store/file.txt",
  "ext": ".jpg",
  "filename": "data.json",
  "mime_type": "image/png",
  "size": 719926,
  "metadata": {
    "width": 100,
    "height": 100
  },
  "duration_ms": 604.4
}

Apply filtering

Dotenv

Converts dotenv-rails boot messages (load/update/save/restore) into structured JSON. Early boot events are buffered and emitted once configuration is loaded.

Example Logs

{
  "src": "dotenv",
  "evt": "update",
  "ts": "2025-10-13T07:21:24.387Z",
  "lvl": "info",
  "vars": [
    "API_KEY"
  ]
}

Apply filtering

Error Handling

LogStruct provides structured error logging across your application, capturing error class, message, backtrace, and contextual data for better debugging.

Example Logs

{
  "src": "sidekiq",
  "evt": "error",
  "ts": "2025-10-13T07:21:24.390Z",
  "lvl": "error",
  "error_class": "ArgumentError",
  "msg": "Example message",
  "backtrace": [
    "app/models/user.rb:12:in find",
    "app/controllers/users_controller.rb:34:in show"
  ]
}

Apply filtering

GoodJob

The GoodJob integration logs job lifecycle events (enqueue, start, finish, error) with execution context and performance metrics.

Example Logs

{
  "src": "job",
  "evt": "enqueue",
  "ts": "2025-10-13T07:21:24.392Z",
  "lvl": "info",
  "job_id": "c6a7df1a",
  "job_class": "HardJob",
  "queue_name": "low",
  "arguments": [
    1
  ],
  "executions": 2,
  "duration_ms": 1439.57,
  "scheduled_at": "2025-10-13T07:21:24.392Z",
  "enqueue_caller": "app/controllers/users_controller.rb:15:in create"
}

Apply filtering

Puma (Server)

Converts Puma server lifecycle output into structured JSON (start and shutdown events).

Example Logs

{
  "src": "puma",
  "evt": "start",
  "ts": "2025-10-13T07:21:24.397Z",
  "lvl": "info",
  "mode": "single",
  "puma_version": "6.6.1",
  "puma_codename": "Return to Forever",
  "ruby_version": "ruby 3.4.5 (revision)",
  "min_threads": 1,
  "max_threads": 12,
  "environment": "test",
  "pid": 67753,
  "listening_addresses": [
    "tcp://127.0.0.1:3776"
  ]
}

Apply filtering

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)
end

Example Logs

{
  "src": "rails",
  "evt": "request",
  "ts": "2025-10-13T07:21:24.402Z",
  "lvl": "info",
  "path": "/login",
  "method": "DELETE",
  "source_ip": "192.168.1.1",
  "user_agent": "Mozilla/5.0",
  "referer": "https://example.com",
  "request_id": "36950ac1",
  "format": "html",
  "controller": "HomeController",
  "action": "index",
  "status": 462,
  "duration_ms": 510.52,
  "view": 116.89,
  "db": "primary",
  "params": {
    "credit_card": "[CREDIT_CARD]",
    "phone": "[PHONE]",
    "address": {
      "line1": "123 Main St",
      "city": "Metropolis"
    }
  }
}

Apply filtering

Security Logging

LogStruct includes security-focused logging for Rails applications.

Example Logs

{
  "src": "security",
  "evt": "blocked_host",
  "ts": "2025-10-13T07:21:24.405Z",
  "lvl": "warn",
  "path": "/api/78",
  "method": "POST",
  "source_ip": "10.0.0.1",
  "user_agent": "Mozilla/5.0",
  "referer": "https://example.com",
  "request_id": "7df1ad7b",
  "msg": "Example message",
  "blocked_host": "malicious.example.com",
  "blocked_hosts": [
    "malicious.example.com"
  ],
  "x_forwarded_for": "203.0.113.1, 70.41.3.18",
  "allowed_hosts": [
    "example.com",
    "trusted.com"
  ],
  "allow_ip_hosts": false
}

Apply filtering

Shrine

The Shrine integration adds structured logging for file uploads and other Shrine operations, including file metadata and operation duration.

Example Logs

{
  "src": "shrine",
  "evt": "upload",
  "ts": "2025-10-13T07:21:24.410Z",
  "lvl": "info",
  "storage": "store",
  "location": "store/file.txt",
  "upload_opts": {
    "acl": "public"
  },
  "opts": {},
  "uploader": "AvatarUploader",
  "duration_ms": 1554.1
}

Apply filtering

Sidekiq

The Sidekiq integration configures structured JSON logging for Sidekiq worker and client logs, maintaining consistent format with other logs.

Example Logs

{
  "src": "sidekiq",
  "evt": "log",
  "ts": "2025-10-13T07:21:24.414Z",
  "lvl": "info",
  "msg": "Example message",
  "ctx": {
    "ctx": "demo"
  },
  "pid": 77916,
  "tid": "thread-6a7d"
}

Apply filtering

SQL (ActiveRecord) Logging

Captures ActiveRecord SQL queries with duration, operation type, table names, and optional bind parameters, with smart filtering of noisy queries.

Example Logs

{
  "src": "app",
  "evt": "database",
  "ts": "2025-10-13T07:21:24.417Z",
  "lvl": "info",
  "msg": "Example message",
  "sql": "SELECT 1",
  "name": "Order Load",
  "duration_ms": 790.95,
  "row_count": 66,
  "adapter": "attributes",
  "bind_params": [
    1
  ],
  "db_name": "production",
  "pool_size": 10,
  "active_count": 18,
  "op_type": "SELECT",
  "table_names": [
    "users"
  ]
}

Apply filtering

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

Edit this page on GitHub