Features / Telemetry

Telemetry

MiraServe can tell you what it is doing in three ways: a Prometheus metrics endpoint, a periodic push of the same metrics to an OpenTelemetry collector, and log lines for every request and security decision. This page shows how to turn each on, what they contain, and what is removed from logs before they are written.

Smallest working setup

server {
    listen ":443" protocols="h3,h2,h1"
    tls {
        cert "/etc/miraserve/certs/example.com.crt"
        key "/etc/miraserve/certs/example.com.key"
    }

    telemetry {
        metrics-listen "127.0.0.1:9090"
        metrics-path "/metrics"
        otlp-endpoint "https://otel.internal.example:4318"
        service-name "miraserve-edge-1"
        redact-logs #true
    }
}

site "example.com" {
    root "/var/www/example"
}
$ curl -s http://127.0.0.1:9090/metrics | grep security_blocks
# HELP miraserve_security_blocks_total Requests rejected by MiraServe security controls.
# TYPE miraserve_security_blocks_total counter
miraserve_security_blocks_total{reason="rate_limit"} 0
miraserve_security_blocks_total{reason="anti_smuggling"} 0
miraserve_security_blocks_total{reason="site_preset"} 0
miraserve_security_blocks_total{reason="bot_auth"} 0
miraserve_security_blocks_total{reason="mcp_rbac"} 2
miraserve_security_blocks_total{reason="wasm_sandbox"} 0

The telemetry block

telemetry goes inside server.

DirectiveDefaultMeaning
metrics-listennone (no metrics endpoint)Address and port for the Prometheus endpoint, for example "127.0.0.1:9090".
metrics-path"/metrics"Path of the endpoint. Must start with / and not contain ...
otlp-endpointnone (no export)Base URL of an OpenTelemetry collector's OTLP/HTTP receiver.
service-name"miraserve"service.name attribute attached to exported metrics.
redact-logs#trueRemove secrets from access logs. Turning it off produces warning W013.

Changes to metrics-listen, metrics-path and otlp-endpoint need a restart; a reload logs a warning and keeps the old values.

Prometheus endpoint

Prometheus is a monitoring system that periodically fetches ("scrapes") metrics over HTTP. With metrics-listen set, MiraServe opens a separate plain-HTTP listener for this purpose. It answers only GET and HEAD on metrics-path; every other path returns 404. It is not part of any site and cannot share a port with a listen address (check reports E102).

The metrics endpoint has no authentication and no TLS. Anyone who can reach the port can read it. Bind it to loopback (127.0.0.1 or [::1]) or to a private network interface that only your monitoring system can reach, and firewall the port. check warns with W012 when it is bound to a non-loopback address.

MetricTypeLabels
miraserve_http_requests_totalcounterprotocol (h1, h2, h3), status_class (1xx to 5xx)
miraserve_http_request_duration_secondshistogrambuckets from 1 ms to 5 s
miraserve_active_connectionsgauge
miraserve_tls_handshakes_totalcounterpqc (post-quantum key exchange used or not), isolation (in-process or split-daemon keys)
miraserve_security_blocks_totalcounterreason: rate_limit, anti_smuggling, site_preset, bot_auth, mcp_rbac, wasm_sandbox
miraserve_wasm_invocations_totalcounteroutcome: ok, fuel_exhausted, memory_limit, timeout, trap
miraserve_wasm_fuel_consumed_totalcounter

Metrics carry no host name, path or client labels, so they reveal nothing about individual requests.

OTLP export

OTLP (the OpenTelemetry Protocol) is the standard way to send telemetry to an OpenTelemetry collector. With otlp-endpoint set, MiraServe sends the same metrics every 30 seconds as JSON in an HTTP POST to <otlp-endpoint>/v1/metrics, plus a final send on shutdown. Use an https:// URL; a plain http:// URL to a non-loopback host produces warning W005.

Only metrics are exported. Traces and logs are not sent over OTLP, and no authentication header or client certificate can be configured for the collector, so restrict who can reach the collector's receiver by network instead.

Logs

MiraServe writes human-readable log lines to standard output, which systemd sends to the journal. Use miraserve run --log-file <path> to append to a file instead (it refuses symbolic links), and --log-level (default info) or the RUST_LOG variable to change verbosity.

Access log

One line per completed request, at info level:

INFO http request completed request_id=01M7TAWHX5Z2QWXXNGQXGQ9YXX proto="h2" method=GET target=/index.html?page=2&api_key=[REDACTED]&token=[REDACTED] status=200 latency_us=345 client_ip=Some(127.0.0.1) user_agent="curl/8.7.1" redacted=true

Fields: a request ID (also shown on MiraServe's error pages, so you can match a user's report to a log line), protocol, method, path and query, status, latency in microseconds, client IP and user agent. Request headers other than the user agent, cookies and bodies are not logged.

Security and audit logs

Security decisions are logged as they happen, for example sandbox status at startup, configuration reloads, and WASM plugin failures. The MCP gateway writes an audit record for every allow and deny decision, with tool arguments redacted as described on that page.

What is redacted

With redact-logs #true (the default):

  • Query parameters whose names contain token, secret, apikey, password, passwd, auth, signature, session, cookie, jwt or credential (after decoding and ignoring case, dashes and underscores), or that are, or end in, key, sig, code, pass, pwd or otp, have their values replaced with [REDACTED].
  • Any value that looks like a credential, such as Bearer or Basic credentials, a JWT, or an API key with a well-known prefix, is replaced, whatever its parameter name.
  • The user agent is replaced if it looks like a credential.
  • Control characters and line separators are always escaped, with or without redaction, so a request cannot forge extra log lines.

With redact-logs #false, paths, queries and user agents are logged as received (control characters still escaped).

Limits

  • The metrics endpoint has no authentication; protect it with its bind address and firewall.
  • OTLP export covers metrics only, uses JSON over HTTP, and has a fixed 30-second interval.
  • Log lines are text, not JSON. The MCP audit record is a JSON object inside a text line.
  • Redaction is pattern based. It removes common credential shapes; it cannot recognise every secret, so avoid putting secrets in URLs.