# `GcpCompute.Telemetry`
[🔗](https://github.com/nyo16/gcp_compute/blob/v0.3.0/lib/gcp_compute/telemetry.ex#L1)

Telemetry events emitted by the library.

Every HTTP call to the Compute API is wrapped in a `:telemetry.span/3`, so you
get the standard `:start` / `:stop` / `:exception` trio.

## Events

  * `[:gcp_compute, :request, :start]` —
    measurements: `%{system_time, monotonic_time}`;
    metadata: `%{method, path, project}`.

  * `[:gcp_compute, :request, :stop]` —
    measurements: `%{duration, monotonic_time}`;
    metadata: `%{method, path, project, result, http_status}`
    (`result` is `:ok` or `:error`; `http_status` is present on API errors).

  * `[:gcp_compute, :request, :exception]` —
    measurements: `%{duration, monotonic_time}`;
    metadata: `%{method, path, project, kind, reason, stacktrace}`.

## Attaching a quick logger

    GcpCompute.Telemetry.attach_default_logger()
    GcpCompute.Telemetry.detach_default_logger()

or wire the events into `Telemetry.Metrics` / your reporter of choice.

> #### Do not log `:exception` metadata verbatim {: .warning}
>
> The `:exception` event's `:stacktrace` (and `:reason`) can contain a frame
> holding the bearer token — Req's auth step receives `{:bearer, token}` as
> an argument. `GcpCompute` never raises with a token in scope on any path it
> controls, and `GcpCompute.Error` redacts `:body` on `inspect/1`, but a
> handler that does `inspect(metadata)` or ships raw stacktraces to an error
> tracker bypasses both. Log `:kind` and a classified reason, not the frames.

# `attach_default_logger`

```elixir
@spec attach_default_logger(Logger.level()) :: :ok | {:error, :already_exists}
```

Attach a simple `Logger` handler for request stops/exceptions.

Intended for development. In production prefer `Telemetry.Metrics` + a reporter.
Pair it with `detach_default_logger/0`.

# `detach_default_logger`

```elixir
@spec detach_default_logger() :: :ok | {:error, :not_found}
```

Detach the handler installed by `attach_default_logger/1`.

Returns `:ok`, or `{:error, :not_found}` if it was never attached.

# `events`

```elixir
@spec events() :: [[atom()]]
```

The list of telemetry events this library emits.

---

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