Skip to content

docs(runlore): refresh blog post for v0.11.0 (kb-steward, source_diff, Loki, runlore.io) #108

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Smana merged 1 commit into from
Jul 24, 2026
Merged

docs(runlore): refresh blog post for v0.11.0 (kb-steward, source_diff, Loki, runlore.io) #108

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 12 additions & 6 deletions content/en/post/series/observability/runlore/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,11 +62,15 @@ The idea is deliberately simple. An event comes in: an alert, a **GitOps** failu
The diagram breaks down into three stages:

* **Triggers** — an alert, a GitOps failure or a webhook (e.g. PagerDuty) kicks off the investigation.
* **Data sources** — the **GitOps history** (the backbone of _what-changed_), metrics, logs, network flows, the cloud… _the more you plug in, the stronger the answer_.
* **Data sources** — the **GitOps history** (the backbone of _what-changed_), metrics, logs, network flows, the cloud, and — when you allow-list them — your **application source repos**… _the more you plug in, the stronger the answer_.
* **Notification channels** — the verdict goes out to Slack, Matrix…

And all of it sits on top of a **knowledge base** that grows with every incident.

{{% notice tip "From \"the image bumped\" to the offending commit 🔍" %}}
The GitOps history tells you *a* version changed (`image v1.2.2 → v1.2.3`). Allow-list the matching **source repos** and RunLore follows that bump into the code itself — commit subjects, a per-file diffstat, the largest changed hunks — turning a correlation into a **cause**. That's the `source_diff` tool, off until you list a repo.
{{% /notice %}}

### Three design choices

Agents that investigate incidents already exist, and we'll get back to them. What sets RunLore apart comes down to three choices, and it's their **combination** that matters:
Expand Down Expand Up @@ -115,7 +119,7 @@ The idea comes from **Andrej Karpathy**: rather than re-deriving knowledge from

I was already using this pattern **locally**: first in **Obsidian**, then through **Tolaria**, the tooling I built on top of it so an agent could read and write in my knowledge base. Making it RunLore's memory felt like the natural move.

So the memory lives in a Git repo **you own**: BM25-indexed, reviewed through PRs, fully traceable. And you don't have to start from a blank page. The catalog can be **seeded** on day one (constraints, architecture, team conventions), and incidents build on it from there.
So the memory lives in a Git repo **you own**: BM25-indexed, reviewed through PRs, fully traceable. And you don't have to start from a blank page. The catalog can be **seeded** on day one (constraints, architecture, team conventions), and incidents build on it from there. And you don't have to do the interviewing by hand: **kb-steward**, a companion [Claude Code](https://runlore.io/docs/reference/kb-steward/) skill, turns runbooks and tribal knowledge into recall-grade OKF entries to seed the catalog — and later helps you **triage RunLore's KB PRs**. It never diagnoses live incidents; that stays RunLore's job.

## ✋ The human stays in charge

Expand Down Expand Up @@ -224,6 +228,8 @@ Change-oriented RCA is clearly **nothing new**: commercial tools have been compu

## 🛠️ Try it yourself

📖 Everything below — and much more — now lives in the brand-new documentation site: **[runlore.io](https://runlore.io)** (quickstart, architecture, full configuration, all searchable).

Want to try it? Installation is a **Helm chart** and a `values.yaml`. You'll need at least one **data source**, an **LLM**, a **private GitHub repo** for the knowledge base (with a dedicated GitHub App) and a **notification target**. Credentials go into a Kubernetes `Secret`; the `values.yaml` does the wiring.

```yaml
Expand All @@ -243,7 +249,7 @@ config:
metrics:
url: http://kube-prometheus-stack-prometheus.monitoring.svc:9090 # Prometheus
logs:
url: http://victoria-logs-single-server.observability.svc:9428 # VictoriaLogs
url: http://victoria-logs-single-server.observability.svc:9428 # VictoriaLogs (or Grafana Loki — auto-detected)
cloud:
provider: aws
region: eu-west-3
Expand All @@ -263,9 +269,9 @@ config:
helm install runlore deploy/helm/runlore -n runlore --create-namespace -f values.yaml
```

All that's left is to route Alertmanager to `http://runlore.runlore.svc:8080/webhook/alertmanager`, and investigations start. I'm deliberately sticking to the essentials here: the [complete getting started guide](https://github.com/Smana/runlore/blob/main/docs/getting-started.md) covers creating the GitHub App, the full `values.yaml` reference and the verification steps.
All that's left is to route Alertmanager to `http://runlore.runlore.svc:8080/webhook/alertmanager`, and investigations start. I'm deliberately sticking to the essentials here: the [complete getting started guide](https://runlore.io/docs/getting-started/) covers creating the GitHub App, the full `values.yaml` reference and the verification steps.

The example above is a standard stack, but you can plug in whatever you want: **GitOps** (Flux/Argo CD), **metrics**, **logs**, **network flows**, **cloud**, several **LLMs** and **notifiers**, each one _pluggable_. The **full matrix**, which evolves with each release, lives in the [repo's README](https://github.com/Smana/runlore#-supported-integrations).
The example above is a standard stack, but you can plug in whatever you want: **GitOps** (Flux/Argo CD), **metrics**, **logs** (VictoriaLogs or Grafana Loki), **network flows**, **cloud**, your **source repos**, several **LLMs** and **notifiers**, each one _pluggable_. The **full matrix**, which evolves with each release, lives in the [data-sources reference](https://runlore.io/docs/concepts/data-sources/).

### 🔒 Security wasn't an afterthought

Expand Down Expand Up @@ -329,7 +335,7 @@ So I'll report back after a longer run. Until then, the project is **open** (Apa

## 🔖 References

* [RunLore — GitHub repo](https://github.com/Smana/runlore) · [getting started guide](https://github.com/Smana/runlore/blob/main/docs/getting-started.md)
* [RunLore — documentation](https://runlore.io) · [GitHub repo](https://github.com/Smana/runlore) · [getting started guide](https://runlore.io/docs/getting-started/)
* [Open Knowledge Format (OKF) — Knowledge Catalog](https://github.com/GoogleCloudPlatform/knowledge-catalog)
* [Open Knowledge Format — Google Cloud announcement](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing)
* [Andrej Karpathy's _LLM-wiki_ pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)
Expand Down
18 changes: 12 additions & 6 deletions content/fr/post/series/observability/runlore/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,11 +62,15 @@ Son principe est volontairement simple : à partir d'un événement (une alerte,
Le schéma se lit en trois temps :

* **Déclencheurs** — une alerte, un échec GitOps ou un webhook (ex: PagerDuty) lancent l'investigation.
* **Sources de données** — l'**historique GitOps** (le fil rouge du _what-changed_), les métriques, les logs, les flux réseau, le cloud… _plus il y en a de branchées, plus la réponse est solide_.
* **Sources de données** — l'**historique GitOps** (le fil rouge du _what-changed_), les métriques, les logs, les flux réseau, le cloud, et — quand tu les autorises — tes **dépôts de code applicatif**… _plus il y en a de branchées, plus la réponse est solide_.
* **Canaux de notification** — le verdict part vers Slack, Matrix…

Et tout ça repose sur une **base de connaissances** qui s'enrichit à chaque incident et **évolue avec le temps**.

{{% notice tip "De « l'image a changé » au commit fautif 🔍" %}}
L'historique GitOps te dit qu'*une* version a changé (`image v1.2.2 → v1.2.3`). Autorise les **dépôts de code** correspondants et RunLore suit ce bump jusque dans le code lui-même — sujets de commits, diffstat par fichier, les plus gros hunks modifiés — transformant une corrélation en **cause**. C'est l'outil `source_diff`, désactivé tant que tu n'as pas listé de dépôt.
{{% /notice %}}

### Trois choix de conception

Des agents qui investiguent un incident, il en existe déjà (nous y reviendrons). Ce qui distingue RunLore tient en trois choix — et c'est leur **combinaison** qui compte :
Expand Down Expand Up @@ -115,7 +119,7 @@ Il vient d'une réflexion d'**Andrej Karpathy** : plutôt que de re-dériver la

J'utilisais déjà ce pattern **en local** : d'abord dans **Obsidian**, puis via **Tolaria**, l'outillage que j'ai bâti par-dessus pour qu'un agent lise et écrive dans ma base de connaissances. Il m'a donc paru naturel d'en faire la mémoire de RunLore.

La mémoire est donc stockée dans un dépôt Git **qui t'appartient** : indexé en BM25, relu par PR, avec une traçabilité complète. Et rien n'oblige à démarrer d'une page blanche : le catalogue peut être **amorcé** dès le premier jour (contraintes, architecture, conventions d'équipe), que les incidents viennent ensuite enrichir.
La mémoire est donc stockée dans un dépôt Git **qui t'appartient** : indexé en BM25, relu par PR, avec une traçabilité complète. Et rien n'oblige à démarrer d'une page blanche : le catalogue peut être **amorcé** dès le premier jour (contraintes, architecture, conventions d'équipe), que les incidents viennent ensuite enrichir. Et rien n'oblige à mener les entretiens à la main : **kb-steward**, un skill compagnon [Claude Code](https://runlore.io/docs/reference/kb-steward/), transforme runbooks et savoir tribal en entrées OKF prêtes pour le rappel afin d'amorcer le catalogue — puis t'aide à **trier les PRs KB de RunLore**. Il ne diagnostique jamais d'incident à chaud ; ça reste le travail de RunLore.

## ✋ L'humain garde la main

Expand Down Expand Up @@ -224,6 +228,8 @@ Clairement, la **RCA orientée changement n'est pas nouvelle** — des outils co

## 🛠️ Tu peux le tester simplement

📖 Tout ce qui suit — et bien plus — vit désormais sur le tout nouveau site de documentation : **[runlore.io](https://runlore.io)** (démarrage, architecture, configuration complète, le tout indexé et cherchable).

Envie de l'essayer ? L'installation tient en un **chart Helm** et un `values.yaml`. Il te faut au moins une **source de données**, un **LLM**, un **dépôt GitHub privé** pour la base de connaissances (avec une GitHub App dédiée) et une **destination de notification**. Les credentials vont dans un `Secret` Kubernetes ; le `values.yaml` fait le câblage.

```yaml
Expand All @@ -243,7 +249,7 @@ config:
metrics:
url: http://kube-prometheus-stack-prometheus.monitoring.svc:9090 # Prometheus
logs:
url: http://victoria-logs-single-server.observability.svc:9428 # VictoriaLogs
url: http://victoria-logs-single-server.observability.svc:9428 # VictoriaLogs (ou Grafana Loki — auto-détecté)
cloud:
provider: aws
region: eu-west-3
Expand All @@ -263,9 +269,9 @@ config:
helm install runlore deploy/helm/runlore -n runlore --create-namespace -f values.yaml
```

Il ne reste qu'à router les alertes d'Alertmanager vers `http://runlore.runlore.svc:8080/webhook/alertmanager`, et les investigations démarrent. Je m'en tiens volontairement à l'essentiel : le [guide de démarrage complet](https://github.com/Smana/runlore/blob/main/docs/getting-started.md) couvre la création de la GitHub App, la référence exhaustive du `values.yaml` et les étapes de vérification.
Il ne reste qu'à router les alertes d'Alertmanager vers `http://runlore.runlore.svc:8080/webhook/alertmanager`, et les investigations démarrent. Je m'en tiens volontairement à l'essentiel : le [guide de démarrage complet](https://runlore.io/docs/getting-started/) couvre la création de la GitHub App, la référence exhaustive du `values.yaml` et les étapes de vérification.

L'exemple ci-dessus est une stack standard, mais tu peux brancher ce que tu veux — **GitOps** (Flux/Argo CD), **métriques**, **logs**, **flux réseau**, **cloud**, plusieurs **LLM** et **notifieurs**, chacun _pluggable_. La **matrice complète**, qui évolue au fil des versions, vit dans le [README du dépôt](https://github.com/Smana/runlore#-supported-integrations).
L'exemple ci-dessus est une stack standard, mais tu peux brancher ce que tu veux — **GitOps** (Flux/Argo CD), **métriques**, **logs** (VictoriaLogs ou Grafana Loki), **flux réseau**, **cloud**, tes **dépôts de code**, plusieurs **LLM** et **notifieurs**, chacun _pluggable_. La **matrice complète**, qui évolue au fil des versions, vit dans la [référence des sources de données](https://runlore.io/docs/concepts/data-sources/).

### 🔒 La sécurité, une contrainte de conception

Expand Down Expand Up @@ -329,7 +335,7 @@ Je reviendrai donc avec un **retour d'expérience sur la durée**. D'ici là, le

## 🔖 Références

* [RunLore — dépôt GitHub](https://github.com/Smana/runlore) · [guide de démarrage](https://github.com/Smana/runlore/blob/main/docs/getting-started.md)
* [RunLore — documentation](https://runlore.io) · [dépôt GitHub](https://github.com/Smana/runlore) · [guide de démarrage](https://runlore.io/docs/getting-started/)
* [Open Knowledge Format (OKF) — Knowledge Catalog](https://github.com/GoogleCloudPlatform/knowledge-catalog)
* [Open Knowledge Format — annonce Google Cloud](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing)
* [Le pattern _LLM-wiki_ d'Andrej Karpathy](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)
Expand Down
Loading