Tracing hooks for Astro

[Fryuni]

• Accepted Date: 2025-05-21
• Reference Issues/Discussions:
  • OpenTelemetry support #1128
• Author: @Fryuni (from original proposal by @KennethHoff)
• Champion(s): @Fryuni
• Implementation PR: feat: tracing events astro#13782

Summary

This proposal outlines adding a generic, low-overhead instrumentation hook system to Astro's core. These hooks will enable integrations to implement observability features, such as distributed tracing, detailed metrics and performance monitoring, without adding new dependencies to core.

Background & Motivation

As applications grow in complexity, developers need robust tools to understand performance bottlenecks and debug errors, especially in distributed environments. OpenTelemetry has emerged as the industry standard for observability, providing a unified way to collect traces, metrics, and logs. Platforms have demonstrated the value of a common interface, with many offering first-party support for ingesting OpenTelemetry data. Similary, other frameworks like Next.js have also added of first-party support for this standard in recent versions.

Discussion on Stage 1 suggested having OpenTelemetry integrated directly in Astro, but doing so would require bringing in large dependencies. Investigation on the feasibility of an @astrojs/opentelemetry integration revealed that Astro's core currently lacks the necessary instrumentation points for an integration to effectively hook into the lifecycle of a request that would be of interest, particularly for on-demand rendering.

To solve this problem in a flexible and maintainable way, this proposal advocates for adding a generic tracing/instrumentation hooks API to Astro. This approach allows any observability tool to be used via an integration, doesn't add any new dependency to core, and empowers the community to build powerful developer tooling. A first-party @astrojs/opentelemetry integration can be developed concurrently to serve as a reference implementation.

Goals

• Provide a new integration hook API for instrumenting key Astro operations (e.g., page rendering, middleware execution).
• Enable the measurement of operation durations by providing hooks that fire before and after key events, taking into account that some operations are synchronous and others asynchronous.
• Allow integrations to trace the relationship between nested operations (e.g., a page render that triggers component renders).
• Ensure the hook system has minimal performance overhead when in use, and near-zero overhead when no integration is listening.
• Define the operations that will be tracked in the new hooks.
• Define a way for integration to add code to be executed as early as possible on the server in order to not miss any events.
• Develop a first-party @astrojs/opentelemetry integration to serve as the reference implementation and provide out-of-the-box support for the most common tracing standard.

Non-Goals

• Instrumenting every possible internal Astro function. The initial implementation will focus on high-level operations critical for performance analysis, such as routing, middleware, and component rendering. Over-instrumenting would needlesly hinder modification of internal details.
• Guarantee the relationship between events. The order of operations is an internal implementation detail, although tracking their relationship will be possible, those relationship can change at any moment and should not protected by Semantic Versioning. They can be used for reporting but should not be relied on.
• Providing a specific observability backend or visualization tool. Where the data is sent to remains a responsibility of the user.
• Providing built-in support for client-side browser tracing. This can be explored in the future or handled by user-land code, this proposal is focused on on-demand server-side rendering.

[Fryuni]

For the early-code initialization, I think integrations should receive an addInitialization(moduleName: string). At the same time, if a project wants to add initialization logic directly we could support a src/initialization.ts file with the same implication.

This would match what we already have for middlewares (using addMiddleware and src/middleware.ts).

It is similar to what Next.js did for their OpenTelemetry initialization, but their file name is instrumentation.ts and only guarantees to run before their own instrumentation logic runs. Ours can run before anything of the app is initialized to fully configure the environment so it can have a more generic name.

[dvelasquez]

This sounds amazing. I'm the author of a Prometheus integration for astro and we are using it in production for high traffic site (kleinanzeigen.de).
We are hitting some limits of what is possible for a SSR implementation.

I'm actually working in a open telemetry integration following the same principles but is true, the current implementation is an approximation and having this hooks will bring better performance and clarity.

Is anything I can help with?

[Adammatthiesen]

Super interested in this... and how i could work with it when it becomes available! (esp for integrations)

[Fryuni]

This sounds amazing. I'm the author of a Prometheus integration for astro and we are using it in production for high traffic site (kleinanzeigen.de). We are hitting some limits of what is possible for a SSR implementation.

That is a great integration, congrats!

I'm actually working in a open telemetry integration following the same principles but is true, the current implementation is an approximation and having this hooks will bring better performance and clarity.

Is anything I can help with?

There are a few open points regarding the implementation on withastro/astro#13782:

• How to allow consumers of the integration to configure their own exporters (for metrics, traces and logs)
• Should we provide convenience methods for projects to instrument their own logic easier? If so, how?
• Should we enable OpenTelemetry's auto-instrumentations? Opt-in or opt-out?
• What to do during dev mode? Currently it doesn't track telemetry during development, that could be useful to debug slow rendering components but it won't really be equivalent to what happens in production.
• Are we missing any other hooks to be traced? There are multiple other points we don't track right now but we are not sure whether it would be beneficial to do so. Each extra tracking point is extra overhead for users using telemetry, but also more data to drive their decisions. OTel is low overhead but not zero.
• We are not tracking any metrics right now, should we? Everything is traced, so OTel Collector's spanmetrics processor can make metrics out of the traces.

We'll probably hold an API-bash soon (next week or two) on Discord where we have some API options for people to try out and provide feedback.

[dmgawel]

For the early-code initialization, I think integrations should receive an addInitialization(moduleName: string). At the same time, if a project wants to add initialization logic directly we could support a src/initialization.ts file with the same implication.

This could also be used outside of instrumentation use-cases, for example to run compute-heavy operation once, populate edge cache with built data on startup, load some additional data from distributed cache and make it available to pages, etc.