Audit logging utilities for Collection operations.

This module provides functions to log collection-related activities, errors, and track user actions for audit purposes in the Voile library management system.

Features

• Action logging with context (IP, user agent, session)
• Error logging with detailed error information
• Before/after value tracking for changes
• Performance metrics (duration tracking)
• Query helpers for retrieving audit logs

Usage Examples

Basic Action Logging

# Simple action log
CollectionLogger.log_action(collection_id, user_id, "create")

# Action with custom title and message
CollectionLogger.log_action(collection_id, user_id, "publish", [
  title: "Collection Published",
  message: "Collection 'My Book Collection' was published successfully"
])

Advanced Action Logging with Context

# Full context logging (recommended for web requests)
CollectionLogger.log_action(collection_id, user_id, "update", [
  title: "Collection Updated",
  message: "Collection metadata was modified",
  old_values: %{title: "Old Title", status: "draft"},
  new_values: %{title: "New Title", status: "published"},
  ip_address: "192.168.1.100",
  user_agent: "Mozilla/5.0...",
  session_id: "abc123",
  request_id: "req-456",
  duration_ms: 150,
  metadata: %{fields_changed: ["title", "status"]}
])

Error Logging

# Log validation errors
case Collection.changeset(collection, attrs) |> Repo.update() do
  {:ok, collection} ->
    # success handling
  {:error, changeset} ->
    CollectionLogger.log_error(collection.id, user_id, "update", changeset)
end

# Log custom errors
CollectionLogger.log_error(collection_id, user_id, "delete",
  "Cannot delete collection with active items")

Integration in Phoenix Controllers

def update(conn, %{"id" => id, "collection" => collection_params}) do
  collection = Catalog.get_collection!(id)
  user_id = conn.assigns.current_user.id

  # Track old values before update
  old_values = Map.take(collection, [:title, :status, :description])
  start_time = System.monotonic_time(:millisecond)

  case Catalog.update_collection(collection, collection_params) do
    {:ok, updated_collection} ->
      duration = System.monotonic_time(:millisecond) - start_time
      new_values = Map.take(updated_collection, [:title, :status, :description])

      # Log successful update
      CollectionLogger.log_action(updated_collection.id, user_id, "update", [
        title: "Collection Updated",
        message: "Collection '#{updated_collection.title}' updated successfully",
        old_values: old_values,
        new_values: new_values,
        duration_ms: duration,
        ip_address: get_ip_address(conn),
        user_agent: get_req_header(conn, "user-agent") |> List.first(),
        session_id: get_session(conn, :session_id),
        metadata: %{changed_fields: find_changed_fields(old_values, new_values)}
      ])

      render(conn, :show, collection: updated_collection)

    {:error, changeset} ->
      # Log error
      CollectionLogger.log_error(collection.id, user_id, "update", changeset, [
        ip_address: get_ip_address(conn),
        user_agent: get_req_header(conn, "user-agent") |> List.first()
      ])

      render(conn, :edit, collection: collection, changeset: changeset)
  end
end

Query Examples

# Get recent activity for a collection
recent_logs = CollectionLogger.recent_logs(collection_id, 20)

# Get user activity from last week
last_week = DateTime.utc_now() |> DateTime.add(-7, :day)
user_logs = CollectionLogger.user_activity(user_id, last_week)

# Get all user activity
all_user_logs = CollectionLogger.user_activity(user_id)

Available Action Types

The following action types are predefined in the schema:

• "create" - Collection creation
• "update" - Collection modification
• "delete" - Collection deletion
• "publish" - Publishing collection
• "unpublish" - Unpublishing collection
• "archive" - Archiving collection
• "restore" - Restoring archived collection
• "import" - Data import operations
• "export" - Data export operations

Options for log_action/4 and log_error/5

Context Options (Recommended)

• :ip_address - Client IP address
• :user_agent - Client user agent string
• :session_id - User session identifier
• :request_id - Unique request identifier

Change Tracking Options

• :old_values - Map of values before change
• :new_values - Map of values after change

Performance Options

• :duration_ms - Operation duration in milliseconds

Custom Options

• :title - Custom log title (defaults to "Collection {action}")
• :message - Custom log message (defaults to "Collection was {action}")
• :action_type - Override action type (defaults to action)
• :metadata - Additional metadata map

Best Practices

1. Always log in service/context layers, not in controllers
2. Include context information (IP, user agent) for security auditing
3. Track before/after values for important changes
4. Use descriptive titles and messages for better audit trails
5. Log both successes and failures for complete audit coverage
6. Include performance metrics for operation monitoring
7. Use structured metadata for easier querying and analysis