Technology
Bun
Dash0 seamlessly integrates with your Bun applications, providing clear visibility into your system's activity and performance.
Overview
Overview
Instrumenting your Bun application to generate traces, logs, and metrics is a powerful way to gain deep insights into its behavior and performance. By adding instrumentation, you enable your application to emit valuable data that can be used for monitoring, troubleshooting, and optimization.
Dash0 supports instrumentation of Bun applications through OpenTelemetry's open-source and vendor-agnostic packages. Bun applications require manual setup of an initialization file to properly configure OpenTelemetry.
Want AI to set this up for you? Install the Dash0 Agent Skills to let Claude Code, Cursor, or Windsurf instrument your application automatically with OpenTelemetry best practices.
Use Cases
- Understand outgoing and incoming HTTP requests through traces and metrics. Allowing drill-downs to the database level.
- You can see which database statements were executed and how long they took, which gives you valuable data to optimize your applications.
- Reveal (uncaught) errors and the context in which they happened.
Setup
Install
To instrument your Bun application, you'll need to install the OpenTelemetry SDK and the Node.js auto-instrumentation packages, as Bun is compatible with most Node.js packages:
bun add @opentelemetry/api \
@opentelemetry/sdk-node \
@opentelemetry/auto-instrumentations-node \
@opentelemetry/exporter-trace-otlp-http \
@opentelemetry/exporter-metrics-otlp-http \
@opentelemetry/semantic-conventions \
@opentelemetry/resourcesConfigure
Unlike Node.js, Bun requires a manual initialization file since it doesn't support the same --require flag that Node.js uses for auto-instrumentation. You'll need to create a separate initialization file and preload it.
1. Create an initialization file
Create a file named otel.ts in your project root with the following content:
import { NodeSDK } from "@opentelemetry/sdk-node";
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
import { resourceFromAttributes } from "@opentelemetry/resources";
import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions";
// Configure the SDK with auto-instrumentation
const sdk = new NodeSDK({
resource: resourceFromAttributes({
[ATTR_SERVICE_NAME]: process.env.OTEL_SERVICE_NAME || "bun-application",
[ATTR_SERVICE_VERSION]: process.env.OTEL_SERVICE_VERSION || "1.0.0",
}),
traceExporter: new OTLPTraceExporter(),
metricExporter: new OTLPMetricExporter(),
instrumentations: [getNodeAutoInstrumentations()],
});
// Start the SDK
sdk.start();
// Bun doesn't correctly handle process exit signals by default,
// so we need a way to properly shut down the SDK
const shutdownSignals = ["SIGTERM", "SIGINT", "SIGQUIT", "uncaughtException"];
// Gracefully shut down the SDK on termination signals
for (const signal of shutdownSignals) {
process.on(signal, () => {
sdk
.shutdown()
.then(() => console.log("OpenTelemetry SDK shut down successfully"))
.catch((error) => console.error("Error shutting down OpenTelemetry SDK", error))
.finally(() => {
if (signal !== "uncaughtException") {
process.exit(0);
}
});
});
}2. Configure environment variables
Set the following environment variables before starting your application:
export OTEL_SERVICE_NAME="my-bun-service"
export OTEL_EXPORTER_OTLP_ENDPOINT="{{endpoint_otlp_http}}"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer {{token}}"
export OTEL_METRICS_EXPORTER=otlp3. Run your application with the preloaded initialization file
bun run --preload './otel.ts' index.tsKubernetes Setup
In case you are not using the Dash0 operator for Kubernetes to deploy your application, you should extend the OpenTelemetry resource attributes to include the Pod UID. This is important to merge the resources between logs, traces, and metrics.
You need to modify your otel.ts file to include these attributes:
// In your otel.ts file
const sdk = new NodeSDK({
resource: resourceFromAttributes({
[ATTR_SERVICE_NAME]: process.env.OTEL_SERVICE_NAME || "bun-application",
[ATTR_SERVICE_VERSION]: process.env.OTEL_SERVICE_VERSION || "1.0.0",
[ATTR_K8S_POD_NAME]: process.env.K8S_POD_NAME,
[ATTR_K8S_POD_UID]: process.env.K8S_POD_UID,
}),
// ...other configuration
});And update your Kubernetes deployment:
env:
- name: K8S_POD_UID
valueFrom:
fieldRef:
apiVersion: v1
fieldPath: metadata.uid
- name: K8S_POD_NAME
valueFrom:
fieldRef:
apiVersion: v1
fieldPath: metadata.name
# Other environment variables...Supported libraries and frameworks
Since Bun uses the Node.js auto-instrumentation package, it supports most of the same libraries and frameworks. However, compatibility may vary as Bun continues to evolve.
To understand which libraries are automatically instrumented, please refer to the OpenTelemetry documentation.