Skip to content
Logixlysia
Esc
↑↓navigate↵open⌘Jpreview
On this page

Enrichers

Add context to every request once, and have it reach every sink

An enricher is a small function that contributes fields to the request context. Set it up once and the fields show up in the console tree, in file logs, and in every transport — Datadog, PostHog, Sentry, OTLP — without touching a single route.

import { Elysia } from 'elysia'
import logixlysia from 'logixlysia'
import { geoEnricher, traceparentEnricher } from 'logixlysia/enrichers'

new Elysia().use(
  logixlysia({
    config: {
      enrichers: [traceparentEnricher(), geoEnricher()]
    }
  })
)

Built-in Enrichers

traceparentEnricher()

Parses the W3C traceparent header directly, with no OpenTelemetry SDK required. That is the difference from logixlysia/otel, which reads the ids of the currently active span and therefore needs the SDK installed and instrumenting your app.

traceparentEnricher()
// → trace_id, span_id, trace_flags, trace_sampled

The trace_id / span_id naming matches what Sentry, HyperDX, and OTLP backends expect, so logs link to traces as soon as an upstream service propagates the header. The OTLP and HyperDX adapters also copy these values into the log record’s native traceId, spanId and flags fields.

Option Type Default Description
header string 'traceparent' Header to read the trace context from
tracestate boolean false Also record tracestate, capped at 512 chars

Malformed headers are ignored rather than partially parsed: the reserved ff version, all-zero trace or span ids, and a version 00 header carrying extra fields all add nothing.

userAgentEnricher()

Turns user-agent into fields you can group by.

userAgentEnricher()
// → ua.browser, ua.browserVersion, ua.os, ua.device, ua.bot

ua.device is one of desktop, mobile, tablet, or bot. This is a heuristic — user agents are not a parseable grammar — so treat it as a dashboard dimension, not as an access-control input.

geoEnricher()

Reads the geo headers your platform already attaches. Vercel, Cloudflare, and Netlify are recognized.

geoEnricher()
// → geo.city, geo.country, geo.region, geo.timezone, geo.latitude, geo.longitude

Nothing is derived from the IP address itself, and no lookup is performed. On a platform that does not set these headers, the enricher adds nothing. Vercel percent-encodes city names, which the enricher decodes for you.

These headers are set by the client unless the platform’s edge overwrites them, so read them as a hint, not a fact.

sizeEnricher()

Records payload sizes.

sizeEnricher()
// → requestBytes, responseBytes

Both come from content-length, the only size available without buffering a body. A chunked or streamed response has no content-length, so responseBytes is omitted rather than guessed.

Writing Your Own

An enricher is either a bare function — treated as the request phase — or an object with request and response phases.

// Request phase only.
const tenantEnricher = (request: Request) => ({
  tenant: request.headers.get('x-tenant-id') ?? 'unknown'
})

// Both phases.
const cacheEnricher = {
  request: (request: Request) => ({
    cacheKey: new URL(request.url).pathname
  }),
  response: ({ headers, status }) => ({
    cacheHit: headers['x-cache'] === 'HIT',
    served: status
  })
}

logixlysia({ config: { enrichers: [tenantEnricher, cacheEnricher] } })

Return undefined to add nothing.

Phases

Phase Runs Receives
request At request start The Request
response Once the outcome is known { request, status, durationMs, headers }

The response phase runs before the request’s final log line on both the success and the error path, so its fields are on the access log and on the error log alike. Request-phase fields, being merged at the start, also reach any log.info() you make inside the handler.

Response headers

headers holds the headers the client received. When a handler returns a Response and also sets set.headers, the Response’s value wins. set.headers only fills in headers the Response lacks. This matches what Elysia sends, so sizeEnricher’s responseBytes matches the wire.

headers['set-cookie'] holds the cookies from both sources, except that a set.headers array of cookies is dropped when the Response sets its own, as Elysia does. It is a string for one cookie and an array for several, so a custom enricher that reads it must handle both:

const cookieEnricher = {
  response: ({ headers }) => {
    const raw = headers['set-cookie']
    const cookies = raw === undefined ? [] : Array.isArray(raw) ? raw : [raw]
    return { cookiesSet: cookies.length }
  }
}

Failure Handling

Enrichment is decoration and must never take a request down. A hook that throws is caught, reported, and skipped — the remaining enrichers still run and the request completes normally.

Failures go to onError with sink: 'enricher', or to stderr (rate-limited) when no hook is configured.

logixlysia({
  config: {
    enrichers: [myEnricher],
    onError: ({ sink, error }) => {
      if (sink === 'enricher') {
        metrics.increment('logixlysia.enricher_error')
      }
    }
  }
})

Enrichers and Sampling

Enricher fields live in the request context, which is merged at emit time. A record rescued by tail sampling is replayed after the response phase has run, so replayed records carry the response-phase fields too.

Last updated on

Was this page helpful?