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:

  • :cluster - the cluster name (the atom passed as :name to Redix.Cluster.start_link/1). Only cluster connections include this field. Available since v1.9.0.
  • :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 original host and port used to connect, or the Unix socket path.
  • :peer_address - the connected socket's IP address and port as a string, or its Unix socket path. nil if the peer address is unavailable. Available since v1.9.0.
  • :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:

  • :cluster - the cluster name (the atom passed as :name to Redix.Cluster.start_link/1). Only cluster connections include this field. Available since v1.9.0.
  • :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 original host and port used to connect, or the Unix socket path.
  • :peer_address - the peer address saved when the connection opened, in the same format as the connection event. nil if the peer address was unavailable. Available since v1.9.0.
  • :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:

  • :cluster - the cluster name (the atom passed as :name to Redix.Cluster.start_link/1). Only cluster connections include this field. Available since v1.9.0.
  • :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 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).

Cluster events

Redix.Cluster connections execute the following Telemetry events:

• [:redix, :cluster, :pipeline, :start] - executed when a Redix.Cluster.command/3, pipeline/3, or transaction_pipeline/3 call starts. Measurements are :system_time. Metadata are:

  • :cluster - the name of the cluster (the atom passed as :name).
  • :call - :pipeline (for command/3 and pipeline/3) or :transaction_pipeline.
  • :route - the resolved :route option (:primary, :replica, or :prefer_replica).
  • :commands - the commands passed to the call.
  • :extra_metadata - the :telemetry_metadata option passed to the call, or %{}.

  Available since 1.7.0.

• [:redix, :cluster, :pipeline, :stop] - executed when the call returns. It covers every node request and every MOVED/ASK hop the call performed. Measurements are:

  • :duration - the total time of the call (in native units).
  • :command_count - the number of commands in the call.
  • :node_count - the number of nodes the commands were split across.
  • :redirections - the number of MOVED/ASK redirections followed.

  Metadata are the same as for :start, plus :result (the return value of the call).

  Available since 1.7.0.

• [:redix, :cluster, :pipeline, :exception] - executed when the call raises or exits. Measurements are :duration. Metadata are the same as for :start, plus :kind, :reason, and :stacktrace.

  Available since 1.7.0.

• [:redix, :cluster, :discovery_wait] - executed when a call had to wait for the initial topology discovery (only possible before the first topology fetch completes with sync_connect: false). Measurements are :duration. Metadata are :cluster and :result.

  Available since 1.7.0.

• [:redix, :cluster, :topology_change] - executed every time the cluster topology is successfully fetched, whether or not it changed. Generally this is fired once per :topology_refresh_interval. It's also fired on refreshes caused by redirections. Handlers can use the :changed metadata field to count changes specifically (compared to uneventful refreshes). Measurements are :duration (the time spent fetching and applying the topology) and :node_count.

  Metadata are:

  • :cluster - the name of the cluster (the atom passed as :name).
  • :changed - true on the first successful fetch, or when the set of nodes, their roles, or the slot map differs from the last successful fetch. DNS address changes and pool member restarts do not count as topology changes. Replicas only count when :read_from_replicas is enabled. This field is present since v1.9.1.
  • :nodes - the list of node addresses (as "host:port" strings) for every node the cluster connects to.
  • :node_info - a list of maps with :id, :host, :port, and :role (:primary or :replica) for every node the cluster connects to.

  Node IDs keep the host returned by CLUSTER SLOTS, after :address_mapper runs.

• [:redix, :cluster, :failed_topology_refresh] - executed when the cluster manager fails to refresh the topology (no reachable node). Measurements are :duration. Metadata are:

  • :cluster - the name of the cluster.
  • :reason - the error reason. This is {:no_reachable_node, node_errors}, where node_errors is a list of {host, port, reason} triples, one per node that was tried, in the order tried, so you can tell (for example) a wrong password from a network partition instead of a single opaque reason.

• [:redix, :cluster, :node_connection_failed] - executed when the cluster manager fails to establish a connection to a specific node. There are no measurements. Metadata are:

  • :cluster - the name of the cluster.
  • :address - the node address (as a "host:port" string).
  • :reason - the error reason.
  • :kind - :start_failed if the connection could not be started, or :parked if the connection stopped with a semantic error (such as NOAUTH or WRONGPASS) and is left for the next topology refresh instead of being restarted.

• [:redix, :cluster, :node_connection_restarted] - executed when a node connection went down for a non-semantic reason (a crash or a kill) and the cluster manager restarts it right away. There are no measurements. Metadata are:

  • :cluster - the name of the cluster.
  • :address - the node address (as a "host:port" string).
  • :role - :primary or :replica.
  • :reason - the exit reason of the old connection.

  Available since 1.7.0.

• [:redix, :cluster, :node_role_changed] - executed when a topology refresh finds that a node changed role (typically after a failover) and its connections are restarted with the new role. There are no measurements. Metadata are:

  • :cluster - the name of the cluster.
  • :address - the node address (as a "host:port" string).
  • :from - the previous role (:primary or :replica).
  • :to - the new role.

  Available since 1.7.0.

• [:redix, :cluster, :redirection] - executed when a command receives a MOVED or ASK redirection from a cluster node. There are no measurements. Metadata are:

  • :cluster - the name of the cluster.
  • :type - either :moved or :ask.
  • :slot - the hash slot being redirected.
  • :target_address - the target node address (as a "host:port" string).

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 in the docs.