Filskane LogQL 🔍

Filskane LogQL is a powerful, fully integrated log analytics environment directly inside Visual Studio Code. It transforms flat .log files into a searchable database using a dedicated, SQL-inspired query language (LogQL).

Powered by an advanced ANTLR parser and a flexible Regex mapping system, this extension allows you to instantly filter lines, extract variables, and execute complex subqueries without ever leaving your code editor.

✨ Key Features

• Dedicated LogQL Language: Intuitive syntax supporting column selection, filtering, distinct values (DIST), and logical operators (AND, OR, NOT).
• Virtual Document Results: Query results instantly open in a clean, new editor tab (Virtual Document). This allows you to freely search (Ctrl+F) and navigate your results without modifying the source file.
• Subqueries: Advanced support for nested queries using the IN operator.
• Flexible Log Format (Regex): The engine can interpret almost any log structure. Choose a predefined template (Nginx, Java, Syslog) or create a custom Regular Expression.
• Smart Date Parsing: Automatic and safe ISO date recognition for precise time-frame filtering, immune to standard JavaScript parsing quirks.

🚀 Installation

Currently, the extension is distributed as a local installation package (.vsix).

1. Open Visual Studio Code.
2. Go to the Extensions view on the Activity Bar (Ctrl+Shift+X).
3. Click the three dots (...) icon in the top right corner of the Extensions panel.
4. Select "Install from VSIX..." from the dropdown menu.
5. Locate and select the generated logql-0.0.1.vsix file.
6. Done! The extension is immediately ready to use.

📖 How to Use (Step-by-Step)

Using Filskane LogQL is incredibly fast and operates entirely via the VS Code command palette.

1. Open your logs: Open any .log or raw text file containing your server logs in the active editor.
2. Launch the parser: Press Ctrl+Shift+P (or Cmd+Shift+P on Mac) to open the Command Palette and type LogQL: Run Parser.
3. Write your query: A sleek input box will appear at the top of your screen. Type your LogQL query here (e.g., FIND IP WHERE STATUS EQUALS "500").
4. Analyze the results: Hit Enter. A new "Virtual Document" tab will instantly open, displaying the neatly formatted results of your query.
5. Iterate seamlessly: Want to refine your search? Just trigger LogQL: Run Parser again while viewing the results. The extension remembers your original log file and updates the virtual tab on the fly without cluttering your workspace!

📋 Available Fields

When using the default Filskane template, the following fields are automatically parsed and ready to be used in your FIND, REJECT, or WHERE clauses:

TIME | LEVEL | MODULE | MESSAGE | STATUS | IP | USER | REQUEST | SIZE | HOST | IDENTITY

(Note: If you write a Custom Regex in the settings, the available fields will correspond to the named capture groups ?<NAME> you define).

🛠️ Configuration & Custom Logs

Filskane LogQL needs to "understand" the structure of your file. By default, the extension expects the Filskane format: [Time] [Level] [Module] Message

To change the format for your specific logs:

1. Open VS Code Settings (Ctrl + ,).
2. Search for LogQL.
3. Under LogQL Settings, choose one of the predefined templates from the dropdown list or input your own Custom Regex.

You can also configure this directly in your project's .vscode/settings.json file:

{
    "logql.logFormatRegex": "^(?<IP>[\\w\\.:]+)\\s+(?<IDENTITY>\\S+)\\s+(?<USER>\\S+)\\s+\\[(?<TIME>.*?)\\]\\s+\"(?<REQUEST>.*?)\"\\s+(?<STATUS>\\d+)\\s+(?<SIZE>\\S+)"
}

## 📝 LogQL Syntax (Cheatsheet)

### Query Examples

| Goal | LogQL Syntax |
| :--- | :--- |
| Fetch full lines of errors | `FIND * WHERE LEVEL EQUALS "ERROR"` |
| Extract specific columns | `FIND IP, HOST WHERE STATUS EQUALS "500"` |
| Reject specific data | `REJECT * WHERE LEVEL CONTAINS "DEBUG"` |
| Get unique values | `FIND DIST IP WHERE STATUS >= "500"` |
| Logical operators | `FIND * WHERE LEVEL = "ERROR" AND SIZE > "1024"` |
| Grouping conditions | `FIND IP WHERE (LEVEL == "ERROR" OR LEVEL == "WARN") AND STATUS >= "500"` |

### Supported Operators
* `EQUALS` / `=` / `==` 
* `CONTAINS` / `~=`
* `GREATER_THAN` / `>`
* `LESS_THAN` / `<`
* `GREATER_OR_EQUAL` / `>=`
* `LESS_OR_EQUAL` / `<=`

### Subqueries
You can filter logs based on the results of another query using the `IN` operator:
```logql
FIND * WHERE IP IN (FIND DIST IP WHERE STATUS EQUALS "503")

(This returns all log lines for IPs/users who encountered a 503 error at least once).

⚠️ Important Notes

• DIST Limitation: The DIST (Distinct) keyword is currently only supported with the FIND action. It cannot be combined with REJECT (e.g., executing REJECT DIST IP WHERE... will throw a syntax error).
• Data Types: Numerical comparisons (like > 500) are automatically handled as numbers under the hood. Dates should be written in standard ISO format without quotes.

⚙️ Requirements

• Visual Studio Code version ^1.110.0 or higher.