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.
| Directive | Default | Meaning |
|---|---|---|
metrics-listen | none (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-endpoint | none (no export) | Base URL of an OpenTelemetry collector's OTLP/HTTP receiver. |
service-name | "miraserve" | service.name attribute attached to exported metrics. |
redact-logs | #true | Remove 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.
| Metric | Type | Labels |
|---|---|---|
miraserve_http_requests_total | counter | protocol (h1, h2, h3), status_class (1xx to 5xx) |
miraserve_http_request_duration_seconds | histogram | buckets from 1 ms to 5 s |
miraserve_active_connections | gauge | |
miraserve_tls_handshakes_total | counter | pqc (post-quantum key exchange used or not), isolation (in-process or split-daemon keys) |
miraserve_security_blocks_total | counter | reason: rate_limit, anti_smuggling, site_preset, bot_auth, mcp_rbac, wasm_sandbox |
miraserve_wasm_invocations_total | counter | outcome: ok, fuel_exhausted, memory_limit, timeout, trap |
miraserve_wasm_fuel_consumed_total | counter |
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,jwtorcredential(after decoding and ignoring case, dashes and underscores), or that are, or end in,key,sig,code,pass,pwdorotp, have their values replaced with[REDACTED]. - Any value that looks like a credential, such as
BearerorBasiccredentials, 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.