defmodule Redix.Telemetry do
@moduledoc """
Telemetry integration for event tracing, metrics, and logging.
Redix connections (both `Redix` and `Redix.PubSub`) execute the
following Telemetry events:
* `[:redix, :connection]` - executed when a Redix connection establishes the
connection to Redis. There are no measurements associated with this event.
Metadata are:
* `:connection` - the PID of the Redix connection that emitted the event.
* `:connection_name` - the name (passed to the `:name` option when the
connection is started) of the Redix connection that emitted the event.
`nil` if the connection was not registered with a name.
* `:address` - the address the connection successfully connected to.
* `:reconnection` - a boolean that specifies whether this was a first
connection to Redis or a reconnection after a disconnection. This can
be useful for more granular logging.
* `[:redix, :disconnection]` - executed when the connection is lost
with the Redis server. There are no measurements associated with
this event. Metadata are:
* `:connection` - the PID of the Redix connection that emitted the event.
* `:connection_name` - the name (passed to the `:name` option when the
* `:address` - the address the connection was connected to.
connection is started) of the Redix connection that emitted the event.
`nil` if the connection was not registered with a name.
* `:reason` - the disconnection reason as a `Redix.ConnectionError` struct.
* `[:redix, :failed_connection]` - executed when Redix can't connect to
the specified Redis server, either when starting up the connection or
after a disconnection. There are no measurements associated with this event.
Metadata are:
* `:connection` - the PID of the Redix connection that emitted the event.
* `:connection_name` - the name (passed to the `:name` option when the
connection is started) of the Redix connection that emitted the event.
`nil` if the connection was not registered with a name.
* `:address` or `:sentinel_address` - the address the connection was trying
to connect to (either a Redis server or a Redis Sentinel instance).
* `:reason` - the disconnection reason as a `Redix.ConnectionError` struct.
`Redix` connections execute the following Telemetry events when commands or
pipelines of any kind are executed.
* `[:redix, :pipeline, :start]` - executed right before a pipeline (or command,
which is a pipeline with just one command) is sent to the Redis server.
Measurements are:
* `:system_time` (integer) - the system time (in the `:native` time unit)
at the time the event is emitted. See `System.system_time/0`.
Metadata are:
* `:connection` - the PID of the Redix connection used to send the pipeline.
* `:connection_name` - the name of the Redix connection used to sent the pipeline.
This is `nil` if the connection was not registered with a name or if the
pipeline function was called with a PID directly (for example, if you did
`Process.whereis/1` manually).
* `:commands` - the commands sent to the server. This is always a list of
commands, so even if you do `Redix.command(conn, ["PING"])` then the
list of commands will be `[["PING"]]`.
* `:extra_metadata` - any term set by users via the `:telemetry_metadata` option
in `Redix.pipeline/3` and other functions.
* `[:redix, :pipeline, :stop]` - executed a response to a pipeline returns
from the Redis server, regardless of whether it's an error response or a
successful response. Measurements are:
* `:duration` - the duration (in the `:native` time unit, see `t:System.time_unit/0`)
of back-and-forth between client and server.
Metadata are:
* `:connection` - the PID of the Redix connection used to send the pipeline.
* `:connection_name` - the name of the Redix connection used to sent the pipeline.
This is `nil` if the connection was not registered with a name or if the
pipeline function was called with a PID directly (for example, if you did
`Process.whereis/1` manually).
* `:commands` - the commands sent to the server. This is always a list of
commands, so even if you do `Redix.command(conn, ["PING"])` then the
list of commands will be `[["PING"]]`.
* `:extra_metadata` - any term set by users via the `:telemetry_metadata` option
in `Redix.pipeline/3` and other functions.
If the response is an error, the following metadata will also be present:
* `:kind` - the atom `:error`.
* `:reason` - the error reason (such as a `Redix.ConnectionError` struct).
More events might be added in the future and that won't be considered a breaking
change, so if you're writing a handler for Redix events be sure to ignore events
that are not known. All future Redix events will start with the `:redix` atom,
like the ones above.
A default handler that logs these events appropriately is provided, see
`attach_default_handler/0`. Otherwise, you can write your own handler to
instrument or log events, see the [Telemetry page](telemetry.html) in the docs.
"""
require Logger
@doc """
Attaches the default Redix-provided Telemetry handler.
This function attaches a default Redix-provided handler that logs
(using Elixir's `Logger`) the following events:
* `[:redix, :disconnection]` - logged at the `:error` level
* `[:redix, :failed_connection]` - logged at the `:error` level
* `[:redix, :connection]` - logged at the `:info` level if it's a
reconnection, not logged if it's the first connection.
See the module documentation for more information. If you want to
attach your own handler, look at the [Telemetry page](telemetry.html)
in the documentation.
## Examples
:ok = Redix.Telemetry.attach_default_handler()
"""
@spec attach_default_handler() :: :ok | {:error, :already_exists}
def attach_default_handler() do
events = [
[:redix, :disconnection],
[:redix, :connection],
[:redix, :failed_connection]
]
:telemetry.attach_many(
"redix-default-telemetry-handler",
events,
&__MODULE__.handle_event/4,
:no_config
)
end
# This function handles only log-related events (disconnections, reconnections, and so on).
@doc false
@spec handle_event([atom()], map(), map(), :no_config) :: :ok
def handle_event([:redix, event], _measurements, metadata, :no_config)
when event in [:failed_connection, :disconnection, :connection] do
connection_name = metadata.connection_name || metadata.connection
case {event, metadata} do
{:failed_connection, %{sentinel_address: sentinel_address}}
when is_binary(sentinel_address) ->
_ =
Logger.error(fn ->
"Connection #{inspect(connection_name)} failed to connect to sentinel " <>
"at #{sentinel_address}: #{Exception.message(metadata.reason)}"
end)
{:failed_connection, _metadata} ->
_ =
Logger.error(fn ->
"Connection #{inspect(connection_name)} failed to connect to Redis " <>
"at #{metadata.address}: #{Exception.message(metadata.reason)}"
end)
{:disconnection, _metadata} ->
_ =
Logger.error(fn ->
"Connection #{inspect(connection_name)} disconnected from Redis " <>
"at #{metadata.address}: #{Exception.message(metadata.reason)}"
end)
{:connection, %{reconnection: true}} ->
_ =
Logger.info(fn ->
"Connection #{inspect(connection_name)} reconnected to Redis " <>
"at #{metadata.address}"
end)
{:connection, %{reconnection: false}} ->
:ok
end
end
end