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
maxBatchSizeis reached (default 20) or afterflushIntervalMs(default 2000 ms), whichever comes first. Entries that arrive while a request is in flight join the next request. - Retries — network errors,
429, and5xxresponses retry with linear backoff (default 2 retries). Other4xxresponses fail immediately. - Timeout — each request aborts after
timeoutms (default 5000). - Non-blocking — sends run in the background and never delay your HTTP responses. A failure of a request that a
log()orflush()call started reachesconfig.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’sonError. Without a hook, either goes to stderr, rate-limited. - Copied at log time — each record’s
metais 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, anErrorstored in a field keeps itsname,message,causeand own fields (not its stack; the record’s ownerroris already a plain object and keeps thestackof a server error), aMapbecomes an object and aSetan array (behindwithRedactionthe 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:orhttps:, 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 bareSIGINTwith 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.