FAQ

Frequently asked questions about Logixlysia

Logixlysia is a high-performance logging plugin for Elysia.js that writes its own request logs and exposes a pino instance as store.pino for your application’s structured logging. It offers flexible configuration, file logging, and seamless integration with Elysia applications.

Why use Logixlysia instead of plain Pino?

Logixlysia provides:

Automatic request/response logging
Elysia plugin integration
Built-in file logging with rotation
Custom transport support
Simple configuration API
TypeScript support

Is Logixlysia production-ready?

Yes, Logixlysia is built for production environments. It includes log rotation, filtering, transport support and, for your own structured logging, a pino instance exposed as store.pino.

Installation

How do I install Logixlysia?

bun add logixlysia

Or with npm:

npm install logixlysia

What are the requirements?

Node.js 22+ or Bun
Elysia 1.4.30 or later (the ^1.4.30 peer range)

How do I install a preview build for an unreleased fix?

Every commit on main and every open pull request publishes an installable preview build to pkg.pr.new. Install by commit SHA or PR number:

bun add https://pkg.pr.new/logixlysia@<sha>
bun add https://pkg.pr.new/logixlysia@<pr-number>

Reach for a preview build when you want to reproduce a bug against the latest main, or verify that a fix in an open PR resolves your issue. These builds bypass the npm registry and are for testing only — do not use them in production. See Preview Releases for details.

Configuration

How do I disable console logging?

logixlysia({
  config: {
    disableInternalLogger: true
  }
})

How do I use only file logging?

logixlysia({
  config: {
    disableInternalLogger: true,
    logFilePath: './logs/app.log'
  }
})

How do I use only transports?

logixlysia({
  config: {
    useTransportsOnly: true,
    transports: [myTransport]
  }
})

How do I configure different settings for development and production?

const isDev = process.env.NODE_ENV === 'development'

logixlysia({
  config: {
    showStartupMessage: isDev,
    pino: {
      level: isDev ? 'debug' : 'info',
      prettyPrint: isDev
    }
  }
})

Usage

How do I access the logger in route handlers?

app.get('/users/:id', ({ store, request }) => {
  const { logger, pino } = store

  // Use logger helper
  logger.info(request, 'User accessed')

  // Or use Pino directly
  pino.info('User accessed')

  return { user: 'data' }
})

How do I log custom messages?

app.post(
  '/users',
  ({ store, body, request }) => {
    const { logger } = store

    logger.info(request, 'Creating user', {
      email: body.email
    })

    return createUser(body)
  },
  { body: t.Object({ email: t.String() }) }
)

How do I create child loggers?

app.get('/orders/:id', ({ store, params }) => {
  const { pino } = store

  const orderLogger = pino.child({
    orderId: params.id,
    module: 'order-service'
  })

  orderLogger.info('Processing order')

  return getOrder(params.id)
})

How do I use the logger outside of Elysia routes (in services, background jobs, etc.)?

Use store.pino directly for logging outside of HTTP request context:

// logger.ts
import logixlysia from 'logixlysia'

export const logixlysiaIns = logixlysia({
  config: {
    logFilePath: './logs/app.log',
    pino: {
      level: 'info',
      base: { service: 'my-api' }
    }
  }
})

// Export Pino for standalone use
export const logger = logixlysiaIns.store.pino

// services/user.service.ts
import { logger } from '../logger'

export class UserService {
  async createUser(data: any) {
    logger.info({ userId: data.id }, 'Creating user')
    // ... business logic
    logger.info({ userId: data.id }, 'User created successfully')
  }
}

Why can’t I use store.logger outside routes?

store.logger methods (.info(), .debug(), .warn(), .error()) require a Request object because they’re designed specifically for HTTP request logging with context like method, pathname, IP, and duration. For general-purpose logging, use store.pino instead.

File Logging

How do I enable file logging?

logixlysia({
  config: {
    logFilePath: './logs/app.log'
  }
})

How does log rotation work?

Log rotation automatically manages log file sizes and retention:

logRotation: {
  maxSize: '10m',    // Rotate when file reaches 10MB
  interval: '1d',    // Also rotate daily
  maxFiles: '7d',   // Keep logs for 7 days
  compress: true     // Compress rotated logs
}

Can I use multiple log files?

Currently, Logixlysia supports a single log file path. For multiple files, use custom transports.

Transports

How do I create a custom transport?

const myTransport = {
  log: async (level, message, meta) => {
    // Your logging logic here
    await sendToService(level, message, meta)
  }
}

logixlysia({
  config: {
    transports: [myTransport]
  }
})

Can I use multiple transports?

Yes, you can use multiple transports:

logixlysia({
  config: {
    transports: [elasticsearchTransport, slackTransport, mongodbTransport]
  }
})

Performance

What is the performance impact?

The plugin writes its own lines; on the request path that is one formatted line per request and, with autoRedact, one walk of the record. The impact is small, and transports send in the background.

Should I use file logging in production?

File logging is recommended for production environments. Use log rotation to manage disk space and consider compression for space savings.

How do I reduce logging overhead?

Use log filtering to log only important events
Use appropriate log levels
Consider using transports for high-volume scenarios
Disable pretty printing in production

Troubleshooting

IP logging shows empty or IP is not appearing

The {ip} placeholder reads from x-forwarded-for (first IP in the list) or x-real-ip headers. These are set by reverse proxies and load balancers. When testing on localhost or over a LAN without a proxy, these headers are not set, so the IP field will be empty.

To test IP logging locally:

curl -H 'x-real-ip: 1.2.3.4' http://localhost:3000/

In production behind nginx, Caddy, Cloudflare, or similar, the proxy typically sets these headers and IP logging works as expected.

Logs are not appearing

Check:

Log level configuration
Log filter settings
Output control settings (disableInternalLogger, disableFileLogging)
File permissions for file logging

File rotation is not working

Ensure:

logFilePath is set
File has write permissions
maxSize or interval is configured
Check console for rotation errors

Pino pretty printing not working

Make sure:

pino.prettyPrint is set to true
You’re in development mode (pretty printing is typically disabled in production)
You have pino-pretty installed if using transport-based pretty printing

Transports are not receiving logs

Check:

Transport is properly configured
Transport log method is not throwing errors
useTransportsOnly is not conflicting with other settings
Check console for transport errors

customLogFormat is not working for error logs

Ensure you’re using Logixlysia v6.0.2 or later. Earlier versions had a bug where error logs ignored the customLogFormat configuration and used a hardcoded format instead. This has been fixed in version 6.0.2+.

Before (v6.0.1 and earlier):

ERROR POST /api/users Validation failed

After (v6.0.2+): customLogFormat applies to error lines too. For JSON output use a transport, as shown in examples.

Migration

How do I migrate from another logging library?

Install Logixlysia
Replace your logging setup with logixlysia()
Update log calls to use store.logger or store.pino
Configure transports if needed

Description of the issue
Steps to reproduce
Expected behavior
Actual behavior
Environment details