# `Lotus.Telemetry`
[🔗](https://github.com/typhoonworks/lotus/blob/v0.16.4/lib/lotus/telemetry.ex#L1)

Telemetry events emitted by Lotus.

Lotus uses `:telemetry` to emit events for query execution, cache operations,
and schema introspection. You can attach handlers to these events for monitoring,
logging, or integration with tools like Phoenix LiveDashboard or AppSignal.

## Query Events

### `[:lotus, :query, :start]`

Emitted when a query begins execution.

**Measurements:**

  * `:system_time` - The system time at the start of the query (in native units)

**Metadata:**

  * `:repo` - The Ecto repo module
  * `:sql` - The SQL statement being executed
  * `:params` - The query parameters

### `[:lotus, :query, :stop]`

Emitted when a query completes successfully.

**Measurements:**

  * `:duration` - The query duration (in native time units)
  * `:row_count` - The number of rows returned

**Metadata:**

  * `:repo` - The Ecto repo module
  * `:sql` - The SQL statement that was executed
  * `:params` - The query parameters
  * `:result` - The `Lotus.Result` struct

### `[:lotus, :query, :exception]`

Emitted when a query fails with an exception.

**Measurements:**

  * `:duration` - The time elapsed before the failure (in native time units)

**Metadata:**

  * `:repo` - The Ecto repo module
  * `:sql` - The SQL statement that was executed
  * `:params` - The query parameters
  * `:kind` - The kind of exception (`:error`, `:exit`, or `:throw`)
  * `:reason` - The exception or error reason
  * `:stacktrace` - The stacktrace

## Cache Events

### `[:lotus, :cache, :hit]`

Emitted when a cache lookup finds an existing entry.

**Measurements:**

  * `:count` - Always `1`

**Metadata:**

  * `:key` - The cache key

### `[:lotus, :cache, :miss]`

Emitted when a cache lookup does not find an entry.

**Measurements:**

  * `:count` - Always `1`

**Metadata:**

  * `:key` - The cache key

### `[:lotus, :cache, :put]`

Emitted when a value is stored in the cache.

**Measurements:**

  * `:count` - Always `1`

**Metadata:**

  * `:key` - The cache key
  * `:ttl_ms` - The TTL in milliseconds

## Schema Introspection Events

### `[:lotus, :schema, :introspection, :start]`

Emitted when a schema introspection operation begins.

**Measurements:**

  * `:system_time` - The system time at the start (in native units)

**Metadata:**

  * `:operation` - The introspection operation (e.g., `:list_schemas`, `:list_tables`,
    `:get_table_schema`, `:get_table_stats`, `:list_relations`)
  * `:repo` - The repo name

### `[:lotus, :schema, :introspection, :stop]`

Emitted when a schema introspection operation completes.

**Measurements:**

  * `:duration` - The operation duration (in native time units)

**Metadata:**

  * `:operation` - The introspection operation
  * `:repo` - The repo name
  * `:result` - `:ok` or `:error`

## Example

Attach a handler in your application's `start/2` callback:

    :telemetry.attach_many(
      "lotus-logger",
      [
        [:lotus, :query, :stop],
        [:lotus, :query, :exception],
        [:lotus, :cache, :hit],
        [:lotus, :cache, :miss]
      ],
      &MyApp.TelemetryHandler.handle_event/4,
      nil
    )

A simple logging handler:

    defmodule MyApp.TelemetryHandler do
      require Logger

      def handle_event([:lotus, :query, :stop], measurements, metadata, _config) do
        duration_ms = System.convert_time_unit(measurements.duration, :native, :millisecond)
        Logger.info("Lotus query completed in #{duration_ms}ms, rows: #{measurements.row_count}")
      end

      def handle_event([:lotus, :query, :exception], measurements, metadata, _config) do
        duration_ms = System.convert_time_unit(measurements.duration, :native, :millisecond)
        Logger.error("Lotus query failed after #{duration_ms}ms: #{inspect(metadata.reason)}")
      end

      def handle_event([:lotus, :cache, :hit], _measurements, metadata, _config) do
        Logger.debug("Lotus cache hit: #{metadata.key}")
      end

      def handle_event([:lotus, :cache, :miss], _measurements, metadata, _config) do
        Logger.debug("Lotus cache miss: #{metadata.key}")
      end
    end

---

*Consult [api-reference.md](api-reference.md) for complete listing*