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

Adapters Overview

Ship logs to observability platforms with built-in adapters

Send your logs to external observability platforms with built-in adapters. Each adapter is a regular transport — batched, retried, and non-blocking — so you can mix them with console and file logging or run them exclusively.

Available Adapters

Cloud Platforms

Platform Import Best for
Axiom logixlysia/axiom Schema-free log analytics — every field is queryable
Better Stack logixlysia/better-stack Logs, uptime, and alerting in one place
Datadog logixlysia/datadog Enterprise observability with facets and pipelines
Sentry logixlysia/sentry Structured logs next to your errors and traces
PostHog logixlysia/posthog Product analytics — link logs to persons and funnels

Self-Hosted & Open Standards

Platform Import Best for
OTLP logixlysia/otlp Any OpenTelemetry backend — collectors, Grafana Cloud, New Relic, Honeycomb, SigNoz
HyperDX logixlysia/hyperdx Open-source observability via OTLP
Grafana Loki logixlysia/loki Label-indexed logs for the Grafana stack
ClickHouse logixlysia/clickhouse Your own SQL log warehouse, no pipeline in between

Quick Start

Set the platform’s environment variables, create the transport, and pass it to transports:

import { Elysia } from 'elysia'
import logixlysia from 'logixlysia'
import { createAxiomTransport } from 'logixlysia/axiom'

const app = new Elysia()
  .use(
    logixlysia({
      config: {
        transports: [createAxiomTransport()]
      }
    })
  )
  .get('/', () => 'ok')
  .listen(3000)

Trigger a request and the access log appears in your platform’s log explorer.

Shared Behavior

All adapters share the same core:

  • Batching — entries buffer and flush either when maxBatchSize is reached (default 20) or after flushIntervalMs (default 2000 ms), whichever comes first. Entries that arrive while a request is in flight join the next request.
  • Retries — network errors, 429, and 5xx responses retry with linear backoff (default 2 retries). Other 4xx responses fail immediately.
  • Timeout — each request aborts after timeout ms (default 5000).
  • Non-blocking — sends run in the background and never delay your HTTP responses. A failure of a request that a log() or flush() call started reaches config.onError (sink 'transport'); a failure of a request the adapter started on its own, on the interval timer or after a request returned with a full batch waiting, reaches the adapter’s onError. Without a hook, either goes to stderr, rate-limited.
  • Copied at log time — each record’s meta is turned into a plain JSON copy when the adapter receives it, so a later change to a logged object is not shipped, and a value that cannot be serialized is replaced by "[Unserializable]" for that field only, an Error stored in a field keeps its name, message, cause and own fields (not its stack; the record’s own error is already a plain object and keeps the stack of a server error), a Map becomes an object and a Set an array (behind withRedaction the copy is taken when the wrapper delivers the record).
  • Credentials — read from environment variables by default; options passed to the factory always win. Missing credentials throw at startup with an actionable message, not silently at runtime.
  • Endpoint safety — endpoint URLs are validated when the transport is created and must use http: or https:, and requests never follow redirects, so a credential header can’t be forwarded to another origin.

Every adapter accepts these options on top of its platform-specific ones:

Option Type Default Description
maxBatchSize number 20 Entries buffered before an immediate flush
maxEntriesPerRequest number 500 The most entries one request carries (100 for Sentry)
flushIntervalMs number 2000 Max time an entry waits before the buffer is sent
timeout number 5000 Per-request timeout in milliseconds
retries number 2 Retry attempts on network errors, 429, and 5xx
maxPendingBatches number 32 Bound on waiting entries, as a multiple of maxBatchSize
minLevel 'DEBUG' | 'INFO' | 'WARNING' | 'ERROR' — Lowest level the adapter receives; quieter records skip it and are not counted as dropped
onError (error: unknown) => void — Called when a request the adapter started on its own fails after retries, or entries are dropped
onDropped (info: { count, reason }) => void — Called with how many entries were lost and why

The adapter factory validates these options when you call it. An invalid value throws [logixlysia] <adapter> transport: <option> must be ..., naming the option and the value it received. Omitted options use their defaults and are not affected.

Option Valid values
maxBatchSize, maxEntriesPerRequest, maxPendingBatches A positive integer (1 or more)
retries An integer at or above 0
timeout A whole number of milliseconds from 1 to 2147483647 (2^31 - 1)
flushIntervalMs A number of milliseconds from 0 to 2147483647
minLevel 'DEBUG', 'INFO', 'WARNING' or 'ERROR'

For example, retries: Infinity, timeout: 0, timeout: 1.5, timeout: 2 ** 31, and maxPendingBatches: NaN all throw at startup. The timeout ceiling matches the largest delay a timer honors. Node clamps a longer timer to 1 ms, which would abort every request. retries: 0 and flushIntervalMs: 0 stay valid.

Requests are sent one at a time, so entries arrive in the order they were logged. Under load, the entries that arrived during a send go out together in the next request, up to maxEntriesPerRequest, so a slow backend does not limit delivery to one batch per round trip. Once maxPendingBatches × maxBatchSize entries are waiting, a new entry is dropped and reported rather than buffered forever, unless it outranks the quietest entry waiting: then the oldest entry at that quietest level is dropped instead, so an ERROR is not lost to a burst of DEBUG lines. To see every failure in one place, including those of requests no caller is awaiting, forward the adapter’s onError to the function you give config.onError: onError: error => handle({ error, sink: 'transport' }), where handle is that function.

Counting lost entries

onDropped receives { count, reason } each time entries are lost. reason is 'queue-full' when too many entries were already waiting (count is 1, whichever entry was dropped), 'send-failed' when a request failed after its retries (count is the size of that batch), and 'closed' for a log() after close() (count is 1).

let lost = 0
const transport = createDatadogTransport({
  onDropped: ({ count }) => {
    lost += count
  }
})

onDropped adds to onError and does not replace it. A hook that throws is ignored.

Every built-in adapter transport has close(), which stops accepting entries and flushes the ones it already has; flushLogixlysia(options, { close: true }) calls it (a transport wrapped in withRedaction is not closed through the wrapper yet).

Your Own Backend

For a backend without a built-in adapter, createHttpTransport from logixlysia/http gives you the same batching, retries, bounded queue and onDropped. You supply the URL, headers, and a function that turns a batch into a request body. See the Elasticsearch example.

Multiple Destinations

Adapters compose — fan the same logs out to several platforms:

import logixlysia from 'logixlysia'
import { createAxiomTransport } from 'logixlysia/axiom'
import { createSentryTransport } from 'logixlysia/sentry'

app.use(
  logixlysia({
    config: {
      transports: [createAxiomTransport(), createSentryTransport()]
    }
  })
)

Production-Only External Logging

Use useTransportsOnly to disable console and file output and send logs exclusively to your platform:

app.use(
  logixlysia({
    config: {
      transports: [createAxiomTransport()],
      useTransportsOnly: process.env.NODE_ENV === 'production'
    }
  })
)

Graceful Shutdown

When the app stops, the plugin starts flushing every transport and the file sink. Elysia’s app.stop() does not wait for plugin stop hooks, so a process that exits right after await app.stop() can cut that flush short. Before you exit, await flushLogixlysia with the same options object you passed to the plugin. The stop hook’s own wait is bounded by flushTimeoutMs (5000 ms by default; 0 starts the flush without waiting), and a flush that runs out of time is reported through onError with sink: 'shutdown'.

What that does not cover:

  • SIGKILL, or a crash — nothing runs.
  • A process that exits without calling app.stop(), including a bare SIGINT with no handler.
  • A serverless function frozen between invocations.

Signals are yours to handle, because a library that installs its own handlers fights the rest of your process. This handler stops the app, waits for the flush, then exits:

import { Elysia } from 'elysia'
import logixlysia, { flushLogixlysia } from 'logixlysia'
import { createAxiomTransport } from 'logixlysia/axiom'

const options = { config: { transports: [createAxiomTransport()] } }
const app = new Elysia().use(logixlysia(options)).listen(3000)

process.on('SIGTERM', async () => {
  await app.stop()
  await flushLogixlysia(options)
  process.exit(0)
})

For workers, scripts, and anything else that logs outside the Elysia lifecycle, drain the sinks directly:

import { flushLogixlysia } from 'logixlysia'

await flushLogixlysia(options, { close: true })

close: true also releases sockets, timers, and the file handle; omit it to flush and keep logging.

What Gets Sent

Each log carries its level, message, and the full meta object: the request method and URL (the URL without its query string unless logQueryParams is true), the response status (on access and error lines; a custom log line is written before the response exists and carries no status), durationMs, and everything merged into the request context — request IDs, trace IDs, user IDs, and your own fields. Platforms that prefer flat attributes (HyperDX, Sentry, PostHog) receive dot-notation keys like request.method and context.requestId; Axiom receives the nested structure as-is.

Redaction runs before transports, so autoRedact and redactKeys apply to everything an adapter ships off-box.

Last updated on

Was this page helpful?