Docs / Run

Operations

What you need to run Ghoti somewhere other than your laptop: metrics, connection limits, process lifecycle and TLS.

Prometheus metrics#

Ghoti can expose runtime metrics for Prometheus. When enabled, a dedicated HTTP listener serves GET /metrics in the Prometheus text exposition format. It is disabled by default.

metrics:
  enabled: true
  addr: "127.0.0.1:9100"   # host:port where GET /metrics is served
KeyDescription
metrics.enabledEnables metrics collection and the /metrics endpoint. Default false.
metrics.addrhost:port of the metrics listener. Required when enabled.

The endpoint is unauthenticated, so bind it to a private interface or firewall it as you would any Prometheus target. Scrape it with a standard job:

scrape_configs:
  - job_name: ghoti
    static_configs:
      - targets: ["127.0.0.1:9100"]

Besides the standard Go runtime (go_*) and process (process_*) collectors, Ghoti exposes:

MetricTypeDescription
ghoti_connected_clientsgaugeNumber of currently connected clients.
ghoti_requests_totalcounterTotal number of requests processed. Use rate() for requests per second.
ghoti_request_duration_secondshistogramRequest processing time in seconds, with buckets from 50 µs to 1 s. Use histogram_quantile() for tail latency.

For example, requests per second and p99 processing time over the last five minutes:

rate(ghoti_requests_total[5m])
histogram_quantile(0.99, rate(ghoti_request_duration_seconds_bucket[5m]))

Before version 0.2, metrics were written to files. The old keys (output_dir, rotation, retain, interval) are now rejected at startup so the change isn't missed.

Connection limits#

By default Ghoti accepts as many client connections as the operating system allows. max_connections caps how many can be open at once, on every transport:

max_connections: 1000

Deployment#

When ghoti run fails to start, the exit status tells you which step failed:

Exit statusCause
1The configuration couldn't be loaded or is invalid.
3The cluster couldn't be created: an unsupported cluster.manager.type, or cluster.user or cluster.pass shorter than 4 characters. A failed join does not stop the server; see Cluster.
4The server couldn't start listening on addr.
5The metrics listener couldn't start.

TLS#

Ghoti has no TLS on any listener: not the protocol port, not the HTTP and SSE transport, not the cluster manager, and not the metrics endpoint. On these connections, the p command, the HTTP Basic Auth header and the cluster credentials all travel in cleartext.

For any deployment that isn't entirely local:

The full security model, and how to report a vulnerability, are in SECURITY.md.

Found something out of date? Open an issue or edit this page.