Milvex.Telemetry (milvex v0.14.0)

Copy Markdown

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)

Migration Events

Emitted via :telemetry.span/3 from Milvex.Migration.Runner during mix milvex.migrate --apply. Skipped (e.g. --allow-drop not given) and blocked-by-impossible operations do NOT emit op-level events because they are never dispatched.

[:milvex, :migrate, :run, :start]

Emitted when an apply run begins (wraps the entire run).

  • Measurements: %{system_time: integer()}
  • Metadata:
    • :mode - Always :apply
    • :allow_drop - Whether destructive ops are allowed (boolean)
    • :manage_load - Whether to manage load state around mutations (boolean)

[:milvex, :migrate, :run, :stop]

Emitted when an apply run completes successfully.

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

[:milvex, :migrate, :run, :exception]

Emitted when an apply run 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

[:milvex, :migrate, :op, :start]

Emitted when a single migration operation is dispatched.

  • Measurements: %{system_time: integer()}
  • Metadata:
    • :kind - The operation kind atom (e.g. :create_collection, :add_field, :create_index)
    • :category - One of :additive, :destructive, :impossible, :descriptive
    • :collection_name - The fully prefixed collection name
    • :module - The originating Milvex.Collection DSL module
    • :requires_release - Whether the op needs the collection released (boolean)
    • :milvus_version - The Milvus server version string captured at run start

[:milvex, :migrate, :op, :stop]

Emitted when a single migration operation finishes.

  • Measurements: %{duration: integer()} (in native time units)
  • Metadata: same as :start plus:
    • :result - The status atom or tuple from the operation (e.g. :ok, {:error, reason})

[:milvex, :migrate, :op, :exception]

Emitted when a single migration operation 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

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
)