From b8925641954c009275441565ed76d3732a2def4b Mon Sep 17 00:00:00 2001
From: "angre.garcia-gomez@ait.ac.at" <angre.garcia-gomez@ait.ac.at>
Date: Tue, 14 Apr 2026 10:57:07 +0200
Subject: [PATCH] add doc

---
 docs/basic_idea.md | 66 ++++++++++++++++++++++++++++++++++++++++++++++
 docs/index.md      |  1 +
 mkdocs.yml         |  1 +
 3 files changed, 68 insertions(+)
 create mode 100644 docs/basic_idea.md

diff --git a/docs/basic_idea.md b/docs/basic_idea.md
new file mode 100644
index 0000000..f7bbad2
--- /dev/null
+++ b/docs/basic_idea.md
@@ -0,0 +1,66 @@
+# Basic Concepts
+
+DetectMateLibrary is a collection of utilities for detecting anomalies in system logs. This short tutorial explains the core concepts you need to get started.
+
+## What is a log?
+
+Logs are messages produced by logging statements in code that describe events or state during execution.
+
+Example code that produces a log:
+
+```python
+import logging
+
+var1 = "DetectMate getting started"
+var2 = "what is a log"
+
+logging.info(f"hello I am a log about {var1} and about {var2}")
+```
+
+This produces the message:
+
+```
+hello I am a log about DetectMate getting started and about what is a log
+```
+
+A log message can be split into a constant part (the template) and variable parts. For example:
+
+- Template: `hello I am a log about <*> and about <*>`
+- Variables: `["DetectMate getting started", "what is a log"]`
+
+Logs often include a prefix with metadata, for example:
+
+```
+INFO [18-05-2005] hello I am a log about DetectMate getting started and about what is a log
+```
+
+To extract the metadata we define a log format. For the example above:
+
+```
+<Level> [<Time>] <Content>
+```
+
+Using that format we can separate the message into components:
+
+- Level: `INFO`
+- Time: `18-05-2005`
+- Message: `hello I am a log about DetectMate getting started and about what is a log`
+
+## What is a parsed log?
+
+A parsed log is a log that has been decomposed into structured fields. Based on the example above:
+
+- log_format: `<Level> [<Time>] <Content>`
+- template: `hello I am a log about <*> and about <*>`
+
+A parsed log would contain fields like:
+
+| Field              | Value                                                                 |
+|--------------------|-----------------------------------------------------------------------|
+| Template           | `hello I am a log about <*> and about <*>`                            |
+| Variables          | `["DetectMate getting started", "what is a log"]`                     |
+| LogFormatVariables | `{"Level": "INFO", "Time": "18-05-2005"}`                              |
+
+Parsed logs expose structured data that downstream detection components use for anomaly detection.
+
+Go back to [Index](index.md)
diff --git a/docs/index.md b/docs/index.md
index 285e3d7..f92468a 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -16,6 +16,7 @@ List of steps to follow for new users of the library:
 
 Documentation of the different components:
 
+* [Basic concepts](basic_idea.md): basic concepts need it to understand log anomaly detection.
 * [Overall architecture](overall_architecture.md): overall architecture of the library.
 * [Schemas](schemas.md): documentation of the different schemas in the library.
 * [Parsers](parsers.md): documentation of the different parsers.
diff --git a/mkdocs.yml b/mkdocs.yml
index 5ae0b45..e8af2af 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -11,6 +11,7 @@ nav:
     - Basic usage: basic_usage.md
     - Create new component: create_components.md
   - Components:
+    - Basic concepts: basic_idea.md
     - Overall architecture: overall_architecture.md
     - Schemas: schemas.md
     - Parsers: parsers.md