Add structured production logging (#105, #107) (#141)

* Update README.md

* Add structured JSON production logging (#105)

* Log requests and background failures (#107)

* Document production logging and the VPS runbook
This commit is contained in:
2026-11-10 22:00:05 +01:00
committed by GitHub
parent f8897fa5ae
commit 202b9b1f6a
20 changed files with 1380 additions and 15 deletions
+115
View File
@@ -0,0 +1,115 @@
defmodule Chesstrainer.BackgroundTest do
use ExUnit.Case, async: false
import ExUnit.CaptureLog
alias Chesstrainer.Background
alias Chesstrainer.JSONLogFormatter
setup do
handler_id = :"background_test_capture_#{System.unique_integer([:positive])}"
:ok =
:logger.add_handler(handler_id, :logger_std_h, %{
formatter: {Chesstrainer.TestLogHandler, %{pid: self()}},
level: :all
})
on_exit(fn -> :logger.remove_handler(handler_id) end)
:ok
end
describe "run/3" do
test "returns the function's value on success" do
assert :ok = Background.run("test task", fn -> :ok end)
assert {:ok, 42} = Background.run("test task", fn -> {:ok, 42} end)
end
test "logs an error tuple with its reason" do
capture_log(fn ->
assert :error =
Background.run("test task", [table: :demo], fn -> {:error, :disk_full} end)
end)
assert_receive {:log_event, event}
assert event.level == :error
assert event.meta[:table] == :demo
assert event.meta[:reason] == :disk_full
assert message(event) == "test task failed: :disk_full"
end
test "logs a crash with the exception, reason and stacktrace" do
capture_log(fn ->
assert :error = Background.run("test task", fn -> raise "boom" end)
end)
assert_receive {:log_event, event}
assert event.level == :error
assert %RuntimeError{message: "boom"} = event.meta[:exception]
assert is_list(event.meta[:stacktrace])
assert event.meta[:stacktrace] != []
assert message(event) =~ "test task crashed: boom"
decoded = event |> JSONLogFormatter.format(%{}) |> IO.iodata_to_binary() |> Jason.decode!()
assert decoded["error"]["kind"] == "RuntimeError"
assert decoded["error"]["reason"] == "boom"
assert decoded["error"]["stacktrace"] |> is_list()
assert decoded["error"]["stacktrace"] != []
end
test "logs a throw with its reason and stacktrace" do
capture_log(fn ->
assert :error = Background.run("test task", fn -> throw(:nope) end)
end)
assert_receive {:log_event, event}
assert event.level == :error
assert event.meta[:kind] == :throw
assert event.meta[:reason] == :nope
assert message(event) == "test task crashed: :nope"
end
end
describe "Chesstrainer.Cache scheduled backups" do
test "log a failed backup" do
table = :"test_failed_backup_log_#{System.unique_integer([:positive])}"
parent = self()
backup_fun = fn _table ->
send(parent, {:backup_started, self()})
{:error, :disk_full}
end
log =
capture_log([level: :info], fn ->
pid =
start_supervised!(
Supervisor.child_spec(
{Chesstrainer.Cache, {table, [backup_fun: backup_fun]}},
id: table
)
)
send(pid, :backup)
assert_receive {:backup_started, task_pid}, 1_000
ref = Process.monitor(task_pid)
assert_receive {:DOWN, ^ref, :process, ^task_pid, :normal}, 1_000
end)
assert log =~ "cache backup failed"
assert log =~ ":disk_full"
end
end
defp message(event) do
event
|> Logger.Formatter.format_event(8_096)
|> IO.iodata_to_binary()
end
end
@@ -0,0 +1,190 @@
defmodule Chesstrainer.JSONLogFormatterTest do
use ExUnit.Case, async: true
alias Chesstrainer.JSONLogFormatter
@time 1_760_000_000_123_456
describe "format/2" do
test "emits one JSON line with timestamp, level, message and request id" do
event = %{
level: :info,
msg: {:string, "hello"},
meta: %{time: @time, request_id: "request-1"}
}
decoded = format_and_decode(event)
assert decoded["timestamp"] ==
@time |> DateTime.from_unix!(:microsecond) |> DateTime.to_iso8601()
assert decoded["level"] == "info"
assert decoded["message"] == "hello"
assert decoded["request_id"] == "request-1"
end
test "includes access-line fields" do
event = %{
level: :info,
msg: {:string, "GET /health 200 in 1.2ms"},
meta: %{
time: @time,
request_id: "request-1",
method: "GET",
path: "/health",
status: 200,
duration_ms: 1.2
}
}
decoded = format_and_decode(event)
assert decoded["method"] == "GET"
assert decoded["path"] == "/health"
assert decoded["status"] == 200
assert decoded["duration_ms"] == 1.2
assert decoded["request_id"] == "request-1"
end
test "renders an exception's reason and stacktrace" do
event = %{
level: :error,
msg: {:string, "boom"},
meta: %{
time: @time,
exception: %RuntimeError{message: "bad thing"},
stacktrace: stacktrace()
}
}
decoded = format_and_decode(event)
assert decoded["error"] == %{
"kind" => "RuntimeError",
"reason" => "bad thing",
"stacktrace" => ["lib/foo.ex:10: Foo.bar/1"]
}
end
test "renders an OTP crash report's reason and stacktrace" do
event = %{
level: :error,
msg: {:report, %{label: :gen_server_terminate}},
meta: %{
time: @time,
crash_reason: {%RuntimeError{message: "call boom"}, stacktrace()}
}
}
decoded = format_and_decode(event)
assert decoded["error"]["kind"] == "RuntimeError"
assert decoded["error"]["reason"] == "call boom"
assert decoded["error"]["stacktrace"] == ["lib/foo.ex:10: Foo.bar/1"]
end
test "redacts email addresses and credentials in metadata, params and the message" do
event = %{
level: :info,
msg: {:string, "contact user@example.com"},
meta: %{
time: @time,
email: "user@example.com",
token: "secret-token",
params: %{
"user" => %{
"email" => "user@example.com",
"name" => "Ada"
},
"user@example.com" => %{"name" => "Keyed by email"}
}
}
}
decoded = format_and_decode(event)
assert decoded["email"] == "[REDACTED]"
assert decoded["token"] == "[REDACTED]"
assert decoded["params"]["user"]["email"] == "[REDACTED]"
assert decoded["params"]["user"]["name"] == "Ada"
assert decoded["params"]["[REDACTED]"]["name"] == "Keyed by email"
assert decoded["message"] == "contact [REDACTED]"
end
test "redacts credential assignments in the message" do
event = %{
level: :info,
msg: {:string, "GET /reset token=abc123&next=/home"},
meta: %{time: @time}
}
decoded = format_and_decode(event)
assert decoded["message"] == "GET /reset token=[REDACTED]&next=/home"
end
test "sanitises non-JSON metadata instead of crashing" do
event = %{
level: :info,
msg: {:string, "weird"},
meta: %{
time: @time,
pid: self(),
reference: make_ref(),
tuple: {:ok, 1},
charlist: ~c"hello",
domain: [:bandit],
invalid: <<0, 255>>
}
}
decoded = format_and_decode(event)
assert decoded["pid"] =~ "#PID"
assert is_binary(decoded["reference"])
assert decoded["tuple"] == ["ok", 1]
assert decoded["charlist"] == "hello"
assert decoded["domain"] == ["bandit"]
assert decoded["invalid"] == "<<0, 255>>"
end
test "falls back to a JSON line when the message cannot be formatted" do
event = %{
level: :error,
msg: {:report, %{label: :broken}},
meta: %{
time: @time,
report_cb: fn _report -> raise "report blew up" end
}
}
decoded = format_and_decode(event)
assert decoded["level"] == "error"
assert is_binary(decoded["message"])
assert decoded["message"] =~ "broken"
end
end
describe "production configuration" do
test "uses the JSON formatter only in production" do
config = Config.Reader.read!("config/prod.exs", env: :prod)
assert get_in(config, [:logger, :default_handler, :formatter]) ==
{Chesstrainer.JSONLogFormatter, %{}}
end
end
defp format_and_decode(event) do
line = event |> JSONLogFormatter.format(%{}) |> IO.iodata_to_binary()
assert String.ends_with?(line, "\n")
assert length(String.split(line, "\n", trim: true)) == 1
Jason.decode!(line)
end
defp stacktrace do
[{Foo, :bar, 1, [file: ~c"lib/foo.ex", line: 10]}]
end
end
+47
View File
@@ -0,0 +1,47 @@
defmodule ChesstrainerWeb.RequestIdTest do
use ExUnit.Case, async: false
import Plug.Conn
alias ChesstrainerWeb.Plugs.PutRequestId
alias ChesstrainerWeb.UserAuth
setup do
on_exit(fn -> Logger.metadata(request_id: nil) end)
end
test "PutRequestId copies the request id into the session" do
conn =
:get
|> Phoenix.ConnTest.build_conn("/")
|> Phoenix.ConnTest.init_test_session(%{})
|> assign(:request_id, "request-1")
|> PutRequestId.call([])
assert get_session(conn, :request_id) == "request-1"
end
test "PutRequestId leaves the session alone without a request id" do
conn =
:get
|> Phoenix.ConnTest.build_conn("/")
|> Phoenix.ConnTest.init_test_session(%{})
|> PutRequestId.call([])
assert get_session(conn, :request_id) == nil
end
test "mounting a LiveView puts the session's request id into logger metadata" do
socket = %Phoenix.LiveView.Socket{}
assert {:cont, _socket} =
UserAuth.on_mount(
:mount_current_scope,
%{},
%{"request_id" => "request-2", "user_token" => nil},
socket
)
assert Logger.metadata()[:request_id] == "request-2"
end
end
@@ -0,0 +1,97 @@
defmodule ChesstrainerWeb.RequestLoggerTest do
use ChesstrainerWeb.ConnCase, async: false
import ExUnit.CaptureLog
import Plug.Conn
alias ChesstrainerWeb.RequestLogger
setup do
level = Logger.level()
Logger.configure(level: :info)
on_exit(fn -> Logger.configure(level: level) end)
:ok
end
describe "handle_event/4" do
test "logs one access line with method, path, status, duration and request id" do
conn = access_conn("GET", "/endgames", 200, "request-1")
log =
capture_log([level: :info], fn ->
RequestLogger.handle_event(
[:phoenix, :endpoint, :stop],
%{duration: 12_500_000},
%{conn: conn},
:ok
)
end)
assert log =~ "GET /endgames 200 in 12.5ms"
assert log =~ "request_id=request-1"
end
test "redacts token-like path segments" do
token = "SFMyNTY." <> String.duplicate("a", 43)
conn = access_conn("GET", "/users/reset-password/#{token}", 200, "request-1")
log =
capture_log([level: :info], fn ->
RequestLogger.handle_event(
[:phoenix, :endpoint, :stop],
%{duration: 1_000_000},
%{conn: conn},
:ok
)
end)
assert log =~ "GET /users/reset-password/[REDACTED] 200 in 1.0ms"
refute log =~ token
end
test "never logs the query string" do
conn =
:get
|> build_conn("/endgames?email=user@example.com&secret=abc")
|> assign(:request_id, "request-1")
|> put_status(200)
log =
capture_log([level: :info], fn ->
RequestLogger.handle_event(
[:phoenix, :endpoint, :stop],
%{duration: 1_000_000},
%{conn: conn},
:ok
)
end)
assert log =~ "GET /endgames 200 in 1.0ms"
refute log =~ "user@example.com"
refute log =~ "secret=abc"
end
end
describe "endpoint integration" do
test "emits exactly one access line for a request", %{conn: conn} do
log = capture_log([level: :info], fn -> get(conn, ~p"/health") end)
assert length(Regex.scan(~r/GET \/health 200 in [\d.]+ms/, log)) == 1
assert log =~ "request_id="
end
test "emits an access line for a LiveView initial request", %{conn: conn} do
log = capture_log([level: :info], fn -> get(conn, ~p"/users/log-in") end)
assert length(Regex.scan(~r/GET \/users\/log-in 200 in [\d.]+ms/, log)) == 1
assert log =~ "request_id="
end
end
defp access_conn(method, path, status, request_id) do
method
|> build_conn(path)
|> assign(:request_id, request_id)
|> put_status(status)
end
end
+9
View File
@@ -0,0 +1,9 @@
defmodule Chesstrainer.TestLogHandler do
@moduledoc false
@doc false
def format(event, %{pid: pid}) do
send(pid, {:log_event, event})
""
end
end