logger/README.md

# Package logger

**Flexible logging system with multiple handlers and log levels**  
*MIT License*

---

## What is this?

`logger` is a **demonstration package** that showcases how to build a structured logging system for MetaTrader 5 using KnitPkg.

It provides:

- `Logger` class for centralized log management
- `LoggerInterface` for custom handler implementations
- Built-in handlers: `PrintLogger` (terminal output) and `FileLogger` (file output)
- Multiple log levels: DEBUG, INFO, WARN, ERROR
- Support for both structured logging (event + fields) and simple message logging

This project is intended **only as an educational example** of how to structure, package, and compile **MQL5** code with KnitPkg. It is **not** meant to be a production-grade library for large-scale use.

## Prerequisites

To use this project, you will need:

1.  [**MetaTrader 5**](https://www.mql5.com/) installed.
2.  **KnitPkg CLI**: The KnitPkg package manager for MetaTrader. If you don't have it, you can install it by following the instructions in the [main KnitPkg repository](https://github.com/knitpkg-dev/knitpkg-mt.git).
3.  **KnitPkg homepage**: See [https://knitpkg.dev](https://knitpkg.dev) for an overview and [https://docs.knitpkg.dev](https://docs.knitpkg.dev) for documentation.

---

## Features

- **Package type** (`type: package`) — header-only library consumable by other KnitPkg projects
- **MQL5 target** — designed for MetaTrader 5
- **Compile support** — `kp compile` compiles the unit test script(s)
- **Multiple handlers** — send logs to terminal, files, or implement custom handlers
- **Log levels** — filter messages by severity (DEBUG, INFO, WARN, ERROR)
- **Flexible formats** — log simple messages or structured event + fields
- **File logging** — with optional auto-flush and append modes

---

## Installing as a dependency (recommended)

To add `logger` to your KnitPkg project:

```bash
kp add @douglasrechia/logger
```

---

## Basic usage (example)

In the case your MQL5 project uses `include_mode: include`, include headers from the KnitPkg include directory:

```mql5
//--- Manifest declares include_mode: include
#include "../knitpkg/include/douglasrechia/logger/Logger.mqh"
#include "../knitpkg/include/douglasrechia/logger/handlers/PrintLogger.mqh"
#include "../knitpkg/include/douglasrechia/logger/handlers/FileLogger.mqh"

// Create logger with source identifier and minimum log level
douglasrechia::Logger logger("MyExpert", douglasrechia::LOG_LEVEL_INFO);

int OnInit()
  {
//---
// Add handlers
   logger.AddHandler(new douglasrechia::PrintLogger());
   logger.AddHandler(new douglasrechia::FileLogger("logs/myexpert.log", true, true));
//---
   return(INIT_SUCCEEDED);
  }

void OnTick()
  {
//---
// Simple message logging
   logger.Info("Application started");
   logger.Warn("Low memory detected");
   logger.Error("Connection failed");

// Structured logging with event + fields
   logger.Info("order_placed", "symbol=EURUSD | lot=0.1 | price=1.0850");
   logger.Error("order_failed", "symbol=GBPUSD | error=130");
  }
```

### Available headers

- `Logger.mqh` — Main logger class
- `LoggerInterface.mqh` — Base interface for custom handlers
- `LogRecord.mqh` — Log record structure and log levels
- `handlers/PrintLogger.mqh` — Terminal output handler
- `handlers/FileLogger.mqh` — File output handler

---

## Exploring the project locally (optional)

If you want to explore how a KnitPkg package is structured, clone the repository and run the standard workflow.

### 1) Clone into MetaTrader `Scripts` folder (example)

```bash
# Go to your MetaTrader 'Scripts' directory.
# Tip: in MetaEditor, right-click the `Scripts` folder and choose "Open Folder".
cd "C:\Users\username\AppData\Roaming\MetaQuotes\Terminal\<TERMINAL_ID>\MQL5\Scripts"

git clone https://forge.mql5.io/DouglasRechia/logger.git
cd logger
```

### 2) Compile

```bash
kp compile
```

---

## Running unit tests

Unit tests are implemented as a MetaTrader **Script**.

1. Compile the project.
2. Restart MetaTrader (so the Navigator refreshes).
3. Run the generated unit test script from the Navigator on any chart.
4. Check results in the MetaTrader console (Experts/Scripts tab, depending on your setup).

The compiled binary is placed under the project `bin/` directory (and appears in the Navigator under the corresponding compiled location after refresh).

The unit tests verify:
- Log level filtering (DEBUG, INFO, WARN, ERROR)
- Both message and structured logging formats
- File output correctness

---

## One-command download/build via the registry (optional)

You can also use `kp get` to query the registry for metadata and automatically download/build the latest stable version.

Example (run from your MetaTrader *Data Folder* root):

```bash
cd "C:\Users\username\AppData\Roaming\MetaQuotes\Terminal\<TERMINAL_ID>"

kp get mql5 @douglasrechia/logger
```

Restart MetaTrader afterward to refresh the Navigator, then run the unit test script as described above.

---

## License

This project is released under the **MIT License**. See `LICENSE` for details.

---

## Disclaimer

This code is provided **as-is**, for **educational purposes only**.  
No warranty (express or implied) is provided. Use at your own risk.