# `Trellis.LogBridge`
[🔗](https://github.com/salesforce-misc/trellis/blob/v0.1.0-alpha/clients/elixir/lib/trellis/log_bridge.ex#L1)

Forwards the engine's log lines to `Logger`.

The Rust engine logs through the `tracing` facade and never installs a
subscriber itself (`docs/decisions/0009-observability-decisions.md`,
decision 3). When the `:trellis_pg` application starts, this process installs
one in the Trellis NIF library, then drains what it queues into `Logger`,
with `domain: [:trellis]` and the emitting Rust module as `:target`
metadata. It needs no `Trellis` handle: every handle's lines come through
it.

## Configuration

    # Forward events at this level and more severe ones. Defaults to
    # `Logger.level()` when `:trellis_pg` starts. Rust's `trace` level
    # arrives as `:debug`.
    config :trellis_pg, log_level: :info

    # Opt out: nothing is installed, this process doesn't start, and the
    # engine's lines go nowhere.
    config :trellis_pg, log_bridge: false

The level is read once, when `:trellis_pg` starts. The engine drops events
above it before formatting them, so a later `Logger.configure/1` can make
`Logger` stricter but can't bring back a level the bridge filtered.

## What can be lost

A log line can be dropped; logging never blocks or crashes the engine. The
engine only appends to a bounded queue (10,000 lines), and this process
drains it every 100 ms. If the queue fills, because this process is
down, restarting, or falling behind, new lines are dropped and counted,
and the next drain logs a warning with the count.

## Composing your own subscriber

`tracing`'s global subscriber lives inside the native library that links
it, and the Trellis NIF links its own copy. So a subscriber another NIF
installs never sees the engine's lines, and doesn't stop this bridge.
Sending them elsewhere, for example through the crate's `otlp` layer,
means building your own NIF around the `trellis` crate that installs that
subscriber. If a subscriber in the Trellis NIF was installed first, this
process logs a warning and doesn't start, and the engine's lines go to
that subscriber instead.

# `flush`

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

Forwards every line queued so far to `Logger` before returning, rather
than on the next tick. For tests, and for a host that wants the engine's
last lines logged before it stops.

---

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