Wiki major update

updated with recent documentation
2026-01-21 19:18:39 -05:00
parent 30e0481685
commit ef55974b50
98 changed files with 32244 additions and 10 deletions
--- a/wiki/service-docs/promtail.md
+++ b/wiki/service-docs/promtail.md
@@ -0,0 +1,134 @@
+# Promtail - Log Shipper
+
+## Table of Contents
+- [Overview](#overview)
+- [What is Promtail?](#what-is-promtail)
+- [Why Use Promtail?](#why-use-promtail)
+- [Configuration in AI-Homelab](#configuration-in-ai-homelab)
+- [Official Resources](#official-resources)
+- [Docker Configuration](#docker-configuration)
+
+## Overview
+
+**Category:** Log Shipping  
+**Docker Image:** [grafana/promtail](https://hub.docker.com/r/grafana/promtail)  
+**Default Stack:** `monitoring.yml`  
+**Purpose:** Ship logs to Loki  
+**Ports:** 9080
+
+## What is Promtail?
+
+Promtail is the log shipping agent for Loki. It discovers log files, reads them, parses labels, and ships them to Loki. Think of it as the Filebeat/Fluentd equivalent for Loki.
+
+### Key Features
+- **Log Discovery:** Auto-find log files
+- **Label Extraction:** Parse labels from logs
+- **Tailing:** Follow log files
+- **Position Tracking:** Don't lose logs
+- **Multi-Tenant:** Send to multiple Loki instances
+- **Docker Integration:** Scrape container logs
+- **Pipeline Processing:** Transform logs
+- **Free & Open Source:** CNCF project
+
+## Why Use Promtail?
+
+1. **Loki Native:** Designed for Loki
+2. **Docker Aware:** Scrape container logs
+3. **Label Extraction:** Smart parsing
+4. **Reliable:** Position tracking
+5. **Efficient:** Minimal overhead
+6. **Simple:** Easy configuration
+
+## Configuration in AI-Homelab
+
+```
+/opt/stacks/monitoring/promtail/
+  promtail-config.yml    # Configuration
+  positions.yaml         # Log positions
+```
+
+## Official Resources
+
+- **Website:** https://grafana.com/docs/loki/latest/clients/promtail
+- **Documentation:** https://grafana.com/docs/loki/latest/clients/promtail
+
+## Docker Configuration
+
+```yaml
+promtail:
+  image: grafana/promtail:latest
+  container_name: promtail
+  restart: unless-stopped
+  networks:
+    - traefik-network
+  ports:
+    - "9080:9080"
+  command: -config.file=/etc/promtail/promtail-config.yml
+  volumes:
+    - /opt/stacks/monitoring/promtail/promtail-config.yml:/etc/promtail/promtail-config.yml
+    - /var/lib/docker/containers:/var/lib/docker/containers:ro
+    - /var/run/docker.sock:/var/run/docker.sock:ro
+    - /opt/stacks/monitoring/promtail/positions.yaml:/positions.yaml
+```
+
+### promtail-config.yml
+
+```yaml
+server:
+  http_listen_port: 9080
+  grpc_listen_port: 0
+
+positions:
+  filename: /positions.yaml
+
+clients:
+  - url: http://loki:3100/loki/api/v1/push
+
+scrape_configs:
+  - job_name: docker
+    docker_sd_configs:
+      - host: unix:///var/run/docker.sock
+        refresh_interval: 5s
+    relabel_configs:
+      - source_labels: ['__meta_docker_container_name']
+        regex: '/(.*)'
+        target_label: 'container'
+      - source_labels: ['__meta_docker_container_log_stream']
+        target_label: 'stream'
+    pipeline_stages:
+      - docker: {}
+```
+
+## Summary
+
+Promtail ships logs to Loki offering:
+- Docker container log collection
+- Label extraction
+- Position tracking
+- Pipeline processing
+- Loki integration
+- Free and open-source
+
+**Perfect for:**
+- Sending Docker logs to Loki
+- System log shipping
+- Application log forwarding
+- Centralized log collection
+
+**Key Points:**
+- Ships logs to Loki
+- Scrapes Docker containers
+- Tracks log positions
+- Extracts labels
+- Minimal resource usage
+- Loki's preferred agent
+
+**Remember:**
+- Mount Docker socket
+- Configure Loki URL
+- Labels parsed from containers
+- Position file prevents duplicates
+- Low overhead
+- Works seamlessly with Loki
+
+Promtail sends logs to Loki!