@spec attach_handler(atom(), list(), function()) :: :ok | {:error, term()}

Attaches a telemetry handler for common Caddy events.

@spec detach_handler(atom()) :: :ok

Detaches a telemetry handler.

@spec emit_adapt_event(atom(), map(), keyword() | map()) :: :ok

Emits a telemetry event for adaptation operations.

@spec emit_api_event(atom(), map(), keyword() | map()) :: :ok

Emits a telemetry event for API operations.

@spec emit_config_change(atom(), map(), keyword() | map()) :: :ok

Emits a telemetry event for configuration changes.

@spec emit_config_manager_event(atom(), map(), keyword() | map()) :: :ok

Emits a telemetry event for ConfigManager operations.

Event Types

• :sync_to_caddy - When syncing in-memory config to running Caddy
• :sync_from_caddy - When pulling config from running Caddy
• :drift_check - When checking for config drift
• :rollback - When rolling back to previous config
• :apply - When applying runtime config directly
• :validate - When validating config

Examples

Caddy.Telemetry.emit_config_manager_event(:sync_to_caddy, %{duration: 100}, %{success: true})

@spec emit_external_event(atom(), map(), keyword() | map()) :: :ok

Emits a telemetry event for external mode operations.

Event Types

• :init - When external server initializes
• :health_check - When health check is performed
• :command_executed - When a system command is executed
• :config_pushed - When configuration is pushed to external Caddy
• :status_changed - When Caddy status changes (running/stopped/unknown)
• :terminate - When external server terminates

Examples

Caddy.Telemetry.emit_external_event(:health_check, %{duration: 50}, %{status: :running})
Caddy.Telemetry.emit_external_event(:command_executed, %{duration: 100}, %{command: :restart})

@spec emit_file_event(atom(), map(), keyword()) :: :ok

Emits a telemetry event for file operations.

@spec emit_log_event(atom(), map(), keyword() | map()) :: :ok

Emits a telemetry event for logging operations.

@spec emit_metrics_event(atom(), map(), keyword() | map()) :: :ok

Emits a telemetry event for metrics operations.

Event Types

• :collected - When metrics are successfully fetched and parsed
• :fetch_error - When fetching metrics fails
• :poller_started - When the metrics poller starts
• :poller_stopped - When the metrics poller stops

Examples

Caddy.Telemetry.emit_metrics_event(:collected, %{duration: 50}, %{metric_count: 25})

@spec emit_resources_event(atom(), map(), keyword() | map()) :: :ok

Emits a telemetry event for Resources operations.

Event Types

• :get - When reading a resource
• :set - When updating a resource
• :delete - When deleting a resource
• :error - When an operation fails

Examples

Caddy.Telemetry.emit_resources_event(:get, %{duration: 50}, %{resource: :http_servers})

@spec emit_server_event(atom(), map(), keyword() | map()) :: :ok

Emits a telemetry event for server lifecycle events.

@spec emit_state_change_event(atom(), atom()) :: :ok

Emits a telemetry event for application state changes.

Event: [:caddy, :state, :changed]

This event is emitted whenever the application state machine transitions from one state to another.

Metadata

• :from - The previous state
• :to - The new state

Examples

Caddy.Telemetry.emit_state_change_event(:unconfigured, :configured)

@spec emit_validation_event(atom(), map(), keyword() | map()) :: :ok

Emits a telemetry event for configuration validation.

@spec list_events() :: list()

Returns list of all Caddy telemetry events.

@spec log_debug(String.t(), keyword() | map()) :: :ok

Emits a debug level log event.

Examples

Caddy.Telemetry.log_debug("Server starting", module: __MODULE__)

@spec log_error(String.t(), keyword() | map()) :: :ok

Emits an error level log event.

Examples

Caddy.Telemetry.log_error("Failed to start server", error: reason)

@spec log_info(String.t(), keyword() | map()) :: :ok

Emits an info level log event.

Examples

Caddy.Telemetry.log_info("Configuration loaded", config_size: 10)

@spec log_warning(String.t(), keyword() | map()) :: :ok

Emits a warning level log event.

Examples

Caddy.Telemetry.log_warning("Deprecated function used", function: :old_api)

@spec start_poller(non_neg_integer()) :: {:ok, pid()} | {:error, term()} | :ignore

Starts telemetry poller for periodic metrics.