Accepted Date: 2025-05-21 Reference Issues/Discussions: https://github.com/withastro/roadmap/discussions/1128 Author: @Fryuni (from original proposal by @KennethHoff) Champion(s): @Fryuni Implementation PR: https://github.com/withastro/astro/pull/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 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 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 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.