Configuration Examples

1. Development

# Development configuration to see all HTTP traffic
# Outputs everything to console for immediate debugging
version: 2

services:
  event_stores:
    - type: stdout
  object_stores:
    - type: stdout

stacks:
  development:
    plugins:
      - type: http_capture
        config:
          level: full       # (none|summary|details|full)
          format: text      # (json|text)

tap:
  direction: all            # (egress|egress-external|egress-internal|ingress|all)
  ignore_loopback: false    # Include localhost traffic
  audit_include_dns: true   # See DNS queries too
  http:
    stack: development

# Test with: curl -X POST https://httpbin.org/post -d "test=data" -H "Content-Type: application/json"

2. API Error Debugging

# Production-safe configuration that only captures when things go wrong
# Shows summary for all traffic, full details for errors
version: 2

services:
  event_stores:
    - type: stdout
  object_stores:
    - type: stdout

stacks:
  error_capture:
    plugins:
      - type: http_capture
        config:
          level: summary  # (none|summary|details|full) - Default: basic info for all requests
          format: json    # (json|text) - Structured for analysis
          rules:
            # Capture everything for client errors
            - name: "Debug 4XX errors"
              expr: http.res.status >= 400 && http.res.status < 500
              level: full
            # Capture everything for server errors
            - name: "Debug 5XX errors"
              expr: http.res.status >= 500
              level: full

tap:
  direction: egress         # (egress|egress-external|egress-internal|ingress|all)
  ignore_loopback: true     # Skip internal traffic
  audit_include_dns: false  
  http:
    stack: error_capture

# Test with: curl https://httpbin.org/status/500  # Triggers 5XX error (full capture)
# Test with: curl https://httpbin.org/status/404  # Triggers 4XX error (full capture)
# Test with: curl https://httpbin.org/get         # Normal request (summary only)

3. Domain-Specific Monitoring

# Different capture levels for different domains
# Shows summary by default, more for specific domains
version: 2

services:
  event_stores:
    - type: stdout
  object_stores:
    - type: stdout

stacks:
  multi_domain:
    plugins:
      - type: http_capture
        config:
          level: summary  # (none|summary|details|full) - Default: basic info
          format: json    # (json|text)
          rules:
            # Full capture for test environment
            - name: "Debug httpbin.org"
              expr: http.req.host == "httpbin.org"
              level: full
            # Headers for GitHub API
            - name: "GitHub API monitoring"
              expr: http.req.host == "api.github.com"
              level: details
            # Full capture for test APIs
            - name: "Test API services"
              expr: http.req.host matches /\.(typicode|mockapi)\.com$/
              level: full
            # Skip health checks
            - name: "Ignore health checks"
              expr: http.req.path in ["/health", "/ping", "/metrics"]
              level: none

tap:
  direction: egress-external  # (egress|egress-external|egress-internal|ingress|all)
  ignore_loopback: true
  audit_include_dns: false
  http:
    stack: multi_domain

# Test with: curl https://httpbin.org/get                        # Full capture
# Test with: curl https://api.github.com/users                   # Headers only
# Test with: curl https://jsonplaceholder.typicode.com/posts/1   # Full capture
# Test with: curl https://httpbin.org/status/200                 # Summary only (not a health path)

4. Container-Based Debugging

# Debug specific containers in Docker/Kubernetes
# Shows summary for all, full for specific containers
version: 2

services:
  event_stores:
    - type: stdout
  object_stores:
    - type: stdout

stacks:
  container_debug:
    plugins:
      - type: http_capture
        config:
          level: summary  # (none|summary|details|full) - Default: basic info
          format: text    # (json|text)
          rules:
            # Debug specific container by name
            - name: "Debug payment service"
              expr: src.container.name == "payment-service"
              level: full
            # Debug by container image
            - name: "Debug Redis containers"
              expr: src.container.image contains "redis"
              level: details
            # Debug containers with debug label
            - name: "Debug labeled containers"
              expr: src.container.labels.debug == "true"
              level: full
            # Debug specific process
            - name: "Debug curl requests"
              expr: src.process.binary == "curl"
              level: full

tap:
  direction: all            # (egress|egress-external|egress-internal|ingress|all)
  ignore_loopback: false    # Include container-to-container
  audit_include_dns: false
  http:
    stack: container_debug

# Test with: docker run --name payment-service --rm curlimages/curl https://httpbin.org/get
# Test with: docker run --label debug=true --rm curlimages/curl https://httpbin.org/post -d "test"
# Test with: curl https://httpbin.org/get  # If running from host, captures curl binary (full)

5. Kubernetes Pod Debugging

# Debug specific pods or namespaces in Kubernetes
# Shows summary by default, more for specific pods
version: 2

services:
  event_stores:
    - type: stdout
  object_stores:
    - type: stdout

stacks:
  k8s_debug:
    plugins:
      - type: http_capture
        config:
          level: summary  # (none|summary|details|full) - Default: basic info
          format: text    # (json|text)
          rules:
            # Debug specific pod pattern
            - name: "Debug frontend pods"
              expr: src.pod.name matches /^frontend-deployment-/
              level: full
            # Debug by namespace
            - name: "Staging namespace debugging"
              expr: src.pod.namespace == "staging"
              level: details
            # Debug by pod label
            - name: "Debug enabled pods"
              expr: src.pod.labels.debug == "true"
              level: full
            # Debug specific app
            - name: "Debug payment app pods"
              expr: src.pod.labels.app == "payment-service"
              level: full

tap:
  direction: all            # (egress|egress-external|egress-internal|ingress|all)
  ignore_loopback: false    # Include pod-to-pod traffic
  audit_include_dns: false
  http:
    stack: k8s_debug

# Test with: kubectl run test-curl --image=curlimages/curl --rm -it -- https://httpbin.org/get
# Test with: kubectl run test-debug --labels="debug=true" --image=curlimages/curl --rm -it -- https://httpbin.org/post -d "test"
# Test with: kubectl -n staging run test-staging --image=curlimages/curl --rm -it -- https://httpbin.org/get

6. Security Monitoring

# Detect and capture potentially malicious traffic
# Shows summary for normal traffic, full for suspicious patterns
version: 2

services:
  event_stores:
    - type: stdout
  object_stores:
    - type: stdout

stacks:
  security:
    plugins:
      - type: http_capture
        config:
          level: summary  # (none|summary|details|full) - Default: basic monitoring
          format: json    # (json|text)
          rules:
            # Capture authentication failures
            - name: "Authentication failures"
              expr: http.res.status == 401 || http.res.status == 403
              level: full
            # SQL injection patterns in URL
            - name: "SQL injection attempts"
              expr: http.req.url matches /(\-\-|union\s+select|drop\s+table)/i
              level: full
            # Path traversal attempts
            - name: "Path traversal"
              expr: http.req.path contains "../" || http.req.path contains "..%2F"
              level: full
            # Suspicious user agents
            - name: "Malicious scanners"
              expr: http.req.headers.user-agent matches /(sqlmap|nikto|havij|acunetix)/i
              level: full

tap:
  direction: ingress        # (egress|egress-external|egress-internal|ingress|all)
  ignore_loopback: true
  audit_include_dns: true   # DNS can reveal C&C communication
  http:
    stack: security

# Test with: curl https://httpbin.org/status/401                          # Auth failure (full)
# Test with: curl "https://httpbin.org/get?id=1' OR '1'='1' --"          # SQL injection pattern (full)
# Test with: curl https://httpbin.org/../../../etc/passwd                 # Path traversal (full)
# Test with: curl https://httpbin.org/get -H "User-Agent: sqlmap/1.0"     # Suspicious agent (full)
# Test with: curl https://httpbin.org/get                                 # Normal request (summary)

7. API Endpoint Monitoring

# Monitor specific API endpoints with different rules
# Shows summary by default, more for sensitive endpoints
version: 2

services:
  event_stores:
    - type: stdout
  object_stores:
    - type: stdout

stacks:
  api_monitoring:
    plugins:
      - type: http_capture
        config:
          level: summary  # (none|summary|details|full) - Default: basic info
          format: json    # (json|text)
          rules:
            # Full capture for authentication endpoints
            - name: "Auth endpoints"
              expr: http.req.path in ["/login", "/logout", "/oauth/token"]
              level: full
            # Capture payment endpoints
            - name: "Payment processing"
              expr: http.req.path contains "/payment" || http.req.path contains "/checkout"
              level: details
            # API v2 endpoints
            - name: "API v2 monitoring"
              expr: http.req.path matches /^\/api\/v2\//
              level: details
            # GraphQL queries
            - name: "GraphQL monitoring"
              expr: http.req.path == "/graphql" && http.req.method == "POST"
              level: full

tap:
  direction: all            # (egress|egress-external|egress-internal|ingress|all)
  ignore_loopback: true
  audit_include_dns: false
  http:
    stack: api_monitoring

# Test with: curl https://httpbin.org/anything/login -X POST -d "user=test"          # Auth endpoint (full)
# Test with: curl https://httpbin.org/anything/payment/process                       # Payment endpoint (details)
# Test with: curl https://httpbin.org/anything/api/v2/users                          # API v2 endpoint (details)
# Test with: curl https://httpbin.org/anything/graphql -X POST -d '{"query":"test"}' # GraphQL (full)
# Test with: curl https://httpbin.org/get                                            # Normal request (summary)

8. Method-Based Capture

# Different capture levels based on HTTP methods
# Shows summary for GET, more for mutations
version: 2

services:
  event_stores:
    - type: stdout
  object_stores:
    - type: stdout

stacks:
  method_based:
    plugins:
      - type: http_capture
        config:
          level: summary  # (none|summary|details|full)
          format: json    # (json|text)
          rules:
            # Full capture for mutations
            - name: "Capture POST requests"
              expr: http.req.method == "POST"
              level: full
            - name: "Capture PUT requests"
              expr: http.req.method == "PUT"
              level: full
            - name: "Capture DELETE requests"
              expr: http.req.method == "DELETE"
              level: full
            # Headers only for PATCH
            - name: "Monitor PATCH requests"
              expr: http.req.method == "PATCH"
              level: details
            # Skip OPTIONS preflight
            - name: "Skip CORS preflight"
              expr: http.req.method == "OPTIONS"
              level: none

tap:
  direction: egress         # (egress|egress-external|egress-internal|ingress|all)
  ignore_loopback: true
  audit_include_dns: false
  http:
    stack: method_based

# Test with: curl -X GET https://httpbin.org/get                       # Summary only
# Test with: curl -X POST https://httpbin.org/post -d "data=test"      # Full capture
# Test with: curl -X PUT https://httpbin.org/put -d "data=update"      # Full capture
# Test with: curl -X DELETE https://httpbin.org/delete                  # Full capture
# Test with: curl -X PATCH https://httpbin.org/patch -d "data=patch"   # Headers only
# Test with: curl -X OPTIONS https://httpbin.org/anything              # No output (none)

9. Header-Based Debugging

# Capture based on request/response headers
# Shows summary by default, more for specific headers
version: 2

services:
  event_stores:
    - type: stdout
  object_stores:
    - type: stdout

stacks:
  header_based:
    plugins:
      - type: http_capture
        config:
          level: summary  # (none|summary|details|full)
          format: json    # (json|text)
          rules:
            # Debug requests with trace headers
            - name: "Trace enabled requests"
              expr: http.req.headers.x-trace-enabled == "true"
              level: full
            # Capture requests with specific API keys
            - name: "Debug API key"
              expr: http.req.headers.x-api-key == "debug-key-123"
              level: full
            # Monitor JWT authentication
            - name: "JWT requests"
              expr: http.req.headers.authorization contains "Bearer"
              level: details
            # Debug based on response headers
            - name: "Capture rate limited requests"
              expr: http.res.headers.x-ratelimit-remaining == "0"
              level: full

tap:
  direction: egress         # (egress|egress-external|egress-internal|ingress|all)
  ignore_loopback: true
  audit_include_dns: false
  http:
    stack: header_based

# Test with: curl https://httpbin.org/get                                         # Summary only
# Test with: curl https://httpbin.org/get -H "X-Trace-Enabled: true"              # Full capture
# Test with: curl https://httpbin.org/get -H "X-API-Key: debug-key-123"           # Full capture
# Test with: curl https://httpbin.org/bearer -H "Authorization: Bearer abc123"     # Details capture
# Test with: curl https://httpbin.org/response-headers?X-RateLimit-Remaining=0    # Response header trigger (full)

10. Production with Rulekit Macros

  version: 2

  services:
    event_stores:
      - type: stdout
    object_stores:
      - type: stdout

  rulekit:
    macros:
      # Status code groups
      - name: is_error
        expr: http.res.status >= 400
      - name: is_client_error
        expr: http.res.status >= 400 && http.res.status < 500
      - name: is_server_error
        expr: http.res.status >= 500

      # Create specific macros instead of parameterized ones
      - name: is_httpbin
        expr: http.req.host == "httpbin.org" || http.req.host matches /\.httpbin\.org$/
      - name: is_github
        expr: http.req.host == "github.com" || http.req.host matches /\.github\.com$/
      - name: is_googleapis
        expr: http.req.host matches /\.googleapis\.com$/

      # Path patterns
      - name: is_api_call
        expr: http.req.path matches /^\/api\//
      - name: is_static_asset
        expr: http.req.path matches /\.(css|js|png|jpg|ico|woff|ttf)$/

      # Authentication
      - name: is_authenticated
        expr: http.req.headers.authorization != ""

  stacks:
    production:
      plugins:
        - type: http_capture
          config:
            level: summary
            format: json
            rules:
              - name: "All errors"
                expr: is_error()
                level: full

              - name: "API errors"
                expr: is_api_call() && is_error()
                level: full

              - name: "Production monitoring"
                expr: is_httpbin() && is_server_error()
                level: full

              - name: "Ignore static files"
                expr: is_static_asset()
                level: none

              - name: "Auth failures"
                expr: is_authenticated() && http.res.status == 401
                level: full

        - type: report_usage

  tap:
    direction: all
    ignore_loopback: true
    audit_include_dns: false
    http:
      stack: production

11. Multi-Tenant with Custom Tags

# Tag traffic by team, service, and environment for multi-tenant observability
# Custom tags enable filtering and cost allocation in Qplane
version: 2

services:
  event_stores:
    - type: s3
      config:
        bucket: my-qtap-events
        region: us-west-2
  object_stores:
    - type: s3
      config:
        bucket: my-qtap-objects
        region: us-west-2

tags:
  # Extract from environment variables
  - key: service
    source: env
    location: SERVICE_NAME
  - key: version
    source: env
    location: APP_VERSION
  - key: environment
    source: env
    location: ENVIRONMENT

  # Extract from container labels
  - key: team
    source: container.label
    location: team

  # Extract from Kubernetes labels
  - key: app
    source: k8s.label
    location: app
  - key: cost_center
    source: k8s.annotation
    location: cost-center

stacks:
  multi_tenant:
    plugins:
      - type: http_capture
        config:
          level: summary  # (none|summary|details|full)
          format: json    # (json|text)
          rules:
            # Full capture for errors
            - name: "Capture errors"
              expr: http.res.status >= 400
              level: full

tap:
  direction: egress         # (egress|egress-external|egress-internal|ingress|all)
  ignore_loopback: true
  audit_include_dns: false
  http:
    stack: multi_tenant

# Run application with environment variables:
# SERVICE_NAME=api-gateway APP_VERSION=2.1.0 ENVIRONMENT=production python ./app.py
#
# Or in Docker with labels:
# docker run --label team=platform myapp:latest
#
# Or in Kubernetes with labels and annotations:
# kubectl run api-server --labels="app=api-server,team=backend" \
#   --annotations="cost-center=eng-001"
#
# Start qtap with static infrastructure tags:
# qtap --config=/path/to/config.yaml --tags='region:us-west-2,cluster:prod'
#
# Result: Connection events include all tags merged together:
# "tags": {
#   "service": ["api-gateway"],        // from env var
#   "version": ["2.1.0"],              // from env var
#   "environment": ["production"],     // from env var
#   "team": ["platform"],              // from container label or k8s label
#   "app": ["api-server"],             // from k8s label
#   "cost_center": ["eng-001"],        // from k8s annotation
#   "region": ["us-west-2"],           // from CLI --tags
#   "cluster": ["prod"],               // from CLI --tags
#   "bin": ["python"],                 // default
#   "host": ["k8s-node-01"],          // default
#   "protocol": ["http2"],            // default
#   "strategy": ["observe"]           // default
# }