From e260e8f70ddf592e23f3d344d63acc51720e7768 Mon Sep 17 00:00:00 2001 From: Markus Rudolph Date: Tue, 4 Nov 2025 18:06:32 +0100 Subject: [PATCH 1/2] Add a page Signed-off-by: Markus Rudolph --- .../docs/recipes/performance/profilers.md | 133 ++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 hugo/content/docs/recipes/performance/profilers.md diff --git a/hugo/content/docs/recipes/performance/profilers.md b/hugo/content/docs/recipes/performance/profilers.md new file mode 100644 index 00000000..a7bfc015 --- /dev/null +++ b/hugo/content/docs/recipes/performance/profilers.md @@ -0,0 +1,133 @@ +--- +title: "Profiling" +weight: 100 +--- + +Profiling is the process of measuring the performance of your application to identify bottlenecks and optimize resource usage. In this section, we will explore Langium's profiling tools and techniques that can help you analyze the performance of your parsing process. + +## Example file + +I will assume that you will be using the `Hello World` example grammar for this tutorial. Furthermore, let's say you have a file `example.hello-world` with the following content: + +```plain +person Langium +person Langium2 +person Langium3 +person Langium4 +person Langium5 +Hello LangiumWrong! +Hello Langium2! +Hello Langium3! +Hello Langium4! +Hello Langium5! +Hello Langium! +Hello Langium! +Hello Langium! +``` + +## What do we measure? + +With Langium's built-in profilers, you can measure: + +* the **parsing** process broken down by each grammar rule. Here, will see how much time was spent in each rule and how many times each rule was invoked + + ```plain + Task parsing.hello-world executed in 1.69ms and ended at 2025-11-04T16:38:53.225Z + ┌─────────┬────────────────────────┬───────┬────────┬───────────┐ + │ (index) │ Element │ Count │ Self % │ Time (ms) │ + ├─────────┼────────────────────────┼───────┼────────┼───────────┤ + │ 0 │ 'hello-world.Model​' │ 1 │ 48.54 │ 0.82 │ + │ 1 │ 'hello-world.Person​' │ 5 │ 27.92 │ 0.47 │ + │ 2 │ 'hello-world.Greeting​' │ 8 │ 20.41 │ 0.34 │ + │ 3 │ 'hello-world' │ 1 │ 3.14 │ 0.05 │ + └─────────┴────────────────────────┴───────┴────────┴───────────┘ + ``` + +* the **linking** process broken down by each cross-reference. Here, we will see how much time was spent resolving each reference and how many times each reference was resolved. + + ```plain + Task linking.hello-world executed in 0.92ms and ended at 2025-11-04T16:38:53.228Z + ┌─────────┬───────────────────────────────┬───────┬────────┬───────────┐ + │ (index) │ Element │ Count │ Self % │ Time (ms) │ + ├─────────┼───────────────────────────────┼───────┼────────┼───────────┤ + │ 0 │ 'hello-world.Greeting:person' │ 8 │ 67.22 │ 0.62 │ + │ 1 │ 'hello-world' │ 1 │ 32.78 │ 0.3 │ + └─────────┴───────────────────────────────┴───────┴────────┴───────────┘ + ``` + +* the **validation** process broken down by each grammar rule. TODO what exactly is measured here? + + ```plain + Task validating.hello-world executed in 0.19ms and ended at 2025-11-04T16:38:53.229Z + ┌─────────┬────────────────────────┬───────┬────────┬───────────┐ + │ (index) │ Element │ Count │ Self % │ Time (ms) │ + ├─────────┼────────────────────────┼───────┼────────┼───────────┤ + │ 0 │ 'hello-world.Person' │ 5 │ 60.83 │ 0.12 │ + │ 1 │ 'hello-world' │ 1 │ 17.21 │ 0.03 │ + │ 2 │ 'hello-world.Model' │ 1 │ 13.87 │ 0.03 │ + │ 3 │ 'hello-world.Greeting' │ 8 │ 8.09 │ 0.02 │ + └─────────┴────────────────────────┴───────┴────────┴───────────┘ + ``` + +## Enabling profiling + +By default, profiling is disabled in Langium to avoid unnecessary performance overhead. To enable profiling, you need to modify your Langium services configuration. Here's how you can do it inside of the `module.ts`: + +```ts +import { DeepPartial, DefaultLangiumProfiler, type Module, inject } from 'langium'; + +//... + +// override your shared services +export const HelloWorldSharedModule: Module> = { + profilers: { + LangiumProfiler: () => new DefaultLangiumProfiler() + //use () => new DefaultLangiumProfiler(new Set(['parsing', 'linking', 'validating'])) + //to enable only specific profilers + } +} + +//... +export function createHelloWorldServices(context: DefaultSharedModuleContext): { + shared: LangiumSharedServices, + HelloWorld: HelloWorldServices +} { + const shared = inject( + createDefaultSharedModule(context), + HelloWorldGeneratedSharedModule, + HelloWorldSharedModule //add this line + ); + //... +} +``` + +## Using the profiler + +Once profiling is enabled, the `LangiumProfiler` service is triggerd during the parsing, linking, and validation processes. After processing a file, the profiler will output the profiling results to the console as shown above. + +```ts +const services = createHelloWorldServices(EmptyFileSystem); +const profiler = services.shared.profilers.LangiumProfiler!; +const parse = parseHelper(services.HelloWorld); + +const result = await parse(` +person Langium +person Langium2 +person Langium3 +person Langium4 +person Langium5 +Hello LangiumWrong! +Hello Langium2! +Hello Langium3! +Hello Langium4! +Hello Langium5! +Hello Langium! +Hello Langium! +Hello Langium! +`); + +//<-- look at your console! + +// Access profiling data programmatically +profiler.getRecords("parsing").forEach(r => console.log(`Parsing record: ${r.identifier} took ${r.duration} ms`)); +``` From 7fa915ca214e4a177624ce2dfb51a44ef82e469f Mon Sep 17 00:00:00 2001 From: Markus Rudolph Date: Tue, 4 Nov 2025 18:09:36 +0100 Subject: [PATCH 2/2] Add imports and enable validation Signed-off-by: Markus Rudolph --- hugo/content/docs/recipes/performance/profilers.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/hugo/content/docs/recipes/performance/profilers.md b/hugo/content/docs/recipes/performance/profilers.md index a7bfc015..7e20886f 100644 --- a/hugo/content/docs/recipes/performance/profilers.md +++ b/hugo/content/docs/recipes/performance/profilers.md @@ -7,7 +7,7 @@ Profiling is the process of measuring the performance of your application to ide ## Example file -I will assume that you will be using the `Hello World` example grammar for this tutorial. Furthermore, let's say you have a file `example.hello-world` with the following content: +Let's assume that we will be using the `Hello World` example grammar for this recipe. Furthermore, let's say you have a file `example.hello-world` with the following content: ```plain person Langium @@ -106,6 +106,11 @@ export function createHelloWorldServices(context: DefaultSharedModuleContext): { Once profiling is enabled, the `LangiumProfiler` service is triggerd during the parsing, linking, and validation processes. After processing a file, the profiler will output the profiling results to the console as shown above. ```ts +import { EmptyFileSystem } from "langium"; +import { parseHelper } from "langium/test"; +import type { Model } from "hello-world-language"; +import { createHelloWorldServices } from "hello-world-language"; + const services = createHelloWorldServices(EmptyFileSystem); const profiler = services.shared.profilers.LangiumProfiler!; const parse = parseHelper(services.HelloWorld); @@ -124,7 +129,7 @@ Hello Langium5! Hello Langium! Hello Langium! Hello Langium! -`); +`, { validation: true }); //do not forget to enable validation! //<-- look at your console!