OpenTelemetry support

[KennethHoff]

Summary

Modern websites needs telemetry to be able to understand what's going on, and there is no way of doing that than OpenTelemetry.

I realize that AstroJS is a Static Site Generator and it's the adapters' job to implement the runtime portions, but in order to make it easier for them to implement, an abstraction is needed, and OpenTelemetry is actually surprisingly useful even in local development, as it makes it trivial to determine performance bottlenecks due to duration-tracking functionality of Spans.

Background & Motivation

Distributed tracing makes it makes it very easy to figure out performance bottlenecks as well make it easier to figure out where errors are coming from, and OpenTelemetry (Otel) is a standard for Distributed Tracing.

Next.js has very good built-in support for OpenTelemetry through the @vercel/otel package.

Goals

• Create a new integration, @astrojs/opentelemetry that enables OpenTelemetry in an Astro application.
• Add some built-in instruments, like requests per minute, average request duration, page visits, and similar.

Example

Create a new integration, @astrojs/opentelemetry that can be used like this:

// astro.config.mjs
import opentelemetry from "@astrojs/opentelemetry";

export default defineConfig({
    ...,
    integrations: [opentelemetry()]
})

The opentelemetry function would allow you to configure these options, which would default to reading these environment variables

[delucis]

Thanks for the idea @KennethHoff! Do you think this would be do-able also as a third-party integration or are changes to Astro’s core required?

I’m not familiar but looking quickly through the OpenTelemetry docs it looks like something a community member could kick off using the integration API.

[KennethHoff]

I know little about Astro's Core, Astro Integrations or how they interact, and I have very shallow knowledge on what the OTel SDK mandates or how it should be implemented. What I do know however is that the OTel SDK is weirdly in-depth - one could say needlessly rigid - when it comes to defining how one should implement it.

All that's to say, I don't know 😅

I could imagine that adding support for custom spans and logs could reasonably easily be implemented third-party, but the built-in instruments could necessitate changes to core ( again, no idea how extensive the Integrations API is). Simple things like Page visits and request duration could conceivably be implemented as middleware, but I imagine that if it was a built-in feature it could allow for potentially more useful information being recorded.

An example of such instruments could be "content collection retrievals"; an instrument that records queries into a content collection (which ID was queried from, what was returned, etc). I don't know how useful that is, but it's a very obvious example.

[ascorbic]

I've had a bit of a think about this, and done a bit of research. I think it couldn't be done using an integration, and would need to be in Astro core. Essentially Astro would need to use the @opentelemetry/api package to instrument on-demand rendering, and provide a way to load an instrumentation.ts bootstrap file. Tracing would be noop by default, and users would need to set up and register their own otel instance, with the collectors that they need. If deploying to Vercel they could use @vercel/otel, for example, or they can set it up for whichever collector they're using.

[delucis]

Interesting! Do you think it could be possible to add some additional generic integration hooks and then still have the actual implementation in an integration that uses those? Wondering if there could be other use cases beyond OpenTelemetry that could need similar lifecycle integration.

[ascorbic]

We would like to advance this to stage 2, so I'm calling for a @withastro/tsc vote. 👍🏻 from me

[florian-lefebvre]

I'm in favor of moving this to stage 2, with updated goals by @Fryuni

[ascorbic]

@matthewp No, this is @Fryuni

[ematipico]

I'm happy to move this to Stage 2

[matthewp]

Ok great, a core team member championing is +1 for moving to stage 2 from me.

[Fryuni]

Took waaaay too long, but I opened stage 2: #1208

[ematipico]

Closing in favour of #1208