Blockyard provides four observability mechanisms: structured logging, Prometheus metrics, OpenTelemetry tracing, and an append-only audit log.

Logging#

Blockyard writes structured JSON logs to stderr. Control verbosity with the log_level setting:

[server]
log_level = "info"   # trace, debug, info, warn, error

Or via environment variable:

BLOCKYARD_SERVER_LOG_LEVEL=debug

Log levels#

HTTP request logging#

All HTTP requests are logged automatically:

• Health probes (/healthz, /readyz) are logged at debug level to avoid noise in production
• Other requests are logged at info (2xx/3xx), warn (4xx), or error (5xx) based on the response status code

Each log entry includes method, path, status, and duration_ms.

Management listener#

By default, operational endpoints (/healthz, /readyz, /metrics) are served on the main listener alongside the application proxy and API. This means containers running untrusted Shiny app code can reach these endpoints.

For production deployments, configure a separate management listener bound to a loopback address:

[server]
bind            = "0.0.0.0:3838"
management_bind = "127.0.0.1:9100"

When management_bind is set:

• /healthz, /readyz, and /metrics move to the management listener and are removed from the main listener
• The management listener requires no authentication — access is controlled by the network binding (loopback = host-only)
• /readyz always returns full per-component check details
• Prometheus can scrape /metrics without a bearer token
• Container bridge networks cannot reach 127.0.0.1, so untrusted workloads cannot access operational data

When AppRole auth is used (openbao.role_id), /readyz also reports a vault_token check that reflects whether the token renewal goroutine is healthy. A stale or expired token degrades readiness, signaling the operator to re-bootstrap with a fresh secret_id.

Point your health checks and Prometheus scraper at the management port:

# prometheus.yml
scrape_configs:
  - job_name: blockyard
    static_configs:
      - targets: ['localhost:9100']

On shutdown, the management listener stops first (health probes fail, signaling load balancers to drain traffic), then the main listener is shut down gracefully.

Prometheus metrics#

Enable the /metrics endpoint in your configuration:

[telemetry]
metrics_enabled = true

When served on the main listener (no management_bind), the endpoint requires authentication (bearer token or session cookie). When served on the management listener, no authentication is required.

Available metrics#

Gauges:

Counters:

Histograms:

OpenTelemetry tracing#

Send distributed traces to an OpenTelemetry collector:

[telemetry]
otlp_endpoint = "http://otel-collector:4317"

The service name is blockyard. Spans include http.method, http.route, and http.status_code attributes. Endpoints using http://, localhost, or 127.0.0.1 connect without TLS; all others use TLS.

Security headers#

All HTTP responses include the following security headers:

API endpoints additionally set Content-Security-Policy: default-src 'none'; frame-ancestors 'none' and Cache-Control: no-store.

Audit logging#

Enable append-only audit logging to a JSONL file:

[audit]
path = "/data/audit/blockyard.jsonl"

Each line is a JSON object with the following fields:

Audit actions#

Buffering#

Audit entries are buffered in memory (up to 1000 entries) and flushed to disk by a background writer. If the buffer is full, new entries wait up to 500 ms for space before being dropped. Dropped entries increment the blockyard_audit_entries_dropped_total metric. Under normal load, entries are written within milliseconds.