ghp exposes Prometheus metrics and structured access logs for observability.

Prometheus Metrics

When metrics are enabled (the default), ghp runs a dedicated metrics server on a separate port. This keeps metrics traffic isolated from the main proxy.

metrics:
  enabled: true
  listen: ":9136"

Scrape the metrics endpoint at http(s)://<ghp-server>:9136/metrics (HTTPS when ghp runs with TLS enabled, HTTP otherwise).

Available Metrics

HTTP Request Metrics

The backend label distinguishes traffic by virtualhost: api.github.com, github.com, codeload.github.com, copilot, or management.

The client label on ghp_client_request_total is the source IP of the request, so operators can spot a host generating disproportionate traffic. By default it is the direct peer address. Behind a reverse proxy, set server.client_ip_header to the one forwarded header your proxy is documented to set — forwarded (RFC 7239 for=), x-real-ip, or x-forwarded-for — and only that header is consulted. All other forwarded headers are ignored: most proxies set exactly one family and pass the others through untouched, so trusting more than the configured header would let clients spoof attribution (and rotate per-IP rate-limit buckets) via a header the proxy never rewrites. The setting assumes exactly one trusted reverse proxy, so for the chain-style headers (Forwarded, X-Forwarded-For) the rightmost entry is used — that is the one appended by the trusted proxy; entries to its left arrived inside the client's own request and are spoofable. Header values must parse as an IP address (an optional port is tolerated); anything else — including RFC 7239 unknown and obfuscated identifiers — falls back to the peer address, so clients cannot inject arbitrary strings into label values. The same attribution is used for the per-IP authentication rate limiter, so behind a reverse proxy client_ip_header must be set for rate limits to apply per client rather than per proxy. The token_type label is proxy (ghx_), agent (gha_), a native GitHub prefix (gho, ghp, ghs, ...), or unknown for unauthenticated traffic. Cardinality is bounded by the number of distinct client hosts; map IPs to hostnames in Grafana or with recording rules if needed.

Proxy Metrics

The type label distinguishes API traffic from git smart-HTTP traffic (e.g. type="git" for git operations proxied via the github.com backend). The decision pipeline metric breaks down the overhead ghp adds to each request into individually timed stages so you can identify where latency originates. The stages are:

Git Cache Metrics

ghp_cache_fetch_total result values:

ghp_cache_request_total result values:

Identifying cache candidates

The ghp_cache_request_total metric includes owner and repo labels, enabling per-repository analysis. Use it to identify repositories that would benefit from caching:

# Top 10 uncached repos by request volume — candidates for adding to cache
topk(10, sum by (owner, repo) (ghp_cache_request_total{result="nocache"}))

# Repos configured but disabled — consider re-enabling
sum by (owner, repo) (ghp_cache_request_total{result="bypass"})

# Cache hit rate per repo — verify caching is effective
sum by (owner, repo) (ghp_cache_request_total{result="hit"})
/ sum by (owner, repo) (ghp_cache_request_total)

# Repos with high miss rates — may need cache warming or service token
sum by (owner, repo) (ghp_cache_request_total{result="miss"})
/ sum by (owner, repo) (ghp_cache_request_total{result=~"hit|miss"})

See Git Cache for configuration details.

Token Metrics

GitHub Rate Limit Metrics

Security Metrics

Release Controls Metrics

The result label on the HEAD check counter has three values:

When redirect_head_check is enabled, each HEAD request is also timed in the decision pipeline histogram (ghp_proxy_decision_duration_seconds) under the redirect_head_check stage. This lets you monitor how much latency the availability probe adds to redirected release downloads.

See Release Download Controls for configuration details.

Codeload Redirect Metrics

The archive label is one of tar.gz, zip, legacy.tar.gz, or legacy.zip. The result label is redirect (302 to the configured caching mirror) or passthrough (forwarded to upstream codeload because the org/repo is in the allow list or no redirect_to is configured). The full ref (SHA, branch, or tag) is intentionally omitted from labels to keep cardinality bounded; query the access log for per-ref breakdowns.

See Codeload Redirect for configuration details.

Logging

ghp treats OpenTelemetry log records as its first-class logging primitive. Every log — operational messages, the HTTP access log, and the audit log — is emitted as an OTel log record described using OpenTelemetry semantic conventions rather than the legacy Caddy-style JSON field names. Records are always written to the console (stdout or a file) using the OTel stdout exporter, and can additionally be shipped to an OTLP collector (see OpenTelemetry below).

Each emitted record carries a service.name=ghp resource attribute and an instrumentation scope that identifies the stream. Aggregators can route on the scope name the same way they previously keyed on the Caddy logger field:

Access Logs

An access log record is emitted for every request across all virtualhosts, with body handled request. Attributes use HTTP semantic conventions:

Records for responses with a 5xx status are emitted at Error severity; all others at Info.

Configure logging output and level:

logging:
  output: "stdout"         # "stdout" or "file"
  level: "info"            # "debug", "info", "warn", "error" (operational logs)
  file:
    path: "/var/log/ghp/ghp.log"

The level setting filters operational (slog) records; access and audit records are always emitted.

Audit Logs

API proxy requests and token lifecycle events (creation, revocation, scope updates) emit audit records under the github.com/goodtune/ghp/audit scope with body audit event. Attributes:

Token lifecycle events omit the request- and repository-related attributes.

OpenTelemetry export

In addition to the console exporter, ghp can ship every log record to an OTLP collector. Enable it under otel (see Configuration → OpenTelemetry):

otel:
  enabled: true
  endpoint: "http://localhost:4318"   # http:// → TLS disabled (insecure)
  protocol: "http"                     # "grpc" (default) or "http"

When enabled, records are batched and exported to the collector while still being written to the console. Capturing and indexing logs that are only written to the console is the responsibility of the deployment environment (e.g. Splunk, Elastic, Datadog).

Server Response Headers

Every response from ghp includes two identifying headers, set by a server-wide middleware regardless of which backend served the request:

• Server: GitHub Proxy — a fixed value that overrides any upstream Server header (e.g. GitHub's own server: github.com), making it easy to verify that traffic is flowing through ghp rather than directly to GitHub.
• X-GitHub-Proxy-Version: <version> — the build version of the running ghp binary, so operators can identify exactly which image a deployment is serving. The header is omitted when no version was compiled in.

You can confirm the deployed version from the command line:

curl -sI https://ghp.example.com/docs/ | grep -i x-github-proxy-version

The same version string is also displayed beneath the login form in the web UI, so managers rolling out a new image can identify the running version at a glance without inspecting headers.

Health Check

The /auth/status endpoint on the management host returns the current authentication status. It requires authentication and returns HTTP 401 when no valid session cookie is present, and HTTP 200 only when the user is authenticated. This makes it unsuitable for unauthenticated liveness checks that expect a 2xx response.

For basic unauthenticated liveness checks, use the documentation endpoint which is always accessible without authentication:

curl -s https://ghp.example.com/docs/

To verify both service health and authentication, use /auth/status with an authenticated session and expect HTTP 200 on success:

curl -s https://ghp.example.com/auth/status