# DecisionLog

A lightweight Elixir library for tracking decisions made during processing. Provides structured logging with compression support for PostgreSQL storage.

## Installation

```elixir
def deps do
  [
    {:decision_log, "~> 0.1.0"}
  ]
end
```

## Three APIs

DecisionLog provides three ways to log decisions:

| API | Use Case |
|-----|----------|
| **Implicit** | Simple, process-scoped logging |
| **Explicit** | Functional, pipe-friendly, testable |
| **Decorator** | Automatic section tagging for functions |

## Comparison to Logger and Telemetry

| Aspect | DecisionLog | Logger | Telemetry |
|--------|-------------|--------|-----------|
| **Purpose** | "Why was this decision made?" | "What happened?" | "How often does X happen?" |
| **Output** | Structured key-value pairs | Text messages | Event metrics |
| **Storage** | Per-request snapshot | Log files | Time-series DB |
| **Query Pattern** | Point-in-time audit trail | Sequential text search | Aggregated metrics |
| **Use Case** | Business logic branches | Debugging | Performance monitoring |

## Usage

### Implicit API (process dictionary)

```elixir
DecisionLog.start_tag(:validation)
DecisionLog.log(:input_valid, true)
DecisionLog.log(:schema_check, :passed)

DecisionLog.tag(:authorization)
DecisionLog.log(:user_role, "admin")
DecisionLog.log(:access_granted, true)

log = DecisionLog.close()
# ["validation_input_valid: true", "validation_schema_check: :passed",
#  "authorization_user_role: \"admin\"", "authorization_access_granted: true"]
```

#### Batch logging with `log_all/1`

Log multiple key-value pairs in a single call:

```elixir
DecisionLog.start_tag(:request)
DecisionLog.log_all(method: "POST", path: "/api/orders", user_id: 123)
DecisionLog.log(:status, :processed)

log = DecisionLog.close()
# ["request_method: \"POST\"", "request_path: \"/api/orders\"",
#  "request_user_id: 123", "request_status: :processed"]
```

#### Transparent logging with `trace/2`

Use `trace` when you need to log a value and continue using it in pipes or `with` statements:

```elixir
# In pipes
result =
  input
  |> transform()
  |> DecisionLog.trace(:after_transform)
  |> process()
  |> DecisionLog.trace(:final_result)

# In with statements
with true <- DecisionLog.trace(check_user(input), :user_valid),
     :ok <- DecisionLog.trace(validate_items(items), :items_check) do
  {:ok, result}
end
```

#### Custom Formatters

By default, values are formatted using `inspect/1` at close time. You can pass a custom formatter to `close/1`:

```elixir
DecisionLog.start_tag(:section)
DecisionLog.log(:date, ~D[2025-01-15])
DecisionLog.log(:count, 42)

formatter = fn
  %Date{} = d -> Date.to_string(d)
  other -> inspect(other)
end

log = DecisionLog.close(formatter: formatter)
# ["section_date: 2025-01-15", "section_count: 42"]
```

#### Per-Entry Formatters

For context-specific formatting, pass a formatter directly to `log/3`, `trace/3`, or `tagged/3`. The per-entry formatter takes precedence over the default:

```elixir
defp format_user_summary(user), do: "User<#{user.id}>"
defp format_user_detail(user), do: "User<#{user.id}, #{user.email}, #{user.role}>"

DecisionLog.start_tag(:auth)
DecisionLog.trace(user, :authenticated_user, &format_user_detail/1)

DecisionLog.tag(:audit)
DecisionLog.trace(user, :actor, &format_user_summary/1)

log = DecisionLog.close()
# ["auth_authenticated_user: User<123, alice@example.com, admin>",
#  "audit_actor: User<123>"]
```

This is useful when the same struct needs different representations in different contexts:

```elixir
# In a benefits calculator - show allowances in calculate context
benefit
|> DecisionLog.trace(:add_on_benefit, fn b ->
  "Benefit<id: #{b.id}, sms: #{b.monthly_sms_allowance}>"
end)

# Later in phone support context - just show id
benefit
|> DecisionLog.trace(:benefit, fn b -> "Benefit<id: #{b.id}>" end)
```

### Explicit API (functional, pipe-friendly)

```elixir
alias DecisionLog.Explicit, as: Log

log =
  Log.new(:request)
  |> Log.log(:method, "GET")
  |> Log.log(:path, "/api/users")
  |> Log.tag(:response)
  |> Log.log(:status, 200)
  |> Log.close()
```

With batch logging:

```elixir
log =
  Log.new(:request)
  |> Log.log_all(method: "POST", path: "/api/orders", user_id: 123)
  |> Log.tag(:response)
  |> Log.log(:status, 201)
  |> Log.close()
```

With `trace` (returns `{value, context}` for threading both):

```elixir
ctx = Log.new(:validation)

with {true, ctx} <- Log.trace(ctx, check_user(input), :user_valid),
     {:ok, ctx} <- Log.trace(ctx, validate_items(items), :items_check) do
  {{:ok, result}, ctx}
end
```

### Decorator API

The decorator automatically adds a section tag when entering a function.
The caller manages the log lifecycle (start/close).

```elixir
defmodule MyModule do
  use DecisionLog.Decorator

  @decorate decision_log()  # uses function name as tag
  def validate(input) do
    DecisionLog.log(:input, input)
    DecisionLog.log(:valid, true)
    :ok
  end

  @decorate decision_log(:authorization)  # custom tag
  def authorize(user) do
    DecisionLog.log(:user_id, user.id)
    DecisionLog.log(:role, user.role)
    :granted
  end
end

# Caller manages lifecycle
DecisionLog.start_tag(:request)
DecisionLog.log(:request_id, "abc-123")

MyModule.validate(%{name: "test"})  # adds :validate section
MyModule.authorize(user)             # adds :authorization section

log = DecisionLog.close()
```

Benefits of this design:
- Nested decorated calls all contribute to the same log
- Caller decides when logging starts and ends
- Clean separation between function logic and log lifecycle

## Logging Control Flow Decisions

### if/else

```elixir
# Implicit
if user_valid do
  DecisionLog.log(:user_check, :valid)
else
  DecisionLog.log(:user_check, :invalid)
end

# Explicit
{result, ctx} =
  if user_valid do
    {:ok, Log.log(ctx, :user_check, :valid)}
  else
    {:error, Log.log(ctx, :user_check, :invalid)}
  end
```

### case

```elixir
# Implicit
case items do
  [] ->
    DecisionLog.log(:items_check, :empty_cart)
    :error

  [_single] ->
    DecisionLog.log(:items_check, :single_item)
    :ok

  _multiple ->
    DecisionLog.log(:items_check, :multiple_items)
    :ok
end

# Explicit
{status, ctx} =
  case items do
    [] -> {:error, Log.log(ctx, :items_check, :empty_cart)}
    [_] -> {:ok, Log.log(ctx, :items_check, :single_item)}
    _ -> {:ok, Log.log(ctx, :items_check, :multiple_items)}
  end
```

### cond

```elixir
# Implicit
discount =
  cond do
    total >= 100 ->
      DecisionLog.log(:discount_tier, :gold)
      0.20

    total >= 50 ->
      DecisionLog.log(:discount_tier, :silver)
      0.10

    true ->
      DecisionLog.log(:discount_tier, :none)
      0.0
  end

# Explicit
{discount, ctx} =
  cond do
    total >= 100 -> {0.20, Log.log(ctx, :discount_tier, :gold)}
    total >= 50 -> {0.10, Log.log(ctx, :discount_tier, :silver)}
    true -> {0.0, Log.log(ctx, :discount_tier, :none)}
  end
```

### with

```elixir
# Implicit
result =
  with :ok <- validate_user(user),
       :ok <- validate_items(items),
       :ok <- validate_shipping(shipping) do
    DecisionLog.log(:fulfillment_status, :approved)
    {:ok, order}
  else
    {:error, :invalid_user} ->
      DecisionLog.log(:fulfillment_status, :rejected_user)
      {:error, :invalid_user}

    {:error, reason} ->
      DecisionLog.log(:fulfillment_status, {:rejected, reason})
      {:error, reason}
  end

# Explicit - bind ctx in else clauses
{result, ctx} =
  with :ok <- validate_user(user),
       :ok <- validate_items(items) do
    {{:ok, order}, Log.log(ctx, :status, :approved)}
  else
    error ->
      {{:error, error}, Log.log(ctx, :status, {:rejected, error})}
  end
```

### Pattern Matching in Function Heads

```elixir
# With decorator - single annotation covers all clauses
@decorate decision_log(:shipping)
def calculate_shipping(order)

def calculate_shipping(%{shipping: :express, items: items}) when length(items) > 5 do
  DecisionLog.log(:method, :express)
  DecisionLog.log(:bulk_order, true)
  DecisionLog.log(:cost, 15.0)
  15.0
end

def calculate_shipping(%{shipping: :express}) do
  DecisionLog.log(:method, :express)
  DecisionLog.log(:bulk_order, false)
  DecisionLog.log(:cost, 25.0)
  25.0
end

def calculate_shipping(%{shipping: :standard}) do
  DecisionLog.log(:method, :standard)
  DecisionLog.log(:cost, 5.0)
  5.0
end
```

## Compression for PostgreSQL Storage

Compress decision logs for efficient storage in PostgreSQL:

```elixir
# With implicit API - compress after close
DecisionLog.start_tag(:request)
DecisionLog.log(:method, "POST")
log = DecisionLog.close()
compressed = DecisionLog.Compression.compress(log)

# With explicit API - compress context directly
alias DecisionLog.Explicit, as: Log
context = Log.new(:request) |> Log.log(:method, "POST")
compressed = DecisionLog.Compression.compress_context(context)

# Decompress
{:ok, log} = DecisionLog.Compression.decompress(compressed)
```

### PostgreSQL Decompression

Decision logs can be decompressed directly in PostgreSQL using the `pg_gzip` extension:

```sql
-- Install extension
CREATE EXTENSION IF NOT EXISTS gzip;

-- Decompress log
SELECT convert_from(gzip_decompress(compressed_log), 'UTF8')
FROM decision_logs
WHERE request_id = 'abc-123';

-- Split into rows
SELECT unnest(string_to_array(
    convert_from(gzip_decompress(compressed_log), 'UTF8'),
    E'\n'
)) AS log_entry
FROM decision_logs;
```

For complete PostgreSQL setup instructions:

```elixir
IO.puts(DecisionLog.Compression.postgresql_setup())
```

### Plug Integration

Initialize decision logging at the start of a request and store it at the end:

```elixir
defmodule MyApp.Plugs.DecisionLog do
  @behaviour Plug

  import Plug.Conn

  def init(opts), do: opts

  def call(conn, _opts) do
    request_id = get_req_header(conn, "x-request-id") |> List.first() || Ecto.UUID.generate()

    # Initialize log with request metadata
    DecisionLog.start_tag(:request)
    DecisionLog.log_all(
      request_id: request_id,
      method: conn.method,
      path: conn.request_path,
      user_agent: get_req_header(conn, "user-agent") |> List.first()
    )

    # Store request_id for later and register callback to save log
    conn
    |> assign(:request_id, request_id)
    |> register_before_send(&save_decision_log/1)
  end

  defp save_decision_log(conn) do
    DecisionLog.tag(:response)
    DecisionLog.log(:status, conn.status)

    log = DecisionLog.close()
    compressed = DecisionLog.Compression.compress(log)

    # Store asynchronously to not block response
    Task.start(fn ->
      MyApp.DecisionLogs.store(conn.assigns.request_id, compressed)
    end)

    conn
  end
end
```

Add to your endpoint or router:

```elixir
plug MyApp.Plugs.DecisionLog
```

Now any code in your controllers/contexts can add to the log:

```elixir
def create(conn, params) do
  DecisionLog.tag(:validation)

  with {:ok, user} <- validate_user(params) |> DecisionLog.trace(:user_valid),
       {:ok, order} <- create_order(user, params) |> DecisionLog.trace(:order_created) do
    DecisionLog.log(:outcome, :success)
    json(conn, order)
  else
    {:error, reason} ->
      DecisionLog.log(:outcome, {:failed, reason})
      conn |> put_status(422) |> json(%{error: reason})
  end
end
```

### Ecto Integration

```elixir
# Migration
create table(:decision_logs) do
  add :request_id, :uuid, null: false
  add :compressed_log, :binary, null: false
  timestamps()
end

# Storing logs
def store_decision_log(request_id, log_context) do
  compressed = DecisionLog.Compression.compress_context(log_context)

  %DecisionLog{}
  |> DecisionLog.changeset(%{
    request_id: request_id,
    compressed_log: compressed
  })
  |> Repo.insert()
end
```

## Examples

See `examples/demo.ex` for complete examples comparing all three APIs:

```elixir
# All three produce identical logs
{result, log} = DecisionLog.Demo.Implicit.process_order(order)
{result, log} = DecisionLog.Demo.Explicit.process_order(order)
{result, log} = DecisionLog.Demo.Decorated.process_order(order)
```

The demo module demonstrates:
- `if/else` expressions
- `case` expressions
- `cond` expressions
- `with` expressions
- Pattern matching in function heads