Astro Integration
Observability across the full Astro lifecycle — SSG build metrics, SSR route tracing, API endpoint spans, island hydration monitoring, and Core Web Vitals — one integration in astro.config.mjs.
How It Works
Install the npm Package
Run npm install @tigerops/astro. The package is an Astro integration that registers a middleware for SSR request tracing, a Vite plugin for build-time metrics, and a client-side module for island hydration monitoring and Core Web Vitals.
Add to astro.config.mjs
Import tigerops from @tigerops/astro and add it to the integrations array in astro.config.mjs. The integration auto-configures the server middleware for SSR output mode and injects the browser SDK for hybrid and SSR modes via the head injection hook.
Configure API Key & Service Name
Set TIGEROPS_API_KEY and TIGEROPS_SERVICE_NAME as environment variables or pass them directly to the tigerops() integration factory. For SSG builds, only build-time metrics are collected. SSR and hybrid modes enable full request tracing.
Build Metrics, Route Traces & Island Events
TigerOps captures SSR route request spans, API endpoint traces, island component hydration timings per directive (client:load, client:idle, client:visible), SSG build duration per page, and Core Web Vitals for every page route.
What You Get Out of the Box
SSR Route Request Tracing
In SSR and hybrid output modes, every Astro page request creates a span with route pattern, rendering time, component tree depth, and response status. Astro middleware execution order and individual timing are captured as ordered child spans.
API Route Endpoint Spans
Astro API routes (src/pages/api/*.ts) are individually traced with HTTP method, route pattern, handler execution time, and response status. Request body parsing time and response serialization are captured as span attributes for debugging slow endpoints.
Island Hydration Monitoring
Each Astro island component's hydration event is tracked with the component name, hydration directive (client:load, client:idle, client:visible, client:media), hydration start time, JavaScript download duration, and time to interactive.
SSG Build Performance Metrics
During static site generation, TigerOps collects build-time metrics: pages built per second, slowest page templates, data fetch duration per getStaticPaths call, and total build time by content collection. Metrics are sent to TigerOps after each build.
Content Collection Query Tracing
Astro content collection queries (getCollection, getEntry) are traced as child spans within SSR render or SSG build spans. Schema validation time and frontmatter parsing duration are included to identify slow content pipeline stages.
Client-Side Core Web Vitals
TigerOps injects the browser SDK into every Astro page to collect LCP, CLS, INP, and TTFB. Metrics are attributed to page route paths and segmented by island count, hydration directive distribution, and total JavaScript payload size per page.
Install & Initialize
One npm install and one integration line. Full Astro observability for SSG, SSR, and hybrid modes.
# Install the TigerOps Astro integration
npm install @tigerops/astro
# Set environment variables
export TIGEROPS_API_KEY="your-api-key"
export TIGEROPS_SERVICE_NAME="my-astro-site"
// astro.config.mjs
import { defineConfig } from "astro/config";
import tigerops from "@tigerops/astro";
import node from "@astrojs/node";
export default defineConfig({
output: "hybrid",
adapter: node({ mode: "standalone" }),
integrations: [
tigerops({
apiKey: import.meta.env.TIGEROPS_API_KEY,
serviceName: "my-astro-site",
environment: import.meta.env.MODE,
islands: {
trackHydration: true,
trackDirectives: ["client:load", "client:idle", "client:visible"],
},
webVitals: true,
}),
],
});
// src/pages/api/orders/[id].ts — auto-traced API route
import type { APIRoute } from "astro";
import { tigerops } from "@tigerops/astro/server";
export const GET: APIRoute = async ({ params }) => {
return tigerops.span("order.api", async (span) => {
span.setAttribute("order.id", params.id!);
const order = await db.order.findUniqueOrThrow({
where: { id: params.id },
});
return new Response(JSON.stringify(order), {
headers: { "Content-Type": "application/json" },
});
});
};Common Questions
Which Astro versions and output modes are supported?
Astro 3.x and 4.x are fully supported. All three output modes are supported: static (build metrics only), server (full request tracing), and hybrid (per-page SSR tracing for server-rendered pages). All official Astro adapters are compatible.
How does TigerOps track island hydration for React, Vue, and Svelte islands?
The browser SDK patches the Astro island custom element to intercept hydration lifecycle events. It works regardless of the island's framework (React, Vue, Svelte, Preact, SolidJS, Lit). The framework name is captured as a span attribute alongside the hydration directive.
Does TigerOps instrument Astro DB and Starlight?
Astro DB queries (powered by Drizzle ORM on libSQL) are auto-instrumented via the Drizzle plugin. Starlight documentation sites benefit from SSR route tracing, content collection spans, and Core Web Vitals collection with no additional configuration.
How do SSG build metrics get sent to TigerOps if there is no running server?
The Vite plugin hooks into the Astro build lifecycle and sends build metrics to TigerOps via a direct OTLP HTTP POST after the build completes. The API key must be available in the build environment. CI pipelines can set it as a secret environment variable.
Does TigerOps work with Astro deployed to Vercel, Netlify, and Cloudflare?
Yes. Each adapter's runtime is supported: Node.js adapter uses the standard Node SDK, Vercel and Netlify Edge Functions use the fetch-based edge SDK, and Cloudflare Workers use the edge SDK with waitUntil() for non-blocking export.
Full Astro Observability in One Integration
SSG build metrics, SSR route traces, island hydration monitoring, and Core Web Vitals — across static, hybrid, and server output modes.