Phoenix.SocketClient.Telemetry (phoenix_socket_client v0.8.0)

View Source

Comprehensive Telemetry integration for Phoenix.SocketClient.

This module provides telemetry events with duration tracking for monitoring socket connections, channel joins/leaves, message handling, and connection lifecycle events.

Event Naming Convention

All events follow the pattern: [:phoenix, :socket_client, component, action]

Connection Events

  • [:phoenix, :socket_client, :connection, :start] - Connection attempt started
  • [:phoenix, :socket_client, :connection, :stop] - Connection attempt completed
  • [:phoenix, :socket_client, :connection, :error] - Connection attempt failed
  • [:phoenix, :socket_client, :connection, :established, :start] - Connection established
  • [:phoenix, :socket_client, :connection, :established, :stop] - Connection ended
  • [:phoenix, :socket_client, :reconnection, :attempt] - Reconnection attempt

Channel Events

  • [:phoenix, :socket_client, :channel, :join, :start] - Channel join started
  • [:phoenix, :socket_client, :channel, :join, :stop] - Channel join completed
  • [:phoenix, :socket_client, :channel, :join, :error] - Channel join failed
  • [:phoenix, :socket_client, :channel, :active, :start] - Channel became active
  • [:phoenix, :socket_client, :channel, :active, :stop] - Channel became inactive
  • [:phoenix, :socket_client, :channel, :leave] - Channel left
  • [:phoenix, :socket_client, :channel, :push] - Message pushed to channel
  • [:phoenix, :socket_client, :channel, :reply] - Reply received

Message Events

  • [:phoenix, :socket_client, :message, :sent] - Message sent
  • [:phoenix, :socket_client, :message, :received] - Message received
  • [:phoenix, :socket_client, :message, :encode, :start] - Message encoding started
  • [:phoenix, :socket_client, :message, :encode, :stop] - Message encoding completed
  • [:phoenix, :socket_client, :message, :decode, :start] - Message decoding started
  • [:phoenix, :socket_client, :message, :decode, :stop] - Message decoding completed

System Events

  • [:phoenix, :socket_client, :heartbeat, :sent] - Heartbeat sent
  • [:phoenix, :socket_client, :heartbeat, :timeout] - Heartbeat timeout
  • [:phoenix, :socket_client, :error] - General error

Duration Tracking

Duration events use the span pattern with start/stop pairs:

:telemetry.span([:phoenix, :socket_client, :connection], %{socket_ref: ref, url: url}, fn ->
  # Connection logic here
  {:ok, %{status: :connected}}
end)

This generates:

  • Start event: [:phoenix, :socket_client, :connection, :start]
  • Stop event: [:phoenix, :socket_client, :connection, :stop]

Configuration

Configure telemetry behavior in your config:

config :phoenix_socket_client, :telemetry,
  enabled: true,
  default_handler: true,
  track_durations: true,
  log_levels: %{
    connection: :info,
    connection_established: :debug,
    channel: :info,
    channel_active: :debug,
    message: :debug,
    error: :error,
    heartbeat: :debug
  }

Default Handler

Attach the default handler for Logger integration:

Phoenix.SocketClient.Telemetry.attach_default_handler()

Custom Metrics Integration

Example with telemetry_metrics:

defmodule MyApp.Telemetry do
  import Telemetry.Metrics

  def metrics do
    [
      distribution("phoenix.socket_client.connection.duration",
        unit: {:native, :millisecond},
        tags: [:transport, :url]
      ),
      distribution("phoenix.socket_client.channel.join.duration",
        unit: {:native, :millisecond},
        tags: [:topic, :status]
      ),
      counter("phoenix.socket_client.connection.count",
        tags: [:transport]
      )
    ]
  end
end

Summary

Types

duration_context()
duration_token()
event_name()
measurements()
metadata()
span_result()

Functions

attach_debug_handler()

Attaches a debug handler that prints all telemetry events.

attach_default_handler(opts \\ [])

Attaches the default telemetry handler that converts events to Logger calls.

channel_active(metadata)

Emits channel active event.

channel_active_start(metadata)

Emits channel active start event.

channel_active_stop(metadata)

Emits channel active stop event.

channel_join_duration(channel_pid, topic, duration)

Emits channel join duration event.

channel_join_error(metadata)

Emits channel join error event.

channel_join_error(pid, topic, error, metadata \\ %{})

Legacy: Emits channel join error event.

channel_join_start(metadata)

Emits channel join start event.

channel_join_stop(metadata)

Emits channel join stop event.

channel_joined(pid, topic, channel_pid, response, metadata \\ %{})

Legacy: Emits channel join event.

channel_leave(metadata)

Emits channel leave event.

channel_leave_duration(channel_pid, topic, duration)

Emits channel leave duration event.

channel_left(metadata)

Emits channel left event.

channel_left(pid, topic, reason, metadata \\ %{})

Legacy: Emits channel leave event.

channel_push(metadata)

Emits channel push event.

channel_reply(metadata)

Emits channel reply event.

channel_status_changed(channel_pid, topic, old_status, new_status)

Emits channel status changed event.

complete_duration_context(context, additional_metadata)

Completes a duration context and emits summary events.

config()

Gets the current telemetry configuration.

connection_error(metadata)

Emits connection error event.

connection_established_start(metadata)

Emits connection established start event.

connection_established_stop(metadata)

Emits connection established stop event.

connection_start(metadata)

Emits connection start event.

connection_stop(metadata)

Emits connection stop event.

create_duration_context(component, metadata \\ %{})

Creates a duration measurement context for complex operations.

debug(metadata)

Emits debug-level event.

detach_debug_handler()

Detaches the debug handler.

detach_default_handler()

Detaches the default telemetry handler.

emit_event(event_name, measurements \\ %{}, metadata \\ %{})

Emits a telemetry event if telemetry is enabled and passes sampling/filters.

enabled?()

Checks if telemetry is enabled.

error(metadata)

Emits general error event.

execute(event_name, measurements, metadata)

Legacy execute function for backward compatibility.

get_config(key)

Gets a specific configuration value.

heartbeat_sent(metadata)

Emits heartbeat sent event.

heartbeat_sent(pid, url, metadata \\ %{})

Legacy: Emits heartbeat event.

heartbeat_timeout(metadata)

Emits heartbeat timeout event.

measure_duration(component, operation, metadata \\ %{}, function)

Measures execution time of a function and emits start/stop events.

measure_sub_operation(context, operation, function)

Measures a sub-operation within a duration context.

message_decode_start(metadata)

Emits message decode start event.

message_decode_stop(metadata)

Emits message decode stop event.

message_decoded(metadata)

Emits message decoded event.

message_encode_start(metadata)

Emits message encode start event.

message_encode_stop(metadata)

Emits message encode stop event.

message_encoded(metadata)

Emits message encoded event.

message_receive(metadata)

Emits message receive event.

message_received(metadata)

Emits message received event.

message_received(pid, topic, event, payload, metadata \\ %{})

Legacy: Emits message received event.

message_send(metadata)

Emits message send event.

message_sent(metadata)

Emits message sent event.

message_sent(pid, topic, event, payload, metadata \\ %{})

Legacy: Emits message sent event.

optimization(optimization_type, metadata)

Emits optimization-related event.

optimization_binary_pool_hit(metadata)

Emits binary pool hit optimization event.

optimization_cache_hit(metadata)

Emits cache hit optimization event.

optimization_cache_miss(metadata)

Emits cache miss optimization event.

optimization_process_hibernated(metadata)

Emits process hibernated optimization event.

passes_filters?(event_name, measurements \\ %{})

Checks if an event passes the configured filters.

reconnecting(pid, url, attempt, metadata \\ %{})

Legacy: Emits reconnection attempt event.

reconnection_attempt(metadata)

Emits reconnection attempt event.

reset_config()

Resets telemetry configuration to defaults.

sampler_rate()

Gets the current sampler rate.

should_sample?()

Checks if an event should be sampled based on the sampler rate.

socket_connected(pid, url, metadata \\ %{})

Legacy: Emits socket connection event.

socket_connecting(pid, url, metadata \\ %{})

Legacy: Emits socket connection attempt event.

socket_connection_duration(pid, url, duration)

Legacy: Emits socket connection duration event.

socket_connection_error(pid, url, error, metadata \\ %{})

Legacy: Emits socket connection error event.

socket_disconnected(pid, url, reason, metadata \\ %{})

Legacy: Emits socket disconnection event.

span(event_name, metadata, fun)

Executes a function with telemetry span for duration tracking.

start_duration(component, operation, metadata \\ %{})

Starts tracking duration for a specific operation.

stop_duration(token, additional_metadata \\ %{})

Stops duration tracking for a specific operation.

track_durations?()

Checks if duration tracking is enabled.

track_memory_usage?()

Checks if memory usage tracking is enabled.

track_message_sizes?()

Checks if message size tracking is enabled.

update_config(new_config)

Updates telemetry configuration.

Types

duration_context()

@type duration_context() ::
  %{
    component: atom(),
    start_time: integer(),
    operations: %{required(atom()) => integer()},
    metadata: metadata()
  }
  | :disabled

duration_token()

@type duration_token() ::
  %{
    component: atom(),
    operation: atom(),
    start_time: integer(),
    start_system_time: integer(),
    metadata: metadata()
  }
  | :disabled

event_name()

@type event_name() :: [atom()]

measurements()

@type measurements() :: map()

metadata()

@type metadata() :: map()

span_result()

@type span_result() :: {:ok, metadata()} | {:error, metadata()}

Functions

attach_debug_handler()

@spec attach_debug_handler() :: :ok

Attaches a debug handler that prints all telemetry events.

Useful for development and debugging.

attach_default_handler(opts \\ [])

@spec attach_default_handler(keyword()) :: :ok

Attaches the default telemetry handler that converts events to Logger calls.

The handler respects the configured log levels and formats duration measurements in human-readable format.

Example

Phoenix.SocketClient.Telemetry.attach_default_handler()

You can also provide custom configuration:

Phoenix.SocketClient.Telemetry.attach_default_handler(
  log_levels: %{connection: :debug, error: :warn}
)

channel_active(metadata)

@spec channel_active(metadata()) :: :ok

Emits channel active event.

channel_active_start(metadata)

@spec channel_active_start(metadata()) :: :ok

Emits channel active start event.

channel_active_stop(metadata)

@spec channel_active_stop(metadata()) :: :ok

Emits channel active stop event.

channel_join_duration(channel_pid, topic, duration)

@spec channel_join_duration(pid(), String.t(), non_neg_integer()) :: :ok

Emits channel join duration event.

channel_join_error(metadata)

@spec channel_join_error(metadata()) :: :ok

Emits channel join error event.

channel_join_error(pid, topic, error, metadata \\ %{})

@spec channel_join_error(pid(), String.t(), any(), metadata()) :: :ok

Legacy: Emits channel join error event.

channel_join_start(metadata)

@spec channel_join_start(metadata()) :: :ok

Emits channel join start event.

channel_join_stop(metadata)

@spec channel_join_stop(metadata()) :: :ok

Emits channel join stop event.

channel_joined(pid, topic, channel_pid, response, metadata \\ %{})

@spec channel_joined(pid(), String.t(), pid(), map(), metadata()) :: :ok

Legacy: Emits channel join event.

channel_leave(metadata)

@spec channel_leave(metadata()) :: :ok

Emits channel leave event.

channel_leave_duration(channel_pid, topic, duration)

@spec channel_leave_duration(pid(), String.t(), non_neg_integer()) :: :ok

Emits channel leave duration event.

channel_left(metadata)

@spec channel_left(metadata()) :: :ok

Emits channel left event.

channel_left(pid, topic, reason, metadata \\ %{})

@spec channel_left(pid(), String.t(), atom(), metadata()) :: :ok

Legacy: Emits channel leave event.

channel_push(metadata)

@spec channel_push(metadata()) :: :ok

Emits channel push event.

channel_reply(metadata)

@spec channel_reply(metadata()) :: :ok

Emits channel reply event.

channel_status_changed(channel_pid, topic, old_status, new_status)

@spec channel_status_changed(pid(), String.t(), atom(), atom()) :: :ok

Emits channel status changed event.

complete_duration_context(context, additional_metadata)

@spec complete_duration_context(duration_context(), metadata()) :: :ok

Completes a duration context and emits summary events.

config()

@spec config() :: map()

Gets the current telemetry configuration.

connection_error(metadata)

@spec connection_error(metadata()) :: :ok

Emits connection error event.

connection_established_start(metadata)

@spec connection_established_start(metadata()) :: :ok

Emits connection established start event.

connection_established_stop(metadata)

@spec connection_established_stop(metadata()) :: :ok

Emits connection established stop event.

connection_start(metadata)

@spec connection_start(metadata()) :: :ok

Emits connection start event.

connection_stop(metadata)

@spec connection_stop(metadata()) :: :ok

Emits connection stop event.

create_duration_context(component, metadata \\ %{})

@spec create_duration_context(atom(), metadata()) :: duration_context()

Creates a duration measurement context for complex operations.

Returns a context that can be used to measure multiple sub-operations.

debug(metadata)

@spec debug(metadata()) :: :ok

Emits debug-level event.

detach_debug_handler()

@spec detach_debug_handler() :: :ok

Detaches the debug handler.

detach_default_handler()

@spec detach_default_handler() :: :ok

Detaches the default telemetry handler.

emit_event(event_name, measurements \\ %{}, metadata \\ %{})

@spec emit_event(event_name(), measurements(), metadata()) :: :ok

Emits a telemetry event if telemetry is enabled and passes sampling/filters.

enabled?()

@spec enabled?() :: boolean()

Checks if telemetry is enabled.

error(metadata)

@spec error(metadata()) :: :ok

Emits general error event.

execute(event_name, measurements, metadata)

@spec execute(event_name(), measurements(), metadata()) :: :ok

Legacy execute function for backward compatibility.

get_config(key)

@spec get_config(atom()) :: any()

Gets a specific configuration value.

heartbeat_sent(metadata)

@spec heartbeat_sent(metadata()) :: :ok

Emits heartbeat sent event.

heartbeat_sent(pid, url, metadata \\ %{})

@spec heartbeat_sent(pid(), String.t(), metadata()) :: :ok

Legacy: Emits heartbeat event.

heartbeat_timeout(metadata)

@spec heartbeat_timeout(metadata()) :: :ok

Emits heartbeat timeout event.

measure_duration(component, operation, metadata \\ %{}, function)

@spec measure_duration(atom(), atom(), metadata(), (-> result)) :: result
when result: any()

Measures execution time of a function and emits start/stop events.

This is similar to span/3 but provides more explicit control over the event names and metadata structure.

measure_sub_operation(context, operation, function)

@spec measure_sub_operation(duration_context(), atom(), (-> result)) :: result
when result: any()

Measures a sub-operation within a duration context.

message_decode_start(metadata)

@spec message_decode_start(metadata()) :: :ok

Emits message decode start event.

message_decode_stop(metadata)

@spec message_decode_stop(metadata()) :: :ok

Emits message decode stop event.

message_decoded(metadata)

@spec message_decoded(metadata()) :: :ok

Emits message decoded event.

message_encode_start(metadata)

@spec message_encode_start(metadata()) :: :ok

Emits message encode start event.

message_encode_stop(metadata)

@spec message_encode_stop(metadata()) :: :ok

Emits message encode stop event.

message_encoded(metadata)

@spec message_encoded(metadata()) :: :ok

Emits message encoded event.

message_receive(metadata)

@spec message_receive(metadata()) :: :ok

Emits message receive event.

message_received(metadata)

@spec message_received(metadata()) :: :ok

Emits message received event.

message_received(pid, topic, event, payload, metadata \\ %{})

@spec message_received(pid(), String.t(), String.t(), map(), metadata()) :: :ok

Legacy: Emits message received event.

message_send(metadata)

@spec message_send(metadata()) :: :ok

Emits message send event.

message_sent(metadata)

@spec message_sent(metadata()) :: :ok

Emits message sent event.

message_sent(pid, topic, event, payload, metadata \\ %{})

@spec message_sent(pid(), String.t(), String.t(), map(), metadata()) :: :ok

Legacy: Emits message sent event.

optimization(optimization_type, metadata)

@spec optimization(atom(), metadata()) :: :ok

Emits optimization-related event.

optimization_binary_pool_hit(metadata)

@spec optimization_binary_pool_hit(metadata()) :: :ok

Emits binary pool hit optimization event.

optimization_cache_hit(metadata)

@spec optimization_cache_hit(metadata()) :: :ok

Emits cache hit optimization event.

optimization_cache_miss(metadata)

@spec optimization_cache_miss(metadata()) :: :ok

Emits cache miss optimization event.

optimization_process_hibernated(metadata)

@spec optimization_process_hibernated(metadata()) :: :ok

Emits process hibernated optimization event.

passes_filters?(event_name, measurements \\ %{})

@spec passes_filters?(event_name(), measurements()) :: boolean()

Checks if an event passes the configured filters.

reconnecting(pid, url, attempt, metadata \\ %{})

@spec reconnecting(pid(), String.t(), integer(), metadata()) :: :ok

Legacy: Emits reconnection attempt event.

reconnection_attempt(metadata)

@spec reconnection_attempt(metadata()) :: :ok

Emits reconnection attempt event.

reset_config()

@spec reset_config() :: :ok

Resets telemetry configuration to defaults.

sampler_rate()

@spec sampler_rate() :: float()

Gets the current sampler rate.

should_sample?()

@spec should_sample?() :: boolean()

Checks if an event should be sampled based on the sampler rate.

socket_connected(pid, url, metadata \\ %{})

@spec socket_connected(pid(), String.t(), metadata()) :: :ok

Legacy: Emits socket connection event.

socket_connecting(pid, url, metadata \\ %{})

@spec socket_connecting(pid(), String.t(), metadata()) :: :ok

Legacy: Emits socket connection attempt event.

socket_connection_duration(pid, url, duration)

@spec socket_connection_duration(pid(), String.t(), non_neg_integer()) :: :ok

Legacy: Emits socket connection duration event.

socket_connection_error(pid, url, error, metadata \\ %{})

@spec socket_connection_error(pid(), String.t(), any(), metadata()) :: :ok

Legacy: Emits socket connection error event.

socket_disconnected(pid, url, reason, metadata \\ %{})

@spec socket_disconnected(pid(), String.t(), atom(), metadata()) :: :ok

Legacy: Emits socket disconnection event.

span(event_name, metadata, fun)

@spec span(event_name(), metadata(), (-> span_result())) :: span_result()

Executes a function with telemetry span for duration tracking.

This is the preferred way to track durations as it ensures proper start/stop event pairing and handles errors gracefully.

Example

Phoenix.SocketClient.Telemetry.span(
  [:phoenix, :socket_client, :connection],
  %{socket_ref: ref, url: url},
  fn -> connect_to_server() end
)

start_duration(component, operation, metadata \\ %{})

@spec start_duration(atom(), atom(), metadata()) :: duration_token()

Starts tracking duration for a specific operation.

Returns a tracking token that should be used with stop_duration/3.

stop_duration(token, additional_metadata \\ %{})

@spec stop_duration(duration_token(), map()) :: :ok

Stops duration tracking for a specific operation.

Emits the stop event with duration measurements.

track_durations?()

@spec track_durations?() :: boolean()

Checks if duration tracking is enabled.

track_memory_usage?()

@spec track_memory_usage?() :: boolean()

Checks if memory usage tracking is enabled.

track_message_sizes?()

@spec track_message_sizes?() :: boolean()

Checks if message size tracking is enabled.

update_config(new_config)

@spec update_config(map()) :: :ok

Updates telemetry configuration.