Vaultx.Base.Telemetry (Vaultx v0.7.0)
View SourceEnterprise observability and telemetry for Vaultx HashiCorp Vault client.
This module provides comprehensive telemetry capabilities for monitoring Vault operations, performance metrics, and operational insights. It integrates seamlessly with Elixir's Telemetry ecosystem and can be completely disabled for maximum performance when observability is not required.
Core Capabilities
- Optional: Can be completely disabled via configuration
- Zero Overhead: When disabled, all functions become no-ops
- Comprehensive Events: Covers all major Vaultx operations
- Structured Metadata: Rich context for monitoring and debugging
- Performance Metrics: Duration, success/failure rates, and more
Event Structure
All events follow the pattern [:vaultx, :operation, :event_type]:
Core Operation Events
[:vaultx, :http, :request, :start]- HTTP request started[:vaultx, :http, :request, :stop]- HTTP request completed[:vaultx, :auth, :start]- Authentication started[:vaultx, :auth, :stop]- Authentication completed[:vaultx, :secret, :read, :start]- Secret read started[:vaultx, :secret, :read, :stop]- Secret read completed[:vaultx, :secret, :write, :start]- Secret write started[:vaultx, :secret, :write, :stop]- Secret write completed
Enhanced Telemetry Events
[:vaultx, :cache, :metrics]- Cache performance metrics[:vaultx, :cache, :hit]- Cache hit occurred[:vaultx, :cache, :miss]- Cache miss occurred[:vaultx, :cache, :eviction]- Cache entry evicted[:vaultx, :pool, :metrics]- Connection pool metrics[:vaultx, :pool, :exhaustion]- Pool exhaustion event[:vaultx, :security, :event]- Security-related events[:vaultx, :security, :anomaly]- Security anomaly detected[:vaultx, :business, :secret_access]- Secret access patterns[:vaultx, :business, :engine_usage]- Engine usage statistics[:vaultx, :performance]- Enhanced performance metrics
Measurements
:duration- Operation duration in native time units:monotonic_time- Monotonic time when event occurred:system_time- System time when event occurred
Metadata
:operation- The operation being performed:path- Vault path being accessed:method- HTTP method used:status- HTTP status code (for stop events):error- Error information (for failed operations)
Usage
# Attach a handler for all HTTP events
:ok = Vaultx.Base.Telemetry.attach(
"my-http-handler",
[[:vaultx, :http, :request, :start], [:vaultx, :http, :request, :stop]],
&MyApp.TelemetryHandler.handle_event/4,
%{}
)
# Use span for automatic start/stop events
result = Vaultx.Base.Telemetry.span(
[:operation, :read],
%{path: "secret/myapp/config"},
fn ->
# Your operation here
{:ok, %{"key" => "value"}}
end
)Configuration
# Enable/disable telemetry
config :vaultx, telemetry_enabled: true
# Or via environment variable
export VAULTX_TELEMETRY_ENABLED=trueReferences
- Telemetry Library - Elixir telemetry system
- Vault Telemetry - Vault telemetry concepts
Summary
Functions
Attaches a telemetry handler.
Attaches multiple telemetry handlers.
Records a failed authentication
Records the start of an authentication attempt
Records a successful authentication
Detaches a telemetry handler.
Emits business intelligence metrics.
Emits cache events (hit, miss, eviction).
Emits cache performance metrics.
Emits enhanced performance metrics.
Emits connection pool events.
Emits connection pool metrics.
Emits security anomaly events.
Emits security events with severity levels.
Checks if telemetry is enabled.
Executes a Telemetry event if telemetry is enabled.
Records an HTTP request exception
Records the start of an HTTP request
Records a completed HTTP request
Returns telemetry configuration and status.
Lists all attached telemetry handlers.
Measures the execution time of a function and emits telemetry events.
Records a failed operation
Records the start of a Vault operation
Records a successful operation
Executes a span with automatic start/stop events if telemetry is enabled.
Checks if the telemetry library is available.
Functions
Attaches a telemetry handler.
This is a convenience wrapper around :telemetry.attach/4.
Examples
iex> :ok = Vaultx.Base.Telemetry.attach(
...> "my-handler",
...> [[:vaultx, :http, :request, :stop]],
...> &MyHandler.handle_event/4,
...> %{}
...> )Attaches multiple telemetry handlers.
This is a convenience wrapper around :telemetry.attach_many/4.
Examples
iex> :ok = Vaultx.Base.Telemetry.attach_many(
...> "my-handlers",
...> [[:vaultx, :http, :request, :start], [:vaultx, :http, :request, :stop]],
...> &MyHandler.handle_event/4,
...> %{}
...> )@spec auth_failure(non_neg_integer(), map()) :: :ok
Records a failed authentication
@spec auth_start(map()) :: :ok
Records the start of an authentication attempt
@spec auth_success(non_neg_integer(), map()) :: :ok
Records a successful authentication
Detaches a telemetry handler.
This is a convenience wrapper around :telemetry.detach/1.
Examples
iex> :ok = Vaultx.Base.Telemetry.detach("my-handler")Emits business intelligence metrics.
Examples
iex> Vaultx.Base.Telemetry.emit_business_metrics(:secret_access, 1, %{engine: "kv"})
:okEmits cache events (hit, miss, eviction).
Examples
iex> Vaultx.Base.Telemetry.emit_cache_event(:hit, "secret/myapp/config")
:ok@spec emit_cache_metrics(float(), non_neg_integer(), non_neg_integer(), map()) :: :ok
Emits cache performance metrics.
Examples
iex> Vaultx.Base.Telemetry.emit_cache_metrics(0.85, 1000, 52428800)
:ok@spec emit_performance_metrics(atom(), non_neg_integer(), boolean(), map()) :: :ok
Emits enhanced performance metrics.
Examples
iex> Vaultx.Base.Telemetry.emit_performance_metrics(:read, 1500000, true, %{engine: "kv"})
:okEmits connection pool events.
Examples
iex> Vaultx.Base.Telemetry.emit_pool_event(:exhaustion, %{pool_name: "vault_pool"})
:ok@spec emit_pool_metrics( non_neg_integer(), non_neg_integer(), non_neg_integer(), [non_neg_integer()], map() ) :: :ok
Emits connection pool metrics.
Examples
iex> Vaultx.Base.Telemetry.emit_pool_metrics(5, 3, 2, [100, 150, 200])
:okEmits security anomaly events.
Examples
iex> Vaultx.Base.Telemetry.emit_security_anomaly("Unusual access pattern detected", :high)
:okEmits security events with severity levels.
Examples
iex> Vaultx.Base.Telemetry.emit_security_event(:auth_failure, :medium, %{user_id: "user123"})
:ok@spec enabled?() :: boolean()
Checks if telemetry is enabled.
Examples
iex> Vaultx.Base.Telemetry.enabled?()
trueExecutes a Telemetry event if telemetry is enabled.
This is a no-op when telemetry is disabled, providing zero overhead.
Examples
iex> Vaultx.Base.Telemetry.execute([:http, :request, :start], %{system_time: System.system_time()})
:ok@spec http_request_exception(non_neg_integer(), map()) :: :ok
Records an HTTP request exception
@spec http_request_start(map()) :: :ok
Records the start of an HTTP request
@spec http_request_stop(non_neg_integer(), map()) :: :ok
Records a completed HTTP request
@spec info() :: %{ enabled: boolean(), handlers_count: non_neg_integer(), available_events: [[atom()]] }
Returns telemetry configuration and status.
Examples
iex> info = Vaultx.Base.Telemetry.info()
iex> info.enabled
trueLists all attached telemetry handlers.
This is a convenience wrapper around :telemetry.list_handlers/1.
Examples
iex> handlers = Vaultx.Base.Telemetry.list_handlers([:vaultx])Measures the execution time of a function and emits telemetry events.
This is a convenience function that combines start/stop events with duration measurement.
Examples
iex> result = Vaultx.Base.Telemetry.measure([:http, :request], %{method: :get}, fn ->
...> # Perform HTTP request
...> {:ok, %{status: 200}}
...> end)
iex> result
{:ok, %{status: 200}}@spec operation_failure(non_neg_integer(), map()) :: :ok
Records a failed operation
@spec operation_start(map()) :: :ok
Records the start of a Vault operation
@spec operation_success(non_neg_integer(), map()) :: :ok
Records a successful operation
Executes a span with automatic start/stop events if telemetry is enabled.
When telemetry is disabled, this simply executes the function without emitting any events, providing zero overhead.
Examples
iex> result = Vaultx.Base.Telemetry.span([:operation, :read], %{path: "secret/test"}, fn ->
...> {:ok, %{"key" => "value"}}
...> end)
iex> result
{:ok, %{"key" => "value"}}@spec telemetry_available?() :: boolean()
Checks if the telemetry library is available.
Examples
iex> Vaultx.Base.Telemetry.telemetry_available?()
true