Observability

Portwing ships a zero-dependency Prometheus metrics endpoint plus explicit liveness and readiness routes in both standard and edge modes. No instrumentation library is embedded — the agent writes the exposition format directly.

Metrics endpoint

Metrics are available at two paths; both serve identical output:

In standard mode both paths require a valid Bearer token. In edge mode the local operations listener exposes /health, /ready, /_portwing/health, /metrics, and /_portwing/audit/export; keep that listener on a private container or pod network because the metrics and audit-export routes have no inbound credential surface. The audit export can contain client addresses, request paths, stack names, and container identifiers, so restrict listener access to the monitoring/exporter workload rather than the whole cluster. The response content-type is text/plain; version=0.0.4; charset=utf-8 (Prometheus text exposition format 0.0.4).

Prometheus scrape config

scrape_configs:
  - job_name: portwing
    scheme: https          # use http if TLS is not configured
    static_configs:
      - targets: ["your-host:3000"]
    authorization:
      type: Bearer
      credentials: YOUR_PORTWING_TOKEN
    tls_config:
      # ca_file: /etc/prometheus/portwing-ca.crt  # uncomment if using a custom CA
      insecure_skip_verify: false

Edge-mode scrape config on the same private container or pod network:

scrape_configs:
  - job_name: portwing-edge
    scheme: http
    static_configs:
      - targets: ["portwing-edge:3000"]

Exported metrics

Agent metrics

These metrics are always present and use the portwing_ prefix.

Per-container metrics

These metrics are emitted once per running container and carry id, name, and image labels. They are absent from the output if no containers are running or if Docker is unreachable at scrape time.

The container_ prefix is intentionally compatible with cAdvisor label conventions so the metrics slot into existing Grafana dashboards without relabelling.

Request metrics

These metrics track HTTP request activity and are the most operationally relevant signals for latency alerting and security monitoring.

Sample lines:

portwing_http_requests_total{method="POST",code="200"} 42
portwing_auth_failures_total{reason="bad_token"} 3

Edge connection and audit metrics

These series make controller connectivity, reconnect churn, slow-consumer backpressure, and audit exporter health directly alertable.

Recommended alerts include sustained portwing_edge_controller_connected == 0, a reconnect rate above the expected maintenance baseline, any increase in backpressure events, and an audit buffer that remains at capacity while the exporter error counter rises.

Sample output

# HELP portwing_build_info Portwing agent build metadata.
# TYPE portwing_build_info gauge
portwing_build_info{version="0.9.1"} 1
# HELP portwing_uptime_seconds Seconds since the agent started.
# TYPE portwing_uptime_seconds gauge
portwing_uptime_seconds 3842.7
# HELP portwing_host_cpu_usage_percent Host CPU usage percentage.
# TYPE portwing_host_cpu_usage_percent gauge
portwing_host_cpu_usage_percent 4.2
# HELP portwing_host_memory_total_bytes Host total memory in bytes.
# TYPE portwing_host_memory_total_bytes gauge
portwing_host_memory_total_bytes 8589934592
# HELP portwing_host_memory_used_bytes Host used memory in bytes.
# TYPE portwing_host_memory_used_bytes gauge
portwing_host_memory_used_bytes 3145728000
# HELP portwing_host_disk_total_bytes Host total disk space in bytes.
# TYPE portwing_host_disk_total_bytes gauge
portwing_host_disk_total_bytes 107374182400
# HELP portwing_host_disk_used_bytes Host used disk space in bytes.
# TYPE portwing_host_disk_used_bytes gauge
portwing_host_disk_used_bytes 32212254720
# HELP portwing_host_network_receive_bytes_total Host network bytes received (all non-lo interfaces).
# TYPE portwing_host_network_receive_bytes_total counter
portwing_host_network_receive_bytes_total 1073741824
# HELP portwing_host_network_transmit_bytes_total Host network bytes transmitted (all non-lo interfaces).
# TYPE portwing_host_network_transmit_bytes_total counter
portwing_host_network_transmit_bytes_total 536870912
# HELP container_cpu_usage_seconds_total Cumulative CPU time consumed by the container in seconds.
# TYPE container_cpu_usage_seconds_total counter
container_cpu_usage_seconds_total{id="a1b2c3d4e5f6",name="myapp",image="myapp:latest"} 120.5
# HELP container_memory_usage_bytes Current memory usage of the container in bytes.
# TYPE container_memory_usage_bytes gauge
container_memory_usage_bytes{id="a1b2c3d4e5f6",name="myapp",image="myapp:latest"} 134217728

Liveness, readiness, and info endpoints

GET /health

No authentication required. Intended for Docker/Kubernetes liveness probes. It does not contact Docker or the edge controller, so a dependency outage cannot put the process into a restart loop.

curl http://your-host:3000/health

Returns HTTP 200 with the full operational shape:

{"status":"ok","live":true,"ready":false,"mode":"standard","version":"0.9.1","uptimeSeconds":3842.7,"docker":"unknown","controller":"not_applicable"}

GET /ready

No authentication required. In standard mode, readiness requires Docker. In edge mode, readiness requires both Docker and the Drydock controller WebSocket. It returns HTTP 503 until every required dependency is connected.

curl http://your-host:3000/ready

Standard-mode ready response:

{"status":"healthy","live":true,"ready":true,"mode":"standard","version":"0.9.1","uptimeSeconds":3842.7,"docker":"connected","controller":"not_applicable"}

Edge-mode not-ready response:

{"status":"unhealthy","live":true,"ready":false,"mode":"edge","version":"0.9.1","uptimeSeconds":42.1,"docker":"connected","controller":"disconnected"}

GET /_portwing/health remains as a compatibility alias for /ready.

The container image's built-in healthcheck uses /health and automatically selects HTTP or HTTPS from TLS_CERT, while the Kubernetes examples use /health for liveness and /ready for readiness.

GET /_portwing/info

Bearer auth required. Returns agent version, Docker version, connection mode, uptime, hostname, and the capability list.

curl -H "Authorization: Bearer YOUR_PORTWING_TOKEN" \
  https://your-host:3000/_portwing/info

Related

• Audit Logging — structured audit events complement these time-series metrics for the security side of observability.
• API Reference — full OpenAPI spec for all endpoints including metrics and health.
• Configuration — token configuration options referenced in the scrape config above.
• Deployment examples — pinned Prometheus and Fluent Bit topologies for Compose and Kubernetes.