telemetry-essentials

Telemetry Essentials

RULES — Follow these with no exceptions

1. Use structured logging (Logger.info("action", key: value)) — never string interpolation in log messages; structured logs are searchable and parseable
2. Attach telemetry handlers in Application.start/2 — :telemetry.attach/4 with an existing handler ID returns {:error, :already_exists}, so it never double-attaches; attach at boot anyway, since handlers detach permanently if they raise and boot-time attachment gives them a stable lifecycle
3. Use Ecto.Repo telemetry events for query monitoring — don't wrap every query manually; Ecto already emits events
4. Use Phoenix.LiveDashboard in dev/staging — it's free observability with zero code
5. Tag telemetry events with metadata (user_id, request_id) — without correlation IDs, distributed traces are useless
6. Never log at :debug level in production — it includes query parameters and PII

---

Structured Logging

Structured logs can be filtered, searched, and aggregated. String-interpolated logs cannot.

Bad:

# String interpolation — unsearchable, inconsistent format
Logger.info("User #{user.id} created order #{order.id} for $#{order.total}")
Logger.error("Failed to process payment for user #{user.id}: #{inspect(reason)}")

Good:

# Structured logging — searchable, parseable by log aggregators
Logger.info("Order created", user_id: user.id, order_id: order.id, total: order.total)
Logger.error("Payment failed", user_id: user.id, reason: inspect(reason))

Keyword data goes to Logger metadata and is dropped unless whitelisted — add the keys to config :logger, :default_formatter, metadata: [...] (or metadata: :all in dev). Passing user_id: user.id doesn't help if :user_id isn't in that list — it's silently discarded.

Logger Metadata

Set metadata once per request — it's automatically included in all subsequent log calls.

# In a Plug (added to your endpoint or router pipeline)
defmodule MyAppWeb.Plugs.RequestMetadata do
  import Plug.Conn

  def init(opts), do: opts

  def call(conn, _opts) do
    Logger.metadata(
      request_id: conn.assigns[:request_id] || Ecto.UUID.generate(),
      remote_ip: to_string(:inet.ntoa(conn.remote_ip))
    )
    conn
  end
end

# In a LiveView mount
@impl true
def mount(_params, _session, socket) do
  if connected?(socket) do
    Logger.metadata(user_id: socket.assigns.current_user.id)
  end
  {:ok, socket}
end