Telemetry events for ExMaude.

ExMaude uses the standard :telemetry library to emit events that can be consumed by monitoring tools, custom handlers, or exported to Prometheus, OpenTelemetry, and other observability platforms.

Event Conventions

All events follow standard conventions compatible with telemetry_metrics, Prometheus exporters, and OpenTelemetry:

• Measurements are always numeric values (durations in native time units)
• Metadata contains atoms for tags/labels (:ok or :error, not booleans)
• Event names follow [:app, :component, :action, :phase] pattern

Events

Command Events

Emitted for high-level Maude operations (reduce, rewrite, search, execute, parse, load_file, ensure_file_loaded, and load_module).

[:ex_maude, :command, :start]

• Measurements: %{system_time: integer}
• Metadata: %{operation: atom, module: String.t}

[:ex_maude, :command, :stop]

• Measurements: %{duration: integer} (native time units)

• Metadata: %{operation: atom, module: String.t, result: :ok | :error}

[:ex_maude, :command, :exception]

• Measurements: %{duration: integer}
• Metadata: %{operation: atom, module: String.t, kind: atom, reason: term}

Server (Worker) Events

Emitted by the backend workers (Port, C-Node, NIF) around the lifecycle of each Maude OS process. All carry %{system_time: integer} plus the numeric measurements below, with metadata %{pid: pid, backend: :port | :cnode | :nif}.

[:ex_maude, :server, :start]

• Metadata also includes %{maude_path: String.t}
• Emitted when a worker's Maude process is ready. Also fires when the pool replaces a worker after a timeout or crash.

[:ex_maude, :server, :command_start]

• Measurements: %{command_bytes: integer}
• Metadata includes command text only when config :ex_maude, telemetry_include_commands: true; opted-in text is truncated to 100 characters. Commands may contain sensitive application data, so the secure default is false.

[:ex_maude, :server, :command_complete]

• Measurements: %{response_size: integer} when available

• Metadata also includes %{result: :ok | :error}

[:ex_maude, :server, :timeout]

• Measurements: %{timeout_ms: integer} (Port also reports buffer_size)
• A command timed out. The worker stops with {:shutdown, _} and the pool starts a replacement (Maude cannot cancel an in-flight computation, so the session is no longer trustworthy); expect a follow-up [:ex_maude, :server, :start] event.

[:ex_maude, :server, :crash]

• Measurements: %{exit_status: integer}
• The Maude OS process exited unexpectedly.

Pool Events

Emitted for worker pool checkout operations.

[:ex_maude, :pool, :checkout, :start]

• Measurements: %{system_time: integer}

• Metadata: %{backend: :port | :cnode | :nif}

[:ex_maude, :pool, :checkout, :stop]

• Measurements: %{duration: integer}

• Metadata: %{result: :ok | :error, backend: :port | :cnode | :nif}

IoT Events

Emitted for IoT conflict detection operations.

[:ex_maude, :iot, :detect_conflicts, :start]

• Measurements: %{system_time: integer, rule_count: integer}
• Metadata: %{template: :iot_rules}

[:ex_maude, :iot, :detect_conflicts, :stop]

• Measurements: %{duration: integer, conflict_count: integer}

• Metadata: %{result: :ok | :error, template: :iot_rules}

AI Events

Emitted for AI conflict detection operations. Mirrors the IoT envelope so handlers can dispatch on the :template metadata key.

[:ex_maude, :ai, :detect_conflicts, :start]

• Measurements: %{system_time: integer, rule_count: integer}
• Metadata: %{template: :ai_rules}

[:ex_maude, :ai, :detect_conflicts, :stop]

• Measurements: %{duration: integer, conflict_count: integer}

• Metadata: %{result: :ok | :error, template: :ai_rules}

Attaching Handlers

Attach a handler to receive telemetry events:

:telemetry.attach(
  "my-app-ex-maude-handler",
  [:ex_maude, :command, :stop],
  fn event, measurements, metadata, config ->
    Logger.info("ExMaude command completed",
      operation: metadata.operation,
      duration_ms: System.convert_time_unit(measurements.duration, :native, :millisecond),
      result: metadata.result
    )
  end,
  nil
)

Or attach to multiple events:

:telemetry.attach_many(
  "my-app-ex-maude-handlers",
  ExMaude.Telemetry.events(),
  &MyApp.Telemetry.handle_event/4,
  nil
)

Prometheus Integration

Using telemetry_metrics in your consuming application:

defp metrics do
  [
    counter("ex_maude.command.stop.count",
      tags: [:operation, :result],
      description: "Total Maude commands executed"
    ),
    distribution("ex_maude.command.stop.duration",
      unit: {:native, :millisecond},
      tags: [:operation, :result],
      description: "Maude command execution time"
    ),
    counter("ex_maude.pool.checkout.stop.count",
      tags: [:result],
      description: "Pool checkout operations"
    ),
    distribution("ex_maude.pool.checkout.stop.duration",
      unit: {:native, :millisecond},
      tags: [:result],
      description: "Pool checkout time"
    ),
    counter("ex_maude.iot.detect_conflicts.stop.count",
      tags: [:result],
      description: "IoT conflict detections"
    ),
    last_value("ex_maude.iot.detect_conflicts.stop.conflict_count",
      description: "Number of conflicts detected"
    )
  ]
end

OpenTelemetry Integration

Using opentelemetry_telemetry in your consuming application:

OpentelemetryTelemetry.attach_default_handlers()

Converting Duration

Durations are in native time units. Convert for display:

duration_ms = System.convert_time_unit(duration, :native, :millisecond)
duration_us = System.convert_time_unit(duration, :native, :microsecond)