docs: add example logs and expand custom formats guide

Author: code-with-auto

docs/guide/custom-formats.md

@@ -353,6 +353,228 @@ describe('myformat parser', () => {
 4. Run tests: `bun test`
 5. Push and open a PR
 
+## Step-by-Step Example: Parsing Unstructured Logs
+
+Let's walk through creating a parser for a common unstructured log format:
+
+```
+2025-01-15 08:00:35 ERROR [payment] Failed to process payment for order #12345
+2025-01-15 08:00:40 DEBUG [scheduler] Running job: cleanup_sessions
+2025-01-15 08:00:45 WARN  [memory] Heap usage high: 1.5GB / 2GB (75%)
+```
+
+### Step 1: Analyze the Format
+
+Break down the log structure:
+- `2025-01-15 08:00:35` - timestamp (YYYY-MM-DD HH:MM:SS)
+- `ERROR` - log level (DEBUG, INFO, WARN, ERROR, FATAL)
+- `[payment]` - component name in brackets
+- `Failed to process...` - the message
+
+### Step 2: Write the Detection Pattern
+
+The detection pattern should match uniquely to avoid false positives:
+
+```typescript
+// Matches: date + time + level keyword
+detect: /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2} (DEBUG|INFO|WARN|ERROR|FATAL)/
+```
+
+### Step 3: Write the Parse Pattern
+
+Use named capture groups for clarity:
+
+```typescript
+parse: {
+  pattern: /^(?<timestamp>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}) (?<level>\w+)\s+\[(?<component>[^\]]+)\] (?<message>.+)$/,
+  fields: {
+    timestamp: 'timestamp',
+    level: 'level',
+    message: 'message',
+  },
+}
+```
+
+### Step 4: Complete Config
+
+```typescript
+// loq.config.ts
+export default {
+  formats: [
+    {
+      name: 'myapp',
+      detect: /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2} (DEBUG|INFO|WARN|ERROR|FATAL)/,
+      parse: {
+        pattern: /^(?<timestamp>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}) (?<level>\w+)\s+\[(?<component>[^\]]+)\] (?<message>.+)$/,
+        fields: {
+          timestamp: 'timestamp',
+          level: 'level',
+          message: 'message',
+        },
+      },
+    },
+  ],
+};
+```
+
+### Step 5: Test It
+
+```bash
+# Now these queries work!
+loq plain.log where level=error
+loq plain.log where component=payment
+loq plain.log where level=error and component=database
+loq plain.log count by level
+loq plain.log count by component
+```
+
+### Step 6: Add the Component Field
+
+To query by component, add it to the fields:
+
+```typescript
+parse: {
+  pattern: /^(?<timestamp>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}) (?<level>\w+)\s+\[(?<component>[^\]]+)\] (?<message>.+)$/,
+  fields: {
+    timestamp: 'timestamp',
+    level: 'level',
+    message: 'message',
+    component: 'component',  // Add this!
+  },
+}
+```
+
+---
+
+## More Real-World Examples
+
+### Kubernetes Pod Logs
+
+```typescript
+{
+  name: 'k8s',
+  detect: /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d+Z\s/,
+  parse: {
+    pattern: /^(?<timestamp>\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d+Z)\s+(?<level>\w+)\s+(?<message>.+)$/,
+    fields: {
+      timestamp: 'timestamp',
+      level: 'level',
+      message: 'message',
+    },
+  },
+}
+```
+
+### Python Logging
+
+```typescript
+{
+  name: 'python',
+  detect: /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2},\d{3} - \w+ -/,
+  parse: {
+    pattern: /^(?<timestamp>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2},\d{3}) - (?<logger>\w+) - (?<level>\w+) - (?<message>.+)$/,
+    fields: {
+      timestamp: 'timestamp',
+      level: 'level',
+      message: 'message',
+      logger: 'logger',
+    },
+  },
+}
+```
+
+### Java/Log4j
+
+```typescript
+{
+  name: 'log4j',
+  detect: /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3} \[/,
+  parse: {
+    pattern: /^(?<timestamp>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3}) \[(?<thread>[^\]]+)\] (?<level>\w+)\s+(?<logger>\S+) - (?<message>.+)$/,
+    fields: {
+      timestamp: 'timestamp',
+      level: 'level',
+      message: 'message',
+      thread: 'thread',
+      logger: 'logger',
+    },
+  },
+}
+```
+
+### Go/Zap Logger (Non-JSON)
+
+```typescript
+{
+  name: 'zap',
+  detect: /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}[+-]\d{4}\s+(DEBUG|INFO|WARN|ERROR)/,
+  parse: {
+    pattern: /^(?<timestamp>\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}[+-]\d{4})\s+(?<level>\w+)\s+(?<logger>\S+)\s+(?<message>[^\t]+)(?:\t(?<fields>.+))?$/,
+    fields: {
+      timestamp: 'timestamp',
+      level: 'level',
+      message: 'message',
+      logger: 'logger',
+    },
+  },
+}
+```
+
+### Heroku Router Logs
+
+```typescript
+{
+  name: 'heroku',
+  detect: /^.*heroku\[router\]:/,
+  parse: (line) => {
+    const match = line.match(/^(?<timestamp>\S+) .*heroku\[router\]: at=(?<status>\w+) method=(?<method>\w+) path="(?<path>[^"]+)".*status=(?<code>\d+).*connect=(?<connect>\d+)ms service=(?<service>\d+)ms/);
+    if (!match) return null;
+    const { timestamp, status, method, path, code, connect, service } = match.groups!;
+    return {
+      timestamp,
+      level: status === 'error' ? 'error' : (parseInt(code) >= 400 ? 'warn' : 'info'),
+      message: `${method} ${path} ${code}`,
+      fields: {
+        method,
+        path,
+        status: parseInt(code),
+        connect_ms: parseInt(connect),
+        service_ms: parseInt(service),
+      },
+    };
+  },
+}
+```
+
+### Multiline Stack Traces
+
+For logs with stack traces, you may need special handling:
+
+```typescript
+{
+  name: 'java-multiline',
+  detect: /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3}/,
+  parse: (line) => {
+    // Skip continuation lines (stack traces)
+    if (line.startsWith('\t') || line.startsWith('    at ')) {
+      return null;  // These get attached to previous entry
+    }
+
+    const match = line.match(/^(?<timestamp>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3}) (?<level>\w+) (?<message>.+)$/);
+    if (!match) return null;
+
+    return {
+      timestamp: match.groups!.timestamp,
+      level: match.groups!.level.toLowerCase(),
+      message: match.groups!.message,
+      fields: {},
+    };
+  },
+}
+```
+
+---
+
 ## Debugging Custom Formats
 
 Test your format detection: