Health Monitoring for Private Locations¶

See Environment Variables for the complete Private Location configuration reference.

Verbosity Control¶

The Private Location supports configurable log verbosity levels through the ESCAPE_VERBOSITY environment variable. This setting controls the amount of diagnostic information output by the Private Location service.

Available Verbosity Levels¶

Configuration Example¶

The verbosity level can be set using the ESCAPE_VERBOSITY environment variable:

Docker Compose:

services:
  private-location:
    image: escapetech/cli:latest
    restart: always
    command: locations start -v location-name
    environment:
      - ESCAPE_API_KEY=<ESCAPE_API_KEY>
      - ESCAPE_VERBOSITY=1

Helm:

container:
  env:
    - name: ESCAPE_VERBOSITY
      value: "1"

How does Escape determine if a Private Location is alive and operational?¶

Escape monitors Private Location health through a multi-layered approach:

• Regular heartbeats: The Private Location sends periodic health checks to the Escape platform (every 5 seconds) to signal operational status. Heartbeats update Last seen; they are not log lines.
• Connection status tracking: The platform records connect and disconnect on the location logs page when the SSH tunnel opens or closes.
• Performance monitoring: Escape tracks response times and success rates of scan requests to detect performance degradation

Open a location on the Private Locations dashboard to see last-seen time, connect/disconnect events, and forwarded Info-level and higher-severity logs. Debug and trace stay on the agent so scan traffic does not flood that page.

How Do Restarts Work?¶

The agent retries an SSH connection when it disconnects. Docker Compose's restart: always only restarts a container after its process exits, not when /health returns 503.

The Helm chart configures a scheduled 24h restart with ESCAPE_CLI_RESTART_INTERVAL. It also checks /health every 60 seconds and restarts the pod after 60 failed checks. The chart doesn't expose liveness probe timing as a Helm value.

For Docker Compose or a custom deployment, set HEALTH_CHECK_PORT, monitor /health, and restart the container when it reports 503. See Deployment Methods.

Advanced Request Logging and Monitoring for Private Locations¶

The CLI can't see the HTTPS/mTLS traffic, That's why we need to use a proxy to intercept the traffic. Below is an example using mitmproxy

Example: Using mitmproxy to extract the X-Escape-Request-Id header¶

You can provide a custom python script to catch the request ID and forward it to the Escape platform. Create a file called ./mitmproxy/extract_escape_request_id.py with the following content:

import requests
import os


class Addon:
    def __init__(self):
        port = os.getenv("HEALTH_CHECK_PORT", "8080")
        self.log_url = f"http://private-location:{port}/log"

    def request(self, flow):
        request_id = flow.request.headers.get("X-Escape-Request-Id", "")
        if request_id:
            requests.post(self.log_url, data=f'Forwarding X-Escape-Request-Id: {request_id}')

addons = [Addon()]

Then to configure a Private Location to use this addon, you can use the following docker-compose file:

services:
  private-location:
    image: escapetech/cli:latest
    restart: always
    command: locations start -v location-name
    environment:
      - ESCAPE_API_KEY=<ESCAPE_API_KEY>
      - HEALTH_CHECK_PORT=8080
      - ESCAPE_BACKEND_PROXY_URL=mitm-proxy:8080
      - ESCAPE_ENABLE_LOGS_ENDPOINT=true
  mitm-proxy:
    image: mitmproxy/mitmproxy:latest
    restart: always
    ports:
      - "8080:8080"
    command: "mitmdump -s /mitmproxy/extract_escape_request_id.py"
    volumes:
      - ./mitmproxy:/mitmproxy