slim bramble
I setup Sentry on my Astro site, and I want to profile the build process to see if I can improve the build time by finding slow functions and such.
Right now I'm able to view traces from all the pageviews etc. But I don't know how to profile the build process (before the site is finished deploying).
Right now the build time is 6 minutes, and I want to see if I can improve that
hardy sentinelBOT
Hi @slim bramble. I'm happy to dig into this for you! I'll check my internal sources for answers to your question! :wave:
To profile the build process of your Astro site using Sentry, you need to instrument the Node.js environment where the build runs, since Astro's build process is executed in Node.js. Sentry's Profiling for Node.js can capture function-level performance data, helping you identify slow parts of your build.
Install the Profiling Package
You need to install @sentry/profiling-node alongside your main Sentry SDK:
npm install @sentry/profiling-node --save
Initialize Sentry with Node Profiling in Your Build Script
In the script that runs your build (or in a wrapper script), initialize Sentry with the Node Profiling integration:
const Sentry = require("@sentry/node");
const { nodeProfilingIntegration } = require("@sentry/profiling-node");
Sentry.init({
dsn: "<https://[email protected]/0",>
integrations: [nodeProfilingIntegration()],
tracesSampleRate: 1.0,
profileSessionSampleRate: 1.0,
profileLifecycle: 'trace', // or 'manual' for manual control
});
// Now run your build logic here
trace mode, profiling will automatically start and stop with Sentry spans.manual mode, you can control exactly when profiling starts and stops using Sentry.profiler.startProfiler() and Sentry.profiler.stopProfiler().For more details and examples, see the Astro Node Profiling guide and NodeProfiling integration docs.
Wrap Your Build Process in a Span (Optional but Recommended)
To get meaningful profiling data, wrap your build process in a Sentry span:
Sentry.startSpan(
{ op: "build", name: "Astro Build Process" },
() => {
// Call your build logic here, e.g., run Astro's build command
}
);
@sentry/profiling-node matches your main Sentry SDK version.For more details, see the official documentation:
Node Profiling in Astro
NodeProfiling Integration
slim bramble
@hardy sentinel instead of require, how do I import nodeProfilingIntegration ?
hardy sentinelBOT
Let me check the knowledge base for you again. One moment! :books:
Based on the knowledge sources, here's how to import the nodeProfilingIntegration using ESM syntax instead of CommonJS require:
import * as Sentry from "@sentry/node";
import { nodeProfilingIntegration } from "@sentry/profiling-node";
Sentry.init({
integrations: [nodeProfilingIntegration()],
});
This ESM import syntax can be used in your Astro build scripts when you're using ECMAScript modules instead of CommonJS. The functionality remains the same - the nodeProfilingIntegration will set up automatic performance profiling for your Node.js application during the build process, capturing profiles via v8 and sending them to Sentry.
Remember that you'll still need to configure the profiling options as mentioned in our previous conversation:
Sentry.init({
dsn: "<https://[email protected]/0",>
integrations: [nodeProfilingIntegration()],
tracesSampleRate: 1.0,
profileSessionSampleRate: 1.0,
profileLifecycle: 'trace', // or 'manual' for manual control
});
@hardy sentinel when using a framework like Astro, how do I "Wrap Your Build Process in a Span" as you described?
hardy sentinelBOT
Let me check the knowledge base for you again. One moment! :books:
To wrap your Astro build process in a Sentry span, you'll need to create a custom build script that uses Sentry's tracing APIs. Here's how you can do it:
build-with-profiling.js or build-with-profiling.mjs) in your project:import * as Sentry from "@sentry/node";
import { nodeProfilingIntegration } from "@sentry/profiling-node";
import { exec } from "child_process";
import { promisify } from "util";
const execAsync = promisify(exec);
// Initialize Sentry with Node Profiling
Sentry.init({
dsn: "<https://[email protected]/0",>
integrations: [nodeProfilingIntegration()],
tracesSampleRate: 1.0,
profileSessionSampleRate: 1.0,
profileLifecycle: 'trace',
});
// Wrap the build process in a span
Sentry.startSpan(
{
op: "build",
name: "Astro Build Process",
},
async () => {
try {
console.log("Starting Astro build with profiling...");
// Execute the Astro build command
const { stdout, stderr } = await execAsync("npx astro build");
console.log(stdout);
if (stderr) console.error(stderr);
console.log("Build completed successfully!");
} catch (error) {
console.error("Build failed:", error);
// Capture the error in Sentry
Sentry.captureException(error);
} finally {
// Make sure to close Sentry to flush all events
await Sentry.close(2000);
}
}
);
node build-with-profiling.js
If you want to integrate more deeply with Astro's build process, you can use Astro's integration API to hook into the build lifecycle:
sentry-build-profiling.js):import * as Sentry from "@sentry/node";
import { nodeProfilingIntegration } from "@sentry/profiling-node";
let buildSpan = null;
export default function sentryBuildProfiling() {
return {
name: 'sentry-build-profiling',
hooks: {
'astro:config:setup': ({ command }) => {
// Only initialize for build command
if (command === 'build') {
Sentry.init({
dsn: "<https://[email protected]/0",>
integrations: [nodeProfilingIntegration()],
tracesSampleRate: 1.0,
profileSessionSampleRate: 1.0,
profileLifecycle: 'manual', // Using manual mode for more control
});
// Start profiling
Sentry.profiler.startProfiler();
}
},
'astro:build:start': () => {
// Start the build span when the build begins
buildSpan = Sentry.startInactiveSpan({
name: "Astro Build Process",
op: "build"
});
},
'astro:build:done': async () => {
// End the build span when the build is complete
if (buildSpan) {
buildSpan.end();
}
// Stop profiling
Sentry.profiler.stopProfiler();
// Flush events to Sentry
await Sentry.close(2000);
}
}
};
}
astro.config.mjs:import { defineConfig } from "astro/config";
import sentryAstro from "@sentry/astro";
import sentryBuildProfiling from "./sentry-build-profiling.js";
export default defineConfig({
integrations: [
sentryAstro({
// Your regular Sentry config
}),
sentryBuildProfiling()
],
});
This approach leverages Astro's integration API and hooks into the build lifecycle, giving you more precise control over when profiling starts and stops.
After running your build with either approach, you should see the build process profiling data in your Sentry dashboard, which will help you identify performance bottlenecks in your build.
slim bramble
@hardy sentinel what if I have a [slug].astro file that generates thousands of static pages, and I want to trace that instead of the entire build script?
hardy sentinelBOT
Let me check the knowledge base for you again. One moment! :books:
I understand you want to profile specifically the static page generation process for your [slug].astro file that generates thousands of pages, rather than the entire build process.
You can target this specific part of your build by using Sentry's custom instrumentation within your [slug].astro file or in the code that handles the static generation. Here's how you can approach this:
getStaticPaths() functionIn Astro, the getStaticPaths() function is responsible for generating static routes. You can wrap this function with Sentry tracing:
import * as Sentry from "@sentry/node";
export async function getStaticPaths() {
return Sentry.startSpan(
{
op: "astro.static-generation",
name: "[slug].astro Static Generation",
},
async () => {
// Your existing getStaticPaths logic here
const allPosts = await fetchAllPosts(); // Your data fetching
// Create a child span for data processing if needed
return Sentry.startSpan(
{
op: "data.processing",
name: "Process Post Data"
},
() => {
return allPosts.map(post => ({
params: { slug: post.slug },
props: { post }
}));
}
);
}
);
}
You can create a more targeted integration that specifically instruments your slug file:
import * as Sentry from "@sentry/node";
import { nodeProfilingIntegration } from "@sentry/profiling-node";
import path from "path";export default function sentrySlugProfiling() {
let slugGenSpan = null;
return {
name: 'sentry-slug-profiling',
hooks: {
'astro:build:setup': () => {
Sentry.init({
dsn: "https://[email protected]/0",
integrations: [nodeProfilingIntegration()],
tracesSampleRate: 1.0,
profileSessionSampleRate: 1.0,
profileLifecycle: 'trace',
});
},
'astro:build:generated': ({ buildConfig, pages }) => {
// Check if our slug pages were generated
const slugPages = pages.filter(page =>
page.pathname.startsWith('/your-slug-path-pattern/'));
if (slugPages.length > 0) {
// Create a transaction for the slug generation
const transaction = Sentry.startTransaction({
name: "[slug].astro Page Generation",
op: "build.static-generation"
});
// Add useful metadata
transaction.setTag("pages.count", slugPages.length);
transaction.setData("pages.list", slugPages.map(p => p.pathname));
// End the transaction
transaction.finish();
}
}
}
};
}
### Option 3: Manual instrumentation in your data fetching code
If your `[slug].astro` file calls external functions to fetch or process data, you can instrument those directly:
```javascript
// In your data fetching module
import * as Sentry from "@sentry/node";export async function fetchAllPostsForStaticGeneration() {
return Sentry.startSpan(
{
op: "data.fetch",
name: "Fetch Posts for Static Generation",
},
async () => {
// Your data fetching logic
const posts = await database.getPosts();
// You can add metrics to see exactly how many items you're processing
Sentry.metrics.distribution(
"static_generation.items_count",
posts.length,
{ unit: "item" }
);
return posts;
}
);
}
### Viewing the Results
After implementing one of these approaches and running your build, you'll be able to see the specific spans and transactions in your Sentry dashboard. Look for:
1. The performance tab to see transaction durations
2. Flame charts in the profiling section to identify slow functions
3. Spans breakdown to understand which parts of your static generation are taking the most time
This targeted approach will give you much more specific insights into the performance bottlenecks in your `[slug].astro` file's static generation process, rather than the entire build.
For more information on custom instrumentation in Astro, see the [Custom Instrumentation documentation](<https://docs.sentry.io/platforms/javascript/guides/astro/tracing/#custom-instrumentation>).
----------------------
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
----------------------@hardy sentinel earlier you suggest a build script called build-with-profiling.js
How do I add my authToken there?
hardy sentinelBOT
Let me check the knowledge base for you again. One moment! :books:
To add your Sentry authentication token to the build-with-profiling.js script, you have several options. Here's how you can include your auth token in the script:
import * as Sentry from "@sentry/node";
import { nodeProfilingIntegration } from "@sentry/profiling-node";
import { exec } from "child_process";
import { promisify } from "util";
const execAsync = promisify(exec);
// Initialize Sentry with Node Profiling
Sentry.init({
dsn: "<https://[email protected]/0",>
integrations: [nodeProfilingIntegration()],
tracesSampleRate: 1.0,
profileSessionSampleRate: 1.0,
profileLifecycle: 'trace',
// Auth token is not needed here for profiling
});
// Wrap the build process in a span
Sentry.startSpan(
{
op: "build",
name: "Astro Build Process",
},
async () => {
try {
console.log("Starting Astro build with profiling...");
// Execute the Astro build command with the auth token passed as an environment variable
const { stdout, stderr } = await execAsync("SENTRY_AUTH_TOKEN=your_auth_token_here npx astro build");
console.log(stdout);
if (stderr) console.error(stderr);
console.log("Build completed successfully!");
} catch (error) {
console.error("Build failed:", error);
Sentry.captureException(error);
} finally {
await Sentry.close(2000);
}
}
);
.env.sentry-build-plugin file in your project root:SENTRY_AUTH_TOKEN=your_auth_token_here
import * as Sentry from "@sentry/node";
import { nodeProfilingIntegration } from "@sentry/profiling-node";
import { exec } from "child_process";
import { promisify } from "util";
import dotenv from "dotenv";// Load environment variables from .env.sentry-build-plugin
dotenv.config({ path: '.env.sentry-build-plugin' });
const execAsync = promisify(exec);
// Rest of your script remains the same
// ...
### Option 3: Pass the Auth Token in Your astro.config.mjs
If you're already using the Sentry Astro integration, you can configure the auth token there and it will be used during the build:
```javascript
// astro.config.mjs
import { defineConfig } from "astro/config";
import sentry from "@sentry/astro";
export default defineConfig({
integrations: [
sentry({
sourceMapsUploadOptions: {
project: "example-project",
org: "example-org",
authToken: process.env.SENTRY_AUTH_TOKEN,
},
}),
],
});
Then your build script doesn't need to handle the auth token separately.
As mentioned in the Sentry documentation, you should never commit your auth token directly to your code repository. The Next.js manual setup guide specifically states:
Make sure to keep your auth token secret and out of version control.
Instead, use environment variables or secure environment variable management in your CI/CD system.
slim bramble
@hardy sentinel when I run the script I get this error:
Build failed: RangeError [ERR_CHILD_PROCESS_STDIO_MAXBUFFER]: stdout maxBuffer length exceeded
hardy sentinelBOT
Let me check the knowledge base for you again. One moment! :books:
I see you're encountering a stdout maxBuffer length exceeded error when running your build script with Sentry profiling. This is a common Node.js error that occurs when the output from a child process exceeds the default buffer size.
This issue has been reported by other Sentry users as well. Based on the knowledge sources, here's how to fix it:
You need to modify your build-with-profiling.js script to increase the maxBuffer parameter in the exec function:
import * as Sentry from "@sentry/node";
import { nodeProfilingIntegration } from "@sentry/profiling-node";
import { exec } from "child_process";
import { promisify } from "util";
const execAsync = promisify(exec);
// Initialize Sentry with Node Profiling
Sentry.init({
dsn: "<https://[email protected]/0",>
integrations: [nodeProfilingIntegration()],
tracesSampleRate: 1.0,
profileSessionSampleRate: 1.0,
profileLifecycle: 'trace',
});
// Wrap the build process in a span
Sentry.startSpan(
{
op: "build",
name: "Astro Build Process",
},
async () => {
try {
console.log("Starting Astro build with profiling...");
// Execute the Astro build command with increased maxBuffer
const { stdout, stderr } = await execAsync("npx astro build", {
maxBuffer: 1024 * 1024 * 10 // 10MB buffer instead of the default 1MB
});
console.log(stdout);
if (stderr) console.error(stderr);
console.log("Build completed successfully!");
} catch (error) {
console.error("Build failed:", error);
// Capture the error in Sentry
Sentry.captureException(error);
} finally {
// Make sure to close Sentry to flush all events
await Sentry.close(2000);
}
}
);
If you're still experiencing issues, you might also need to increase the Node.js memory limit. According to user reports in the JavaScript Bundler Plugins issue #565, increasing the Node.js memory limit helped resolve similar issues:
// Add this to your script
process.env.NODE_OPTIONS = "--max_old_space_size=4096"; // Increase to 4GB
// Or run your script with the environment variable
// NODE_OPTIONS="--max_old_space_size=4096" node build-with-profiling.js
This error typically occurs when:
slim bramble
@hardy sentinel it's working now but where do I find the data? the Profiles section is empty
hardy sentinelBOT
Let me check the knowledge base for you again. One moment! :books:
I'm glad to hear your build script is working now! If you're not seeing any data in the Profiles section of Sentry, there are several troubleshooting steps you can take based on common issues with Sentry profiling.
Here are the most common reasons why profiling data might not appear and how to fix them:
Ensure Tracing is Enabled
tracesSampleRate is set to a value greater than 0 (ideally 1.0 for testing)Verify Performance Data is Being Sent
Enable Debug Mode
Sentry.init({
debug: true,
// your other settings
});
Check for SDK Errors
Verify Profile Sample Rate
profileSessionSampleRate is set to a value greater than 0 (ideally 1.0 for testing)tracesSampleRate * profilesSampleRateCheck for Container Issues (Self-Hosted Only)
According to the troubleshooting documentation for various platforms, these are the most common issues when profiling data doesn't appear.
For Node.js profiling specifically:
Verify the Profiling Integration
nodeProfilingIntegration() and not browserProfilingIntegration()@sentry/profiling-node is properly installed and importedCheck Lifecycle Mode
profileLifecycle: 'trace', ensure your spans are properly created and closedprofileLifecycle: 'manual', verify that startProfiler() and stopProfiler() are calledWait for Data Processing
await Sentry.close(2000) to flush all eventsIf you've verified all these steps and still don't see data, try running a simple test script with profiling to isolate whether the issue is with your build script or with the profiling setup in general.
Let me know if any of these steps help or if you need more specific guidance!
Let me check the knowledge base for you again. One moment! :books:
slim bramble
@hardy sentinel I'm using this:
Sentry.init({
dsn: "hidden for privacy",
tracesSampleRate: 1.0,
integrations: [nodeProfilingIntegration()],
profileSessionSampleRate: 1.0,
profileLifecycle: "trace",
});
It's working cause in the Aggregate Flamegraph I see the profiles. But I don't know how to analyze them
hardy sentinelBOT
Let me check the knowledge base for you again. One moment! :books:
I'm glad to hear you're successfully collecting profiling data with Sentry! Let me explain how to analyze the flame graphs to identify performance bottlenecks in your Astro build process.
Flame graphs in Sentry represent your code's execution, with each rectangle showing a function call:
Flame Graphs and Aggregated Flame Graphs
Look for wide rectangles: These represent functions that consume the most time
Use the color coding options: Click on "Color Coding" to change how frames are colored:
Use the search functionality: Search for specific function names if you have suspicions about what might be slow
Click on frames: When you click on a frame, the sidebar will show details about that function and links to example profiles containing it
Look at the "Slowest Functions" widget: This shows functions consuming the most self-time (time spent in the function itself, excluding child functions)
Start with the "Slowest Functions" widget: This immediately shows you which functions are taking the most time
Examine the "Most Regressed Functions": If you've made changes to your build process, this shows which functions have gotten slower
In the flame graph:
Use the thread selector: If your application is multi-threaded, examine different threads to see where time is being spent
As described in a Sentry blog post about optimizing code:
Tame the performance of code you didn't write
For your Astro build specifically, look for functions related to file processing, template rendering, or data fetching that might be taking excessive time.
I'm glad to hear you're successfully collecting profiling data with Sentry! Let me help you understand how to analyze the flame graphs to identify performance bottlenecks in your Astro build process.
The Aggregate Flame Graph shows you the most frequent code paths across all your profiles. Here's how to interpret and analyze it:
Frame Width: The wider a frame (rectangle) is, the more frequently that function appears in your profiles. Focus on the widest frames first as they represent the most common performance bottlenecks Flame Graphs and Aggregated Flame Graphs.
Frame Color: By default, system functions are colored red, and application functions are blue. You have more control over slow blue (application) frames than red (system) frames Flame Graphs and Aggregated Flame Graphs.
Navigation: Use the search bar to find specific functions. You can also use the minimap to navigate through large flame graphs Profile Details.
Identify Regressions: The "Most Regressed Functions" widget shows functions that have slowed down over time Profiling to Speed Up Your Apps.
Drill Down: Click on a frame in the flame graph to see more details about that function, including its self-time and total time Profile Details.
Change Visualization: Try different color coding options (by system vs. application frame, by symbol name, by package, etc.) to get different insights Profile Details.
Sort Options: Change the sorting from the default "Call Order" to "Left Heavy" to group similar functions together, making it easier to spot patterns Profile Details.
Identify Hot Paths: Look for the tallest and widest stacks in your flame graph - these represent the most time-consuming code paths.
Focus on Application Code: Pay special attention to your own application code (blue frames) rather than system/library code (red frames), as these are areas you can optimize.
Look for Patterns: If you see repeated patterns of slow functions, this might indicate a systemic issue that could be optimized.
Check for I/O Operations: Functions that perform file I/O, network requests, or database operations are common bottlenecks in build processes.
As described in the Tame the Performance blog post, the general approach is:
For your Astro build process specifically, look for functions related to file processing, image optimization, or data fetching that might be slowing down your build.