feat(#27,#36): observability floor — PGRST001/PGRST002 error logging + DB-pool telemetry

[milmazz]

What

The minimal observability floor for a first release: structured JSON error logging for PostgREST's PGRST001/PGRST002-class conditions, plus the [:bier, :pool, …] :telemetry event family. Logging/telemetry is additive and out-of-band — no response body, status, or header changes.

Structured error logging (#27)

• New Bier.ErrorLogger emits PostgREST's error envelope {code, message, details, hint} as a single JSON line via Logger.error/2 (the issue's "via Logger" option), with :bier_instance / :bier_error_code metadata. The message is built lazily, so nothing is encoded when the :error level is disabled. The moduledoc documents how a host gets PostgREST's exact stderr behavior (config :logger, :default_handler, config: [type: :standard_error]).
• PGRST002 ("Could not query the database for the schema cache. Retrying.") is wired inside Bier.SchemaCache.load!/3 — the one funnel both the boot introspection (Bier.HttpServerStarter) and every reload (listener or programmatic) go through — so each failing load logs exactly once before re-raising.
• PGRST001 ("Database client error. Retrying the connection.") fires where pool errors surface in the request path: a DBConnection.ConnectionError reaching Bier.Plugs.FallbackController (new clause rendering the exact opaque 500 the catch-all already produced), or a Postgrex.Error carrying no SQLSTATE (client error; response unchanged).

DB-pool telemetry (#36)

• New Bier.PoolMonitor (child of each instance's supervisor) samples the Postgrex pool via DBConnection.get_connection_metrics/1 and emits the [:bier, :pool, :status] gauges — :max / :available / :waiting, mirroring pgrst_db_pool_max|available|waiting. One sample at startup, then every 5s; an unreachable pool skips the sample instead of crash-looping alongside it.
• [:bier, :pool, :checkout_timeout] (mirrors pgrst_db_pool_timeouts_total) fires from the fallback controller when a request's checkout was dropped from the pool queue (reason: :queue_timeout).
• Both events carry :instance metadata, consistent with [observability] Emit :telemetry events (request / pool / schema-cache) #26, and are fully documented in the Bier.Telemetry moduledoc.
• db_connection ~> 2.7 is now an explicit dep (already in the lock at 2.10.1): get_connection_metrics/1 is called directly and was added in 2.7.

The [:bier, :jwt_cache, …] family from #36 is not included: as the issue notes, it first requires introducing a JWT verification cache (Bier verifies every JWT directly today) — that remains open.

Verification

• mix format --check-formatted, mix compile --warnings-as-errors (dev + test env), mix credo --strict, mix docs --warnings-as-errors, mix deps.unlock --check-unused, mix hex.audit — all green locally.
• New unit tests under test/bier/ (CI runs them): error_logger_test.exs (capture_log envelope shape + the load! PGRST002 funnel via an unreachable pool), plugs/fallback_controller_test.exs (PGRST001 logging, unchanged 500 wire format, checkout-timeout counter), pool_monitor_test.exs (:status gauges on boot; unreachable-pool sample skip).
• DB-free smoke run exercising every new path end-to-end (envelopes, counter, unchanged response, monitor survival) — output verified.
• Conformance suite untouched (test/**/spec/** unchanged); CI is the judge.

Closes #27. Part of #36 (pool events delivered; jwt_cache events remain, blocked on a JWT verification cache).

🤖 Generated with Claude Code