feat: wide-event, LogLayer-compatible observability architecture

[haydenshively]

Adds optional structured observability to viem-dlc, following the wide event model: one enriched event per call rather than a scatter of log lines.

Using it

import { withLogging } from '@morpho-org/viem-dlc'

await withLogging(() => client.request({ method: 'eth_getLogs', params: [filter] }), {
  logger,             // any LogLayer instance, or anything matching the `Logger` interface
  service: 'indexer', // extra opts become context fields on every event
})

loglayer is not a peer dependency — Logger is a local structural interface, so consumers who don't opt in neither install it nor need it to typecheck. Outside a withLogging scope the library emits nothing.

What gets emitted

Each outermost client.request inside the scope emits exactly one "concluded" event carrying call_id, duration_ms, status, the (size-trimmed) req, and every field contributed by the transports it passed through. Success emits at info; failure emits at error with the error attached via withError, so a host wired to forward withError entries to an ErrorReporter captures it automatically — one call, both a log and a Sentry event.

How transports contribute

Each transport declares its identity once, at factory scope:

const facetId = createFacetId(cacheTransportKey)   // one per composition node
…
request: observe(request, facetId)                 // counts crossings, pins the label
getObservability()?.facet(facetId).sub('eth_call') // accumulates fields

The FacetId object is both the field-name prefix and the instance token, so the two call sites can't drift apart. Fields land under the transport's key — viem-dlc-logs-divider.logs_fetched, viem-dlc-failover.succeeded_index. When one call crosses several instances of the same transport (a cache per failover branch, say), the first writes the bare key and later ones get .1, .2 in first-touch order, which is stable for a given composition. A layer crossed many times per call — the sieve and enricher run once per chunk under a divider fan-out — reuses its slot and aggregates via add/stat/push. Every boundary also stamps crossings, so the event records which transports the call traversed and how many times each.

Facets expose set (last-write-wins, for once-per-call facts), add (counters), stat (streaming count/min/max/avg), push (bounded arrays), and sub (name scoping). Event size is bounded: a 32KB budget drops the largest fields first and names them in truncated_fields.

Notable fields

Transport	Fields
cache	blob_key, gaps_fetched, n_followers, input_elements[_unique], elements_fetched, cache/read/write timings
logs-divider	from_block/to_block/latest_block, nominal_ranges, logs_fetched, splits_*, fetch_durations_ms histogram, failed_ranges
failover	branches_attempted, succeeded_index, branch_durations_ms, branch_errors
deployless	input_elements, nominal_batches, batch_bytes (packing utilization), splits_*
rate-limiter	queue_wait_ms — separates time queued behind our own limits from upstream latency
logs-sieve	logs_dropped, dropped_log_bytes — shows whether maxBytes is well-tuned

failed_ranges is worth calling out: Promise.all surfaces only the first rejection, so this bounded list is the only record of sibling chunks that failed in parallel.

Implementation

AsyncLocalStorage with exactly two levels — the withLogging seed, and one per-call store created by the outermost observe. Inner boundaries mutate that shared state rather than opening nested contexts, so ambient enrichment costs no per-layer plumbing and parallel calls stay isolated. In environments without AsyncLocalStorage (unpolyfilled browsers), withLogging degrades to a pass-through and the module is never imported.

Also here

logsSieve, logsDivider, and cache gained no behavioral changes; withRateLimit gained an optional onAdmitted callback, invoked after the caller's own await so wait samples are attributed to the call that waited rather than to whichever call happened to drain the queue.

[devin-ai-integration]

Devin Review found 2 potential issues.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 445eeff196

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[linear-code]

APPS-1259