Skip to content

README.md

Latest commit

 

History

History
143 lines (103 loc) · 4.23 KB

README.md

File metadata and controls

143 lines (103 loc) · 4.23 KB

LogTide Logo

@logtide/elysia

npm License Elysia Release

LogTide plugin for Elysia — automatic request tracing, error capture, and breadcrumbs via lifecycle hooks.

Features

  • Automatic request spans via onRequest / onAfterHandle lifecycle hooks
  • Error capture via onError hook with full request context
  • W3C Trace Context propagation (traceparent in/out)
  • Breadcrumbs for HTTP requests
  • Global plugin — traces all routes automatically
  • Designed for Bun — works with Elysia's native runtime
  • Full TypeScript support with strict types

Installation

npm install @logtide/elysia
# or
pnpm add @logtide/elysia
# or
bun add @logtide/elysia

Quick Start

import { Elysia } from 'elysia';
import { logtide } from '@logtide/elysia';

const app = new Elysia()
  .use(logtide({
    dsn: 'https://lp_your_key@your-instance.com',
    // Or use apiUrl + apiKey instead of dsn:
    // apiUrl: 'https://your-instance.com',
    // apiKey: 'lp_your_key',
    service: 'my-elysia-api',
    environment: 'production',
  }))
  .get('/hello', () => 'Hello World')
  .listen(3000);

How It Works

The plugin registers global lifecycle hooks on the Elysia app:

  1. onRequest — extracts incoming traceparent, creates a span, stores scope on a WeakMap keyed by the request
  2. onAfterHandle — finishes the span with ok or error, injects traceparent into response headers
  3. onError — finishes the span as error, captures the error with full HTTP context

The plugin is registered with .as('global') so it applies to all routes, including those added after the plugin.

Configuration

All ClientOptions from @logtide/core are supported:

Option Type Default Description
dsn string required DSN string: https://lp_KEY@host/PROJECT
service string required Service name for log attribution
environment string — Environment (e.g. production, staging)
release string — Release / version identifier
debug boolean false Enable debug logging
tracesSampleRate number 1.0 Sample rate for traces (0.0 to 1.0)

See @logtide/core README for the full list of options.

Error Handling

Errors thrown by handlers are automatically captured:

const app = new Elysia()
  .use(logtide({ dsn: '...', service: 'my-api' }))
  .get('/boom', () => {
    throw new Error('Something broke');
    // Automatically captured with:
    // - http.url, http.method
    // - Error message and stack trace
    // - Span marked as 'error'
  });

Distributed Tracing

Incoming traceparent headers are extracted and used as parent context:

# Client sends a traced request
curl -H "traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01" \
  http://localhost:3000/api/data

The span created by the plugin will use the same trace ID, enabling end-to-end distributed tracing across services.

Outgoing responses include a traceparent header with the span's context.

Exports

import { logtide } from '@logtide/elysia';
import type { LogtideElysiaOptions } from '@logtide/elysia';

License

MIT License - see LICENSE for details.

Links