To start using OpenTelemetry, install @elysiajs/opentelemetry
and apply plugin to any instance.
import { Elysia } from 'elysia'
import { opentelemetry } from '@elysiajs/opentelemetry'
import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-node'
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto'
new Elysia()
.use(
opentelemetry({
spanProcessors: [
new BatchSpanProcessor(
new OTLPTraceExporter()
)
]
})
)
Elysia OpenTelemetry is will collect span of any library compatible OpenTelemetry standard, and will apply parent and child span automatically.
In the code above, we apply Prisma
to trace how long each query took.
By applying OpenTelemetry, Elysia will then:
- collect telemetry data
- Grouping relevant lifecycle together
- Measure how long each function took
- Instrument HTTP request and response
- Collect error and exception
You may export telemetry data to Jaeger, Zipkin, New Relic, Axiom or any other OpenTelemetry compatible backend.
Here's an example of exporting telemetry to Axiom
import { Elysia } from 'elysia'
import { opentelemetry } from '@elysiajs/opentelemetry'
import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-node'
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto'
new Elysia()
.use(
opentelemetry({
spanProcessors: [
new BatchSpanProcessor(
new OTLPTraceExporter({
url: 'https://api.axiom.co/v1/traces',
headers: {
Authorization: `Bearer ${Bun.env.AXIOM_TOKEN}`,
'X-Axiom-Dataset': Bun.env.AXIOM_DATASET
}
})
)
]
})
)
OpenTelemetry SDK
Elysia OpenTelemetry is for applying OpenTelemetry to Elysia server only.
You may use OpenTelemetry SDK normally, and the span is run under Elysia's request span, it will be automatically appear in Elysia trace.
However, we also provide a getTracer
, and record
utility to collect span from any part of your application.
import { Elysia } from 'elysia'
import { record } from '@elysiajs/opentelemetry'
export const plugin = new Elysia()
.get('', () => {
return record('database.query', () => {
return db.query('SELECT * FROM users')
})
})
Record utility
record
is an equivalent to OpenTelemetry's startActiveSpan
but it will handle auto-closing and capture exception automatically.
You may think of record
as a label for your code that will be shown in trace.
Prepare your codebase for observability
Elysia OpenTelemetry will group lifecycle and read the function name of each hook as the name of the span.
It's a good time to name your function.
If your hook handler is an arrow function, you may refactor it to named function to understand the trace better otherwise, your trace span will be named as anonymous
.
const bad = new Elysia()
// ⚠️ span name will be anonymous
.derive(async ({ cookie: { session } }) => {
return {
user: await getProfile(session)
}
})
const good = new Elysia()
// ✅ span name will be getProfile
.derive(async function getProfile({ cookie: { session } }) {
return {
user: await getProfile(session)
}
})
Config
This plugin extends OpenTelemetry SDK parameters options.
Below is a config which is accepted by the plugin
autoDetectResources - boolean
Detect resources automatically from the environment using the default resource detectors.
default: true
contextManager - ContextManager
Use a custom context manager.
default: AsyncHooksContextManager
textMapPropagator - TextMapPropagator
Use a custom propagator.
default: CompositePropagator
using W3C Trace Context and Baggage
metricReader - MetricReader
Add a MetricReader that will be passed to the MeterProvider.
views - View[]
A list of views to be passed to the MeterProvider.
Accepts an array of View-instances. This parameter can be used to configure explicit bucket sizes of histogram metrics.
instrumentations - (Instrumentation | Instrumentation[])[]
Configure instrumentations.
By default getNodeAutoInstrumentations
is enabled, if you want to enable them you can use either metapackage or configure each instrumentation individually.
default: getNodeAutoInstrumentations()
resource - IResource
Configure a resource.
Resources may also be detected by using the autoDetectResources method of the SDK.
resourceDetectors - Array<Detector | DetectorSync>
Configure resource detectors. By default, the resource detectors are [envDetector, processDetector, hostDetector]. NOTE: In order to enable the detection, the parameter autoDetectResources has to be true.
If resourceDetectors was not set, you can also use the environment variable OTEL_NODE_RESOURCE_DETECTORS to enable only certain detectors, or completely disable them:
- env
- host
- os
- process
- serviceinstance (experimental)
- all - enable all resource detectors above
- none - disable resource detection
For example, to enable only the env, host detectors:
export OTEL_NODE_RESOURCE_DETECTORS="env,host"
sampler - Sampler
Configure a custom sampler. By default, all traces will be sampled.
serviceName - string
Namespace to be identify as.
spanProcessors - SpanProcessor[]
An array of span processors to register to the tracer provider.
traceExporter - SpanExporter
Configure a trace exporter. If an exporter is configured, it will be used with a BatchSpanProcessor
.
If an exporter OR span processor is not configured programmatically, this package will auto setup the default otlp exporter with http/protobuf protocol with a BatchSpanProcessor.
spanLimits - SpanLimits
Configure tracing parameters. These are the same trace parameters used to configure a tracer.