@astroscope/opentelemetry

> Note: This package is in active development. APIs may change between versions.

OpenTelemetry for Astro — tracing, metrics, and component instrumentation that works in dev mode. No monkey-patching required.

Examples

- demo/opentelemetry - Integration-based tracing (works in dev and production)
- demo/opentelemetry-native - Native ESM auto-instrumentation (production only)

Why?

OpenTelemetry's auto-instrumentation relies on monkey-patching Node.js modules, which has two challenges:

1. ESM support is still experimental - Node.js ESM modules can't be monkey-patched like CommonJS. The OpenTelemetry team has been working on this for years (#1946, #4553), and while there's progress, it requires experimental loader hooks that aren't yet stable.

2. Vite dev mode loads modules before instrumentation - Auto-instrumentation must run before any instrumented modules (like http) are imported. In Vite's dev mode, modules are loaded dynamically, making it impossible to instrument them in time.

This package handles both issues by creating spans directly in Astro's request lifecycle - no monkey-patching required. It works in both dev mode and production.

$3

| Feature | @astroscope/opentelemetry | Native auto-instrumentation |
|---------|---------------------------|----------------------------|
| Works in dev mode | ✅ | ❌ |
| Works in production | ✅ | ✅ |
| Incoming HTTP requests | ✅ | ✅ |
| Outgoing fetch requests | ✅ | ❌ (ESM not supported) |
| Astro actions | ✅ (named spans) | ❌ |
| Component tracing | ✅ ( component) | ❌ |
| Metrics (Prometheus-compatible) | ✅ | ✅ |
| Other libraries | ❌ | ✅ (varies by library) |
| Setup complexity | Simple | Requires --import flag |
| Bundle size | Minimal | Heavy (30+ packages) |
| Cold start impact | Negligible | Significant |

Installation

``bash
npm install @astroscope/opentelemetry @opentelemetry/api @opentelemetry/core @opentelemetry/sdk-node
`

Setup

$3

The OpenTelemetry SDK must be initialized before traces can be collected. Use @astroscope/boot for proper lifecycle management:

`ts
// src/boot.ts
import { NodeSDK } from "@opentelemetry/sdk-node";

const sdk = new NodeSDK({
// configuration at https://opentelemetry.io/docs/languages/js/getting-started/nodejs/
});

export function onStartup() {
sdk.start();
}

export async function onShutdown() {
await sdk.shutdown();
}
`

Note, since this integration creates spans directly, you don't need to

- add any instrumentations to the SDK configuration
- use specific import order for auto-instrumentation (since none is used)

$3

`ts
// astro.config.ts
import { defineConfig } from "astro/config";
import boot from "@astroscope/boot";
import opentelemetry from "@astroscope/opentelemetry";

export default defineConfig({
integrations: [opentelemetry(), boot()], // opentelemetry() should come as early as possible in the list
});
`

This automatically:
- Adds middleware to trace incoming HTTP requests
- Instruments fetch() to trace outgoing requests
- Uses RECOMMENDED_EXCLUDES to skip static assets
- Provides component for tracing specific sections or components

Integration Options

`ts
opentelemetry({
instrumentations: {
http: {
enabled: true, // default: true
exclude: [...RECOMMENDED_EXCLUDES, { exact: "/health" }],
},
fetch: {
enabled: true, // default: true
},
},
})
`

$3

Controls incoming HTTP request tracing via middleware.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| enabled | boolean | true | Enable/disable HTTP tracing |
| exclude | ExcludePattern[] | RECOMMENDED_EXCLUDES | Paths to exclude from tracing |

$3

Controls outgoing fetch request tracing.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| enabled | boolean | true | Enable/disable fetch tracing |

Metrics

To export metrics, configure a metrics reader in your SDK (e.g., Prometheus exporter):

`ts
// src/boot.ts
import { NodeSDK } from "@opentelemetry/sdk-node";
import { PrometheusExporter } from "@opentelemetry/exporter-prometheus";

const prometheusExporter = new PrometheusExporter({ port: 9464 });

const sdk = new NodeSDK({
serviceName: "my-astro-app",
metricReader: prometheusExporter,
});

export function onStartup() {
sdk.start();
}
`

or use OTLP metrics exporter (for Grafana, Datadog, etc.):

`ts
import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";

const metricReader = new PeriodicExportingMetricReader({
exporter: new OTLPMetricExporter(),
exportIntervalMillis: 60000,
});

const sdk = new NodeSDK({ metricReader });
`

$3

| Metric | Type | Unit | Description |
|--------|------|------|-------------|
| http.server.request.duration | Histogram | seconds | Duration of incoming HTTP requests |
| http.server.active_requests | UpDownCounter | requests | Number of active HTTP requests |
| http.client.request.duration | Histogram | seconds | Duration of outgoing fetch requests |
| astro.action.duration | Histogram | seconds | Duration of Astro action executions |

$3

HTTP Server metrics:
- http.request.method - HTTP method (GET, POST, etc.)
- http.route - Request path
- http.response.status_code - Response status code

HTTP Client (fetch) metrics:
- http.request.method - HTTP method
- server.address - Target hostname
- http.response.status_code - Response status code

Astro Action metrics:
- astro.action.name - Action name (e.g., newsletter.subscribe)
- http.response.status_code - Response status code
`

$3

For system-level and Node.js runtime metrics (CPU, memory, event loop, GC), add these packages:

`bash
npm install @opentelemetry/host-metrics @opentelemetry/instrumentation-runtime-node
`

`ts
// src/boot.ts
import { NodeSDK } from "@opentelemetry/sdk-node";
import { PrometheusExporter } from "@opentelemetry/exporter-prometheus";
import { HostMetrics } from "@opentelemetry/host-metrics";
import { RuntimeNodeInstrumentation } from "@opentelemetry/instrumentation-runtime-node";

const sdk = new NodeSDK({
serviceName: "my-astro-app",
metricReader: new PrometheusExporter({ port: 9464 }),
instrumentations: [new RuntimeNodeInstrumentation()],
});

let hostMetrics: HostMetrics;

export function onStartup() {
sdk.start();

// the host metrics should be called after sdk.start()
hostMetrics = new HostMetrics({ name: "my-astro-app" });
hostMetrics.start();
}
`

This adds:
- Host metrics: process.cpu., system.cpu., system.memory., system.network.
- Runtime metrics: nodejs.eventloop.delay.*, nodejs.gc.duration, nodejs.eventloop.utilization

Component Tracing

Trace specific sections or components using the component:

`astro
---
import { Trace } from "@astroscope/opentelemetry/components";
---




`

$3

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| name | string | required | Span name |
| params | Record | {} | Custom span attributes |
| enabled | boolean | true | Enable/disable tracing (useful for conditional tracing) |
| withTimings | boolean | false | Enable accurate duration measurement |

$3

By default, preserves Astro's streaming behavior by creating an instant marker span (>> name). This is safe to use anywhere without affecting performance.

`astro





`

For accurate render duration measurement, use withTimings:

`astro




`

Important: withTimings buffers all children before streaming. Use it only when:
- Wrapping a single component where you need timing
- You understand it will block streaming for that section

$3

| Mode | Span Name | Description |
|------|-----------|-------------|
| withTimings={false} | >> section-name | Instant marker, no duration |
| withTimings={true} | RENDER section-name | Full render duration |

$3

Use enabled to conditionally trace (e.g., in recursive components):

`astro
---
const { depth = 0 } = Astro.props;
---



{children.map(child => )}


`

$3

Nested components with withTimings create proper parent-child relationships:

`astro