container-superposition 0.1.1

package/overlays/prometheus/devcontainer.patch.json

@@ -0,0 +1,12 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "runServices": ["prometheus"],
+    "_serviceOrder": 1,
+    "forwardPorts": [9090],
+    "portsAttributes": {
+        "9090": {
+            "label": "Prometheus",
+            "onAutoForward": "openBrowser"
+        }
+    }
+}

package/overlays/prometheus/docker-compose.yml

@@ -0,0 +1,22 @@
+version: '3.8'
+services:
+    prometheus:
+        image: prom/prometheus:${PROMETHEUS_VERSION:-latest}
+        command:
+            - '--config.file=/etc/prometheus/prometheus.yml'
+            - '--storage.tsdb.path=/prometheus'
+            - '--web.console.libraries=/usr/share/prometheus/console_libraries'
+            - '--web.console.templates=/usr/share/prometheus/consoles'
+        volumes:
+            - ./prometheus-prometheus.yml:/etc/prometheus/prometheus.yml
+            - prometheus_data:/prometheus
+        ports:
+            - '${PROMETHEUS_PORT:-9090}:9090'
+        networks:
+            - devnet
+
+volumes:
+    prometheus_data:
+
+networks:
+    devnet:

package/overlays/prometheus/overlay.yml

@@ -0,0 +1,17 @@
+id: prometheus
+name: Prometheus
+description: Metrics collection and monitoring
+category: observability
+supports:
+    - compose
+requires: []
+suggests:
+    - alertmanager
+conflicts: []
+tags:
+    - observability
+    - metrics
+    - prometheus
+ports:
+    - 9090
+order: 1

package/overlays/prometheus/prometheus.yml

@@ -0,0 +1,12 @@
+global:
+    scrape_interval: 15s
+    evaluation_interval: 15s
+
+scrape_configs:
+    - job_name: 'prometheus'
+      static_configs:
+          - targets: ['localhost:9090']
+
+    - job_name: 'otel-collector'
+      static_configs:
+          - targets: ['otel-collector:8889']

package/overlays/prometheus/verify.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+# Verification script for Prometheus overlay
+# Confirms Prometheus service is accessible
+
+set -e
+
+echo "🔍 Verifying Prometheus overlay..."
+echo ""
+
+# Check if Prometheus service is running
+echo "1️⃣ Checking Prometheus service..."
+# Wait up to 15 seconds for prometheus to be ready
+PROMETHEUS_READY=false
+for i in {1..15}; do
+    if curl -sf http://prometheus:9090/-/healthy &> /dev/null; then
+        echo "   ✅ Prometheus service is ready"
+        curl -s http://prometheus:9090/-/healthy
+        PROMETHEUS_READY=true
+        break
+    fi
+    sleep 1
+done
+
+if [ "$PROMETHEUS_READY" = false ]; then
+    echo "   ❌ Prometheus service not ready after 15 seconds"
+    exit 1
+fi
+
+echo ""
+echo "2️⃣ Checking Prometheus version..."
+echo "   Prometheus is accessible at http://prometheus:9090"
+
+echo ""
+echo "✅ Prometheus overlay verification complete"

package/overlays/promtail/.env.example

@@ -0,0 +1,2 @@
+# Promtail version
+PROMTAIL_VERSION=latest

package/overlays/promtail/README.md

@@ -0,0 +1,357 @@
+# Promtail Overlay
+
+Log shipping agent that collects container logs and sends them to Loki for centralized log aggregation.
+
+## Features
+
+- **Promtail agent** - Grafana's official log shipping agent
+- **Docker auto-discovery** - Automatically discovers and tails all container logs
+- **Label extraction** - Extracts service names, container names, and custom labels
+- **JSON parsing** - Automatically parses structured logs
+- **Zero configuration** - Works out-of-box with minimal setup
+- **Loki integration** - Ships logs directly to Loki
+
+## How It Works
+
+Promtail is a log shipping agent designed to collect logs from various sources and send them to Loki. In this overlay, Promtail monitors Docker containers and automatically ships their logs to Loki.
+
+**Architecture:**
+
+```mermaid
+graph TD
+    A[Docker Containers<br/>Application logs<br/>Service logs<br/>System logs] -->|Docker socket| B[Promtail<br/>Discovers containers<br/>Tails log files<br/>Parses JSON logs<br/>Adds labels<br/>Buffers & batches]
+    B -->|HTTP Push| C[Loki<br/>Indexes labels<br/>Stores log data<br/>Serves queries]
+```
+
+**What It Does:**
+
+1. **Discovers Containers:** Uses Docker service discovery to find running containers
+2. **Extracts Metadata:** Pulls container name, image, compose service, and project labels
+3. **Tails Logs:** Streams logs from `/var/lib/docker/containers/`
+4. **Parses Content:** Attempts JSON parsing for structured logs
+5. **Ships to Loki:** Sends logs with rich labels to Loki for storage and querying
+
+## Configuration
+
+### Docker Socket Access
+
+Promtail requires access to:
+
+- **Docker socket** (`/var/run/docker.sock`) - For service discovery
+- **Container logs** (`/var/lib/docker/containers`) - For reading log files
+
+Both are mounted read-only for security.
+
+### Environment Variables
+
+The overlay includes a `.env.example` file. Copy it to `.env` and customize:
+
+```bash
+cd .devcontainer
+cp .env.example .env
+```
+
+**Available variables:**
+
+```bash
+# Promtail version
+PROMTAIL_VERSION=latest
+```
+
+### Label Extraction
+
+Promtail automatically extracts these labels from containers:
+
+| Label       | Source           | Example          |
+| ----------- | ---------------- | ---------------- |
+| `container` | Container name   | `my-app-1`       |
+| `image`     | Container image  | `node:18-alpine` |
+| `service`   | Compose service  | `api`            |
+| `project`   | Compose project  | `my-project`     |
+| `job`       | Fixed value      | `docker`         |
+| `level`     | Parsed from JSON | `info`, `error`  |
+
+### Customizing Configuration
+
+Edit `promtail-config.yaml` in `.devcontainer/`:
+
+```yaml
+# Add custom pipeline stages
+pipeline_stages:
+    - match:
+          selector: '{service="api"}'
+          stages:
+              - regex:
+                    expression: '(?P<timestamp>\S+) (?P<level>\S+) (?P<message>.*)'
+              - labels:
+                    level:
+```
+
+## Common Commands
+
+### Viewing Logs in Grafana
+
+**Simple queries:**
+
+```logql
+# All logs from a specific service
+{service="api"}
+
+# Logs from a specific container
+{container="my-app-1"}
+
+# Error logs only
+{level="error"}
+
+# Logs from a specific image
+{image=~"node:.*"}
+```
+
+**Advanced queries:**
+
+```logql
+# Rate of errors per minute
+rate({level="error"}[1m])
+
+# Logs containing specific text
+{service="api"} |= "database connection"
+
+# JSON field filtering
+{service="api"} | json | userId="12345"
+
+# Count logs by service
+sum by(service) (count_over_time({job="docker"}[5m]))
+```
+
+### Checking Promtail Status
+
+```bash
+# Check if Promtail is running
+docker ps | grep promtail
+
+# View Promtail logs
+docker logs promtail
+
+# Check Promtail metrics (from inside dev container)
+curl http://promtail:9080/metrics
+
+# See which targets are being scraped
+curl http://promtail:9080/targets
+```
+
+### Testing Log Collection
+
+**Generate test logs:**
+
+```bash
+# Run a test container with logs
+docker run --rm alpine sh -c "echo 'Test log message'"
+
+# View in Grafana within seconds:
+# {container="alpine"} |= "Test log"
+```
+
+**Verify logs are reaching Loki:**
+
+```bash
+# Check Loki ingestion
+curl "http://loki:3100/loki/api/v1/query" \
+  --data-urlencode 'query={job="docker"}' \
+  --data-urlencode 'limit=10'
+```
+
+## Use Cases
+
+- **Centralized logging** - Aggregate logs from all containers in one place
+- **Debugging** - Track application behavior across services
+- **Monitoring** - Alert on error patterns in logs
+- **Audit trails** - Maintain searchable log history
+- **Development** - Real-time log streaming during development
+
+**Integrates well with:**
+
+- Loki (required) - Log storage and querying
+- Grafana (recommended) - Log visualization and exploration
+- Prometheus (optional) - Correlate metrics with logs
+- Tempo/Jaeger (optional) - Correlate traces with logs
+
+## Log Format Support
+
+### JSON Logs
+
+**Application logging (Node.js):**
+
+```javascript
+const logger = require('pino')();
+
+logger.info({ userId: '123', action: 'login' }, 'User logged in');
+// Promtail extracts: level=info, userId=123
+```
+
+**Application logging (Python):**
+
+```python
+import logging
+import json
+
+logger = logging.getLogger(__name__)
+logger.info(json.dumps({"userId": "123", "action": "login"}))
+```
+
+### Plain Text Logs
+
+**Standard output:**
+
+```bash
+echo "2024-01-15 10:30:00 INFO User logged in"
+# Promtail ships as-is with container labels
+```
+
+### Custom Parsing
+
+Add regex patterns in `promtail-config.yaml`:
+
+```yaml
+pipeline_stages:
+    - regex:
+          expression: '^(?P<timestamp>\S+) (?P<level>\S+) (?P<message>.*)$'
+    - labels:
+          level:
+    - timestamp:
+          source: timestamp
+          format: '2006-01-02 15:04:05'
+```
+
+## Troubleshooting
+
+### Issue: No Logs Appearing
+
+**Symptoms:**
+
+- Promtail running but logs not in Loki
+
+**Solutions:**
+
+```bash
+# Check Promtail can access Docker socket
+docker exec promtail ls -la /var/run/docker.sock
+
+# Check Promtail is discovering containers
+docker logs promtail | grep "discovered targets"
+
+# Verify Loki is reachable
+docker exec promtail wget -O- http://loki:3100/ready
+
+# Check Promtail positions file
+docker exec promtail cat /tmp/positions.yaml
+```
+
+### Issue: "Permission Denied" on Docker Socket
+
+**Symptoms:**
+
+- Promtail logs show permission errors
+
+**Solution:**
+
+```yaml
+# Update docker-compose.yml to add Promtail to docker group
+services:
+    promtail:
+        user: '0:0' # Run as root (development only)
+```
+
+⚠️ **Security Note:** Running as root is acceptable for development but not for production.
+
+### Issue: High Memory Usage
+
+**Symptoms:**
+
+- Promtail consuming excessive memory
+
+**Solutions:**
+
+```yaml
+# Reduce batch size in promtail-config.yaml
+clients:
+    - url: http://loki:3100/loki/api/v1/push
+      batchwait: 1s
+      batchsize: 102400 # Reduce from default 1MB
+```
+
+### Issue: Logs Not Parsed as JSON
+
+**Symptoms:**
+
+- JSON logs appear as plain text in Loki
+
+**Solution:**
+
+- Ensure application logs to stdout in JSON format
+- Check `pipeline_stages` includes `json` stage
+- Some apps need explicit JSON logging configuration
+
+## Security Considerations
+
+⚠️ **Docker Socket Access:** Promtail has read access to the Docker socket, which allows it to discover containers and read logs.
+
+**Risks:**
+
+- Read access to all container logs (may contain sensitive data)
+- Docker API access (read-only)
+
+**Mitigation:**
+
+- Mounted as read-only (`:ro`)
+- Development environment only
+- Filter sensitive fields in pipeline stages:
+
+```yaml
+pipeline_stages:
+    - replace:
+          expression: 'password=\S+'
+          replace: 'password=***'
+```
+
+## Performance Tuning
+
+**For high-volume logging:**
+
+```yaml
+# promtail-config.yaml
+clients:
+    - url: http://loki:3100/loki/api/v1/push
+      batchwait: 500ms # Batch more frequently
+      batchsize: 1048576 # Larger batches
+      max_backoff: 5m # Retry backoff
+      max_retries: 10 # Retry attempts
+```
+
+**Limit log collection:**
+
+```yaml
+# Only collect logs from specific services
+scrape_configs:
+    - job_name: docker
+      docker_sd_configs:
+          - host: unix:///var/run/docker.sock
+      relabel_configs:
+          # Drop logs from monitoring containers
+          - source_labels: ['__meta_docker_container_label_com_docker_compose_service']
+            regex: '(promtail|loki|prometheus)'
+            action: drop
+```
+
+## References
+
+- [Official Promtail Documentation](https://grafana.com/docs/loki/latest/clients/promtail/)
+- [Promtail Configuration](https://grafana.com/docs/loki/latest/clients/promtail/configuration/)
+- [LogQL Query Language](https://grafana.com/docs/loki/latest/logql/)
+- [Docker Service Discovery](https://grafana.com/docs/loki/latest/clients/promtail/configuration/#docker_sd_configs)
+
+**Related Overlays:**
+
+- `loki` - Required log storage backend
+- `grafana` - Recommended for log visualization
+- `prometheus` - Optional for metrics correlation
+- `tempo` - Optional for trace-log correlation

package/overlays/promtail/devcontainer.patch.json

@@ -0,0 +1,5 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "runServices": ["promtail"],
+    "_serviceOrder": 2
+}

package/overlays/promtail/docker-compose.yml

@@ -0,0 +1,16 @@
+version: '3.8'
+services:
+    promtail:
+        image: grafana/promtail:${PROMTAIL_VERSION:-latest}
+        command: -config.file=/etc/promtail/promtail-config.yaml
+        volumes:
+            - ./promtail-config-promtail.yaml:/etc/promtail/promtail-config.yaml
+            - /var/lib/docker/containers:/var/lib/docker/containers:ro
+            - /var/run/docker.sock:/var/run/docker.sock:ro
+        depends_on:
+            - loki
+        networks:
+            - devnet
+
+networks:
+    devnet:

package/overlays/promtail/overlay.yml

@@ -0,0 +1,17 @@
+id: promtail
+name: Promtail
+description: Log shipping agent for Loki with Docker auto-discovery
+category: observability
+supports:
+    - compose
+requires:
+    - loki
+suggests: []
+conflicts: []
+tags:
+    - observability
+    - logs
+    - promtail
+    - loki
+ports: []
+order: 2

package/overlays/promtail/promtail-config.yaml

@@ -0,0 +1,60 @@
+server:
+    http_listen_port: 9080
+    grpc_listen_port: 0
+
+positions:
+    filename: /tmp/positions.yaml
+
+clients:
+    - url: http://loki:3100/loki/api/v1/push
+
+scrape_configs:
+    # Docker container logs auto-discovery
+    - job_name: docker
+      docker_sd_configs:
+          - host: unix:///var/run/docker.sock
+            refresh_interval: 5s
+
+      relabel_configs:
+          # Extract container name
+          - source_labels: ['__meta_docker_container_name']
+            regex: '/(.*)'
+            target_label: 'container'
+
+          # Extract container image
+          - source_labels: ['__meta_docker_container_image']
+            target_label: 'image'
+
+          # Extract compose service name
+          - source_labels: ['__meta_docker_container_label_com_docker_compose_service']
+            target_label: 'service'
+
+          # Extract compose project
+          - source_labels: ['__meta_docker_container_label_com_docker_compose_project']
+            target_label: 'project'
+
+          # Add job label
+          - replacement: 'docker'
+            target_label: 'job'
+
+      pipeline_stages:
+          # Docker logs are wrapped in JSON: {log, stream, time}
+          # First parse the Docker wrapper
+          - docker: {}
+
+          # Then parse application JSON from the log field
+          - json:
+                expressions:
+                    level: level
+                    msg: message
+                    trace_id: trace.id
+                    span_id: span.id
+
+          # Extract log level as label
+          - labels:
+                level:
+
+          # Use Docker's timestamp
+          - timestamp:
+                source: timestamp
+                format: RFC3339Nano

package/overlays/promtail/verify.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+# Promtail verification script
+
+echo "🔍 Verifying Promtail installation..."
+
+# Track overall success
+ALL_CHECKS_PASSED=true
+
+# Check if Promtail service is running
+if docker ps --format '{{.Names}}' | grep -q promtail; then
+    echo "✓ Promtail service is running"
+else
+    echo "✗ Promtail service is not running"
+    ALL_CHECKS_PASSED=false
+fi
+
+# Check if Promtail can access Docker socket
+if docker exec promtail test -S /var/run/docker.sock 2>/dev/null; then
+    echo "✓ Promtail has access to Docker socket"
+else
+    echo "⚠️ Promtail cannot access Docker socket"
+fi
+
+# Final result
+if [ "$ALL_CHECKS_PASSED" = true ]; then
+    echo "✓ All critical checks passed"
+    exit 0
+else
+    echo "✗ Some checks failed"
+    exit 1
+fi