# `NebulaGraphEx.Telemetry`
[🔗](https://github.com/VChain/nebula_graph_ex/blob/v0.1.8/lib/nebula_graph_ex/telemetry.ex#L1)

`:telemetry` integration for `nebula_graph_ex`.

## Events

All events share the same measurement and metadata shapes.

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

Emitted immediately before a query is sent to NebulaGraph.

**Measurements:** `%{system_time: integer()}`

**Metadata:** `%{statement: binary(), params: map(), opts: keyword()}`

---

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

Emitted after a successful query response is received and decoded.

**Measurements:** `%{duration: integer()}` — native time units (use
`:erlang.convert_time_unit/3` to convert to milliseconds).

**Metadata:**
`%{statement: binary(), params: map(), result: %NebulaGraphEx.ResultSet{}, opts: keyword()}`

---

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

Emitted when a query raises or returns `{:error, _}`.

**Measurements:** `%{duration: integer()}`

**Metadata:**
`%{statement: binary(), params: map(), error: %NebulaGraphEx.Error{}, opts: keyword()}`

---

## Attaching a default handler

Call `NebulaGraphEx.Telemetry.attach_default_handler/0` to log all queries
at the `:debug` level:

    NebulaGraphEx.Telemetry.attach_default_handler()

This is meant for development. In production, attach your own handler
that sends metrics to your observability backend.

## Custom handler example

    :telemetry.attach(
      "my-app-nebula-handler",
      [:nebula_graph_ex, :query, :stop],
      fn _event, %{duration: dur}, %{statement: stmt}, _config ->
        ms = System.convert_time_unit(dur, :native, :millisecond)
        MyApp.Metrics.histogram("nebula.query.duration_ms", ms, tags: [stmt: stmt])
      end,
      nil
    )

# `attach_default_handler`

```elixir
@spec attach_default_handler() :: :ok
```

Attaches a default Logger handler for all `nebula_graph_ex` query events.

Useful in development. Safe to call multiple times — re-attaching detaches
the old handler first.

---

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