# `Tama.Dex.Telemetry`
[🔗](https://github.com/kritama/tama-dex/blob/v0.1.0/lib/tama/dex/telemetry.ex#L1)

The telemetry events tama-dex emits.

Metadata is bounded and free of secrets. It never holds query text (only
its length), `execute` inputs or results, schemas, documents or file
paths.

## Spans

`[:tama_dex, name, :start | :stop | :exception]`, where `name` is
`:load`, `:import`, `:search` or `:execute`. `:start` carries
`monotonic_time` and `system_time`, `:stop` and `:exception` carry
`duration` and `monotonic_time`, in native time units. All three carry a
`telemetry_span_context` that ties them together.

| Span | `:start` metadata | `:stop` adds |
| --- | --- | --- |
| `:load` | `cassette` | `result` (`:ok` or the error kind), and on success `source`, `operations`, `changed` |
| `:import` | `cassette` | `result`, and on success `version`, `mode`, `changed`, `sources`, `operations` |
| `:search` | `cassette` (or nil), `query_length` (bytes), `limit` | `results`, `truncated`, and `not_ready: true` when the index wasn't ready |
| `:execute` | `cassette`, `operation_id` | `source` (or nil), `outcome` (`:ok`, `:operation_error` or a `Tama.Dex.Error` kind) |

`:load`, `:search` and `:execute` run in the calling process. `:import`
runs in the index's writer process.

An `:exception` event has the `:start` metadata plus `kind`, `reason` and
`stacktrace`, reduced so they hold no data:

- `reason` is the exception's module for an error (an Erlang error is
  normalized first, so `:function_clause` gives `FunctionClauseError`),
  an atom reason as is,
  the first element of a tuple reason when it's an atom (such as
  `:noproc` from an exit), and otherwise `:unknown`;
- `stacktrace` entries keep their module, function, arity and location,
  with argument lists replaced by their arity.

The exception itself still reaches the caller unchanged.

## Index events

- `[:tama_dex, :index, :recreated]`: a database with an unknown schema
  version was recreated empty. Metadata: `old_version`, `version`.
- `[:tama_dex, :index, :status]`: `Tama.Dex.Index.status/1` changed.
  Metadata: `status`, and `index`, the index's pid.

---

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