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 ornil
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 ornil
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 aDBConnection.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 ornil
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
- Measurements:
[: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 ornil
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
- Measurements:
[: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 ornil
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
- Measurements:
[: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
, orXandra.Prepared.t/0
) — the query being executed:connection_name
- given name of the connection ornil
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
- Measurements:
[: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
, orXandra.Prepared.t/0
) — the query being executed:connection_name
- given name of the connection ornil
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
- Measurements:
[: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
, orXandra.Prepared.t/0
) — the query being executed:connection_name
- given name of the connection ornil
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
- Measurements:
[: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 ornil
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
- Measurements:
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, ornil
if not set:query
- the query that caused the warning, of typeXandra.Batch.t/0
,Xandra.Prepared.t/0
, orXandra.Simple.t/0
- Measurements:
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 forSTARTUP
frames:protocol_module
- only forSTARTUP
frames
- Metadata:
:frame_type
- the type of the frame, for example:STARTUP
- Measurements:
[: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
Attaches a handler that logs Telemetry events.
Link to this section Functions
@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.
Event | Level |
---|---|
[: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