# `Milvex.Telemetry`

Telemetry events emitted by Milvex.

Milvex uses `:telemetry` to emit events for gRPC operations, connection
lifecycle, and data encoding. You can attach handlers to these events
using `:telemetry.attach/4` or `:telemetry.attach_many/4`.

## RPC Events

Emitted via `:telemetry.span/3` for every gRPC call through `Milvex.RPC`.

### `[:milvex, :rpc, :start]`

Emitted when a gRPC call begins.

  * Measurements: `%{system_time: integer()}`
  * Metadata:
    * `:method` - The RPC method atom (e.g., `:insert`, `:search`)
    * `:stub` - The gRPC stub module
    * `:collection` - The collection name (or `nil` if not applicable)

### `[:milvex, :rpc, :stop]`

Emitted when a gRPC call completes successfully.

  * Measurements: `%{duration: integer()}` (in native time units)
  * Metadata: same as `:start` plus:
    * `:status_code` - The Milvus status code from the response (or `nil`)

### `[:milvex, :rpc, :exception]`

Emitted when a gRPC call raises an exception.

  * Measurements: `%{duration: integer()}` (in native time units)
  * Metadata: same as `:start` plus:
    * `:kind` - The exception kind (`:error`, `:exit`, `:throw`)
    * `:reason` - The raw exception reason
    * `:stacktrace` - The stacktrace
    * `:error_type` - Normalized error classification atom with bounded
      cardinality, safe for use as a metric tag. One of: `:connection`,
      `:grpc`, `:invalid`, `:argument`, `:timeout`, `:closed`,
      `:econnrefused`, `:econnreset`, or `:unknown`

### `[:milvex, :rpc, :retry]`

Emitted when an RPC call required retries (only if at least one retry occurred).

  * Measurements: `%{attempts: integer()}` (number of retries, not counting the initial attempt)
  * Metadata:
    * `:method` - The RPC method atom
    * `:stub` - The gRPC stub module
    * `:collection` - The collection name (or `nil`)

## Connection Lifecycle Events

Emitted via `:telemetry.execute/3` from `Milvex.Connection`.

### `[:milvex, :connection, :connect]`

Emitted when a connection is successfully established.

  * Measurements: `%{}`
  * Metadata:
    * `:host` - The Milvus host
    * `:port` - The Milvus port

### `[:milvex, :connection, :disconnect]`

Emitted when a connection is lost.

  * Measurements: `%{}`
  * Metadata:
    * `:host` - The Milvus host
    * `:port` - The Milvus port
    * `:reason` - The disconnect reason

### `[:milvex, :connection, :reconnect]`

Emitted when a reconnection attempt starts.

  * Measurements: `%{}`
  * Metadata:
    * `:host` - The Milvus host
    * `:port` - The Milvus port
    * `:retry_count` - Number of retries so far
    * `:delay_ms` - Backoff delay before this attempt

## Data Encoding Events

Emitted via `:telemetry.span/3` from `Milvex.Data`.

### `[:milvex, :data, :encode, :start]`

Emitted when data encoding (row-to-column conversion) begins.

  * Measurements: `%{system_time: integer()}`
  * Metadata:
    * `:row_count` - Number of rows being encoded
    * `:field_count` - Number of fields in the schema

### `[:milvex, :data, :encode, :stop]`

Emitted when data encoding completes.

  * Measurements: `%{duration: integer()}` (in native time units)
  * Metadata: same as `:start`

### `[:milvex, :data, :encode, :exception]`

Emitted when data encoding raises an exception.

  * Measurements: `%{duration: integer()}` (in native time units)
  * Metadata: same as `:start` plus:
    * `:kind` - The exception kind
    * `:reason` - The raw exception reason
    * `:stacktrace` - The stacktrace
    * `:error_type` - Normalized error classification atom (see RPC exception docs)

## Example

    :telemetry.attach_many(
      "milvex-logger",
      [
        [:milvex, :rpc, :stop],
        [:milvex, :connection, :connect],
        [:milvex, :connection, :disconnect]
      ],
      fn event, measurements, metadata, _config ->
        Logger.info("Milvex event: #{inspect(event)}, " <>
          "measurements: #{inspect(measurements)}, " <>
          "metadata: #{inspect(metadata)}")
      end,
      nil
    )

---

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