Telemetry

@halostack/telemetry is the full OpenTelemetry stack for the API. It collects traces, metrics, and logs and exports them over OTLP/HTTP, packaged as Elysia plugins together with a structured logger. Under the hood it's a hybrid: it combines the @elysia/opentelemetry plugin with a logger and metrics layer ported into this package.

Importing

Everything ships from a single entrypoint, @halostack/telemetry (src/index.ts). The key exports are:

• telemetry() — the tracing Elysia plugin. Mount it first so the root HTTP span wraps everything downstream.
• telemetryContext() — a per-request logger and timer plus HTTP metrics, reading the span established above.
• initObservability() and shutdownObservability() — boot and flush the logs and metrics pipelines.
• logger — the structured logger, paired with toError(e), which normalizes unknown thrown values into proper errors for logging.

Structure

The implementation is spread across small, focused modules: src/plugin.ts (the Elysia plugin), logger.ts, metrics.ts, observability.ts (init and shutdown), instrumentation.ts, active-span.ts, context.ts, anonymize-ip.ts, errors.ts, config.ts, and types.ts.

Conventions

Telemetry is designed to be always safe to mount, with a few rules to keep in mind:

• OTLP export is env-gated through @halostack/env (the observability schema). When export is disabled the package falls back to a no-op exporter, so mounting the plugin is always harmless.
• The OpenTelemetry dependencies are kept external in the API build (see the apps/api build flags) — don't inline them.
• Use the official @elysia/* scope for Elysia plugins, not the legacy @elysiajs/* one. And avoid throwing inside a derive: an error there surfaces as a 404 rather than a 500.