> For the complete documentation index, see [llms.txt](https://docs.qpoint.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qpoint.io/getting-started/qtap/configuration/configuration-examples.md).

# Configuration Examples

### 1. Development

```yaml
# 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|headers|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

```yaml
# 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|headers|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

```yaml
# 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|headers|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: headers
            # 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

```yaml
# 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|headers|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: headers
            # 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

```yaml
# 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|headers|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: headers
            # 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

```yaml
# 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|headers|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

```yaml
# 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|headers|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: headers
            # API v2 endpoints
            - name: "API v2 monitoring"
              expr: http.req.path matches /^\/api\/v2\//
              level: headers
            # 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

```yaml
# 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|headers|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: headers
            # 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

```yaml
# 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|headers|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: headers
            # 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

```yaml
  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

```yaml
# 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|headers|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
# }
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.qpoint.io/getting-started/qtap/configuration/configuration-examples.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.