Xandra
v0.17.0

View Source Xandra.Telemetry (Xandra v0.17.0)

Telemetry integration for event tracing, metrics, and logging.

Xandra uses telemetry for reporting metrics and events. Below we list all the possible events emitted by Xandra, alongside their measurements and metadata.

Xandra emits telemetry events since v0.15.0.

events

 Events

Here is a comprehensive list of the Telemetry events that Xandra emits.

connection-events

 Connection Events

  • [:xandra, :connected] — executed when a connection connects to its Cassandra node.

    • Measurements: none.
    • Metadata:
      • :connection_name - given name of the connection or nil if not set
      • :address - the address of the node the connection is connected to
      • :port - the port of the node the connection is connected to
      • :protocol_module - the protocol module used by the connection
      • :supported_options - Cassandra supported options as a map (mostly useful for internal debugging)

  • [:xandra, :disconnected] — executed when a connection disconnects from its Cassandra node.

    • Measurements: none.
    • Metadata:
      • :connection_name - given name of the connection or nil if not set
      • :address - the address of the node the connection is connected to
      • :port - the port of the node the connection is connected to
      • :reason - the reason for the disconnection (usually a DBConnection.ConnectionError)

query-events

 Query Events

The [:xandra, :prepare_query, ...] and [:xandra, :execute_query, ...] events are Telemetry spans. See telemetry:span/3. All the time measurements are in native time unit, so you need to use System.convert_time_unit/3 to convert to the desired time unit.

  • [:xandra, :prepare_query, :start] — executed before a query is prepared.

    • Measurements:
      • :system_time (in :native time units)
      • :monotonic_time (in :native time units)
    • Metadata:
      • :query (Xandra.Prepared.t/0) - the query being prepared
      • :connection_name - given name of the connection or nil if not set
      • :address - the address of the node the connection is connected to
      • :port - the port of the node the connection is connected to
      • :extra_metadata - extra metadata provided by :telemetry_metadata option

  • [:xandra, :prepare_query, :stop] — executed after a query was prepared.

    • Measurements:
      • :duration (in :native time units)
      • :monotonic_time (in :native time units)
    • Metadata:
      • :query (Xandra.Prepared.t/0) - the query being prepared
      • :connection_name - given name of the connection or nil if not set
      • :address - the address of the node the connection is connected to
      • :port - the port of the node the connection is connected to
      • :reason - if error, reason
      • :extra_metadata - extra metadata provided by :telemetry_metadata option

  • [:xandra, :prepare_query, :exception] — executed if there was an exception when preparing a query.

    • Measurements:
      • :duration (in :native time units)
      • :monotonic_time (in :native time units)
    • Metadata:
      • :query (Xandra.Prepared.t/0) - the query being prepared
      • :connection_name - given name of the connection or nil if not set
      • :address - the address of the node the connection is connected to
      • :port - the port of the node the connection is connected to
      • :reason - if error, reason
      • :kind - kind on :exception
      • :stacktrace - stacktrace on :exception
      • :extra_metadata - extra metadata provided by :telemetry_metadata option

  • [:xandra, :execute_query, :start] — executed before a query is executed.

    • Measurements:
      • :system_time (in :native time units)
      • :monotonic_time (in :native time units)
    • Metadata:
      • :query (Xandra.Simple.t/0, Xandra.Batch.t/0, or Xandra.Prepared.t/0) — the query being executed
      • :connection_name - given name of the connection or nil if not set
      • :address - the address of the node the connection is connected to
      • :port - the port of the node the connection is connected to
      • :extra_metadata - extra metadata provided by :telemetry_metadata option

  • [:xandra, :execute_query, :stop] — executed after a query was executed.

    • Measurements:
      • :duration (in :native time units)
      • :monotonic_time (in :native time units)
    • Metadata:
      • :query (Xandra.Simple.t/0, Xandra.Batch.t/0, or Xandra.Prepared.t/0) — the query being executed
      • :connection_name - given name of the connection or nil if not set
      • :address - the address of the node the connection is connected to
      • :port - the port of the node the connection is connected to
      • :reason - if error, reason
      • :extra_metadata - extra metadata provided by :telemetry_metadata option

  • [:xandra, :execute_query, :exception] — executed if there was an exception when executing a query.

    • Measurements:
      • :duration (in :native time units)
      • :monotonic_time (in :native time units)
    • Metadata:
      • :query (Xandra.Simple.t/0, Xandra.Batch.t/0, or Xandra.Prepared.t/0) — the query being executed
      • :connection_name - given name of the connection or nil if not set
      • :address - the address of the node the connection is connected to
      • :port - the port of the node the connection is connected to
      • :reason - if error, reason
      • :kind - kind on :exception
      • :stacktrace - stacktrace on :exception
      • :extra_metadata - extra metadata provided by :telemetry_metadata option

  • [:xandra, :prepared_cache, :hit] and [:xandra, :prepared_cache, :miss] — executed when a query is executed and the prepared cache is checked.

    • Measurements:
      • :query (Xandra.Prepared.t/0) - the query being looked up in the cache
      • :connection_name - given name of the connection or nil if not set
      • :address - the address of the node the connection is connected to
      • :port - the port of the node the connection is connected to
      • :extra_metadata - extra metadata provided by :telemetry_metadata option

warnings

 Warnings

  • [:xandra, :server_warnings]
    • Measurements:
      • :warnings - A list of warnings where each warning is a string. It contains at least one element.
    • Metadata:
      • :address - the address of the node the connection is connected to
      • :port - the port of the node the connection is connected to
      • :current_keyspace - the current keyspace of the connection, or nil if not set
      • :query - the query that caused the warning, of type Xandra.Batch.t/0, Xandra.Prepared.t/0, or Xandra.Simple.t/0

cluster-events

 Cluster Events

See the "Telemetry" section in the documentation for Xandra.Cluster.

debugging-events

 Debugging Events

These events are mostly meant for debugging Xandra itself and its internals. You can use these events to monitor exchanges of Cassandra Native Protocol frames between Xandra and the Cassandra server, for example.

  • [:xandra, :debug, :received_frame] (since v0.17.0)

    • Measurements: none
    • Metadata:
      • :frame_type - the type of the frame, for example :READY or :AUTHENTICATE

  • [:xandra, :debug, :sent_frame] (since v0.17.0)

    • Measurements:
      • :requested_options - only for STARTUP frames
      • :protocol_module - only for STARTUP frames
    • Metadata:
      • :frame_type - the type of the frame, for example :STARTUP

  • [:xandra, :debug, :downgrading_protocol] (since v0.17.0)

    • Measurements: none
    • Metadata:
      • :failed_version - the protocol version that failed
      • :new_version - the protocol that we're downgrading to
      • :address - the address of the node the connection is connecting to
      • :port - the port of the node the connection is connecting to

Link to this section Summary

Functions

attach_default_handler()

Attaches a handler that logs Telemetry events.

Link to this section Functions

Link to this function

attach_default_handler()

View Source (since 0.15.0) 
@spec attach_default_handler() :: :ok

Attaches a handler that logs Telemetry events.

This handler is useful when you want to see what's going on in Xandra without having to write a Telemetry handler to handle all the events.

These are the events that get logged. This list might change in the future.

EventLevel
[:xandra, :connected]info
[:xandra, :disconnected]warn
[:xandra, :prepared_cache, :hit]debug
[:xandra, :prepared_cache, :miss]debug
[:xandra, :prepare_query, :start]debug
[:xandra, :prepare_query, :stop]debug
[:xandra, :prepare_query, :exception]error
[:xandra, :execute_query, :start]debug
[:xandra, :execute_query, :stop]debug
[:xandra, :execute_query, :exception]error
[:xandra, :server_warnings]warn
[:xandra, :cluster, :change_event]debug
[:xandra, :cluster, :control_connection, :connected]debug
[:xandra, :cluster, :control_connection, :disconnected]debug
[:xandra, :cluster, :control_connection, :failed_to_connect]warn
[:xandra, :cluster, :pool, :started]debug
[:xandra, :cluster, :pool, :restarted]debug
[:xandra, :cluster, :discovered_peers]debug

Events have the following logger metadata:

  • :xandra_address - the address of the node the connection is connected to
  • :xandra_port - the port of the node the connection is connected to
  • :xandra_protocol_module - the protocol module for the Cassandra native protocol