# [[Pathfinder LogQL tutorial]] ![[Project - Pathfinder LogQL tutorial.svg]] ## Context [[Grafana Pathfinder|Pathfinder]] is the internal name for [[Grafana Interactive Tutorials]], which is a replacement for the Help panel that recommends interactive tutorials based on where a [[Grafana Cloud]] user is. I want to create a tutorial that helps people write their first [[LogQL]] query in the Explore section. It's for both open-source and Grafana Cloud. ## How it works ### [[Grafana Recommender]] The Grafana Recommender is what determines what to show a user when. It can get as granular as showing a user a tutorial when they are typing in a particular field. By default, it just shows a documentation page but if there is an interactive tutorial, it'll show that. So it either pulls from the Grafana docs or a repo: `grafana/interactive-tutorial`. ### Creating an `unstyled.html` ### Interactive list attributes `<li class="interactive" ...>` is how Pathfinder knows to add things like the "Show me" and "Do it" buttons. `data-requirements="nav-menu"` is a way to specify something that needs to be present before the tutorial can continue. In this case, the nav menu has to be open. `data-reftarget` is where you set the CSS selector. You can also target: - form fills (to type out something) - buttons (to click) - `data-targetaction` is what you want Pathfinder to do, like `highlight` to add a little orange highlight around the element. A multi-step action does more than one thing for a user with one click. It's much more complicated. ## Steps for contributing a tutorial 1. Get access to push to [interactive tutorials](https://github.com/grafana/interactive-tutorials). 2. Clone [grafana-pathfinder-app](https://github.com/grafana/grafana-pathfinder-app) and build it. ```bash npm install && npm run build && npm run server ``` Then open Grafana at `http://localhost:3000`. This instance of Grafana will also already have the Interactive Learning plugin installed. 3. Create a new folder with your new project, like `logql-101`. Inside the folder, create a new file called `unstyled.html`. It's easier if you let your LLM of choice do this, but if you don't want to use an LLM, copy and paste the same file from one of the other projects (like `explore-drilldowns-101`) 4. Open up `index.json` and add a block in there for your project like this: ```json { "title": "Interactive Tutorial: LogQL 101 WIP", "url": "https://github.com/grafana/interactive-tutorials/tree/main/logql-101", "description": "Hands-on tutorial: Learn LogQL query language for Grafana Loki.", "type": "docs-page", "match": { "and": [ { "source": "ops.grafana-ops.net", "urlPrefix": "/explore" } ] } }, ``` - The `source` is ops.grafana-ops.net if you want to use one of the already approved datasources. - `urlPrefix` is the page on Grafana where your tutorial will be available. (Navigate to that page and click on the `?` icon.) - Another `type` is a tutorial. There's a `README` on the Recommender repo documenting all the types. 4. Modify the HTML to add steps and sections. Terminology: - *Section:* A section is a series of steps that fulfill one task. A section corresponds to a span in the HTLM. - *Multistep*: A multistep is a single step that requires multiple related actions that are dependent on the preceding actions. (For example, clicking on a down arrow and then selecting something from the resulting dropdown list). - *Step:* A step is a single concrete action that can stand on its own. It corresponds to a list item (`<li>`) in Pathfinder. ## Local development Go to the Interactive Learning plugin and then Configurations (or press the cog from the sidepanel there). Get the URL from this page and then add `?dev=true`. Hit Enter to reload the page. Scroll down on the config page and click the check box on Dev Mode on the plugins. Pathfinder will be reloaded. A DOM Selector Debug page will be added to the sidepanel. - Record mode: You can start recording, then do your demo. Then click "Export HTML" and then just modify it from there. - Tutorial tester: Get the GitHub URL (or local webserver) and put the URL there to load it. - ! You can even just ask Cursor to parse a YouTube video (getting the transcript) and turn that into an interactive tutorial! ## Next steps for Pathfinder ### Workshop mode - [[Tom Glenn]] is currently working on this. Workshop mode lets you start a "live session", outputs a QR code or URL or join session code. For attendees, it lets them choose whether to just replicate the presenter's actions exactly or try to follow along on their own. Attendees can also raise their hands! ### Open-source Will occur in Grafana 12.3 ## Objectives ### Basic LogQL tutorial for Nginx logs 1. Select data source 2. Run a query with just label selectors (`{service_name="nginx_access_log"}`) 3. Briefly go through the results 4. Expand query: another label selector + filter expression `{service_name="nginx_access_log", host="apfelstrudel"} |= "500"` 5. `!=` filter expression (HTTP status = 200) 6. Chaining filter expressions together (|= 500 and != 200) `{service_name="nginx_access_log", host="apfelstrudel"} |= "500" != "200"` 7. JSON parser: `{service_name="nginx_access_log", host="appfelstrudel"} | json | status = "500"` 8. Regular expression 9. Line format to clear up the results 10. Metrics from logs (`count_over_time`, `rate`, `sum by()`)) ### Super awesome murder mystery thing ## Resources - [[Jay Clifford]] - [[2025-09-30 Sync with Jay]] - meeting where Jay showed me how to use Pathfinder - [grafana-pathfinder-app](https://github.com/grafana/grafana-pathfinder-app) is the Pathfinder plugin repo. This contains the code for how Pathfinder itself works, not any of the tutorials - [Instructions for local dev](https://github.com/grafana/grafana-pathfinder-app/blob/main/docs/developer/LOCAL_DEV.md) - [interactive tutorials](https://github.com/grafana/interactive-tutorials) is where all the tutorials that Pathfinder pulls from are stored. - [grafana-recommender](https://github.com/grafana/grafana-recommender) is the repo for the Recommender component, which you may need to run locally if you're not using datasources already in ops. - [Pathfinder enablement session by Tom for Usman](https://drive.google.com/file/d/1zb7YXDroMRWqu2soe65y2sa255u-X5XI/view) is a video of Tom giving Usman the rundown. %% # Excalidraw Data ## Text Elements ## Drawing ```json { "type": "excalidraw", "version": 2, "source": "https://github.com/zsviczian/obsidian-excalidraw-plugin/releases/tag/2.1.4", "elements": [ { "id": "4y8R7iOA", "type": "text", "x": 118.49495565891266, "y": -333.44393157958984, "width": 3.8599853515625, "height": 24, "angle": 0, "strokeColor": "#1e1e1e", "backgroundColor": "transparent", "fillStyle": "solid", "strokeWidth": 2, "strokeStyle": "solid", "roughness": 1, "opacity": 100, "groupIds": [], "frameId": null, "roundness": null, "seed": 967149026, "version": 2, "versionNonce": 939059582, "isDeleted": true, "boundElements": null, "updated": 1713723615080, "link": null, "locked": false, "text": "", "rawText": "", "fontSize": 20, "fontFamily": 4, "textAlign": "left", "verticalAlign": "top", "containerId": null, "originalText": "", "lineHeight": 1.2 } ], "appState": { "theme": "dark", "viewBackgroundColor": "#ffffff", "currentItemStrokeColor": "#1e1e1e", "currentItemBackgroundColor": "transparent", "currentItemFillStyle": "solid", "currentItemStrokeWidth": 2, "currentItemStrokeStyle": "solid", "currentItemRoughness": 1, "currentItemOpacity": 100, "currentItemFontFamily": 4, "currentItemFontSize": 20, "currentItemTextAlign": "left", "currentItemStartArrowhead": null, "currentItemEndArrowhead": "arrow", "scrollX": 583.2388916015625, "scrollY": 573.6323852539062, "zoom": { "value": 1 }, "currentItemRoundness": "round", "gridSize": null, "gridColor": { "Bold": "#C9C9C9FF", "Regular": "#EDEDEDFF" }, "currentStrokeOptions": null, "previousGridSize": null, "frameRendering": { "enabled": true, "clip": true, "name": true, "outline": true } }, "files": {} } ``` %%