Server Logging#

The server writes text logs to standard error by default. Select JSON output with --log-format json:

$ vl-convert serve \
>   --log-format json --log-level info \
>   --port 3000

--log-filter accepts a tracing-subscriber directive and takes priority over --log-level. Use it when one component needs more detail:

$ vl-convert serve \
>   --log-format json \
>   --log-filter 'vl_convert=debug,tower_http=info' \
>   --port 3000

Debug logs include more detail and can contain resource names or error details.

Request Fields#

Each JSON response event contains standard request context:

Field

Meaning

http.method

Request method

http.url

Request path and query

http.version

HTTP protocol version

http.useragent

Caller user agent

http.request_id

Request correlation identifier

http.status_code

Response status

response_time_ms

Request latency in milliseconds

trace_id, span_id

Incoming W3C trace context, when supplied

When render-time budgets are enabled, response events also contain:

Field

Meaning

budget.outcome

accepted, rejected_per_ip, rejected_global, or refunded_on_drop

budget.charged_ms

Settled charge, or the refunded hold when the outcome is refunded_on_drop

budget.elapsed_ms

Measured processing time

budget.font_cache_miss_penalty_ms

Added Google Fonts charge

budget.global_remaining_ms

Shared capacity after the request

budget.ip_remaining_ms

Client capacity after the request

budget.client_ip

Address used for per-IP accounting

Font work adds google_font.css_cache_misses, google_font.file_cache_misses, google_font.downloaded_bytes, and google_font.resolved_variants.

Correlate a Request#

The server returns an X-Request-Id header with each response. With --log-format json, the same value appears in server logs as http.request_id. Use it to find the logs for a request.

The server generates an ID when the request does not include one. To supply your own request ID:

$ curl -i http://127.0.0.1:3000/themes \
>   -H 'X-Request-Id: render-01'

Vega Diagnostics#

Successful render, compilation, HTML, and scenegraph responses also carry X-VLC-Logs, a JSON array of up to 50 Vega diagnostic messages. Inspect it when a chart renders but Vega reported warnings. URL and font-inspection responses do not include this header.