Skip to content
wired guide

WebTransport stats endpoint

A server often wants its own WebTransport load visible as plain JSON, for a dashboard or a health check. This page answers GET /stats with two kinds of counters: how many sessions and streams are open right now, and how many have ever existed since boot.

Code

main.c
#define WIRED_MAIN
#include "wired.h"


/* GET /stats: wired_server_wt_occupancy is a point-in-time snapshot (what is
 * open right now); wired_srvrun_env_wt_usage is the cumulative total since
 * boot. peer_streams/streams count only client-opened WT streams. */
static int on_request(void* ctx, wired_http_exchange* x) {
  wired_srvrun_env* env = (wired_srvrun_env*)ctx;
  if (!wired_span_eq_cstr(wired_h3req_path(x->req), "/stats")) {
    x->status = 404;
    return 0;
  }


  wired_wt_occupancy occ = {0};
  wired_server_wt_occupancy(&occ);
  wired_srvrun_wt_usage usage = {0};
  wired_srvrun_env_wt_usage(env, &usage);


  x->body->len = 0;
  wired_obuf_printf(
      x->body,
      "{\"occupancy\":{\"sessions\":%lu,\"sessions_cap\":%lu,"
      "\"peer_streams\":%lu,\"peer_streams_cap\":%lu},"
      "\"usage\":{\"sessions\":%lu,\"streams\":%lu,\"datagrams\":%lu}}\n",
      occ.sessions, occ.sessions_cap, occ.peer_streams, occ.peer_streams_cap,
      usage.sessions, usage.streams, usage.datagrams);
  x->content_type = "application/json";
  return 1;
}


int wired_main(int argc, char** argv) {
  /* The same fixed demo identity as the HTTP/3 hello page. */
  static wired_srvboot_demo_keys keys;
  wired_srvboot_id               id;
  wired_srvboot_demo(&id, &keys, 0x50, "guide-st");


  /* wired_srvrun_env_wt_usage needs an addressable env, unlike the single
   * process-wide instance wired_server_run/wired_server_run_opt drive --
   * same one-instance mmap srvthreads.c uses for its per-worker envs. */
  i64 envsz = (i64)wired_srvrun_env_size();
  i64 base  = wired_arch_mmap(
      0, envsz, 0x3 /* PROT_READ|PROT_WRITE */,
      0x22 /* MAP_PRIVATE|MAP_ANONYMOUS */, -1, 0);
  if (base < 0) return 1;
  wired_srvrun_env* env = (wired_srvrun_env*)base;
  wired_srvrun_env_init(env);


  u16 port                 = (u16)wired_cliargs_int(argc, argv, "--port", 4433);
  wired_srvrun_handler h   = {.http = on_request, .ctx = env};
  wired_srvrun_obs     obs = {0};
  wired_srvrun_opt     opt = {0};
  opt.incoming_cpu         = -1;
  return wired_srvrun_serve_env(env, port, &id, h, obs, &opt) ? 0 : 1;
}

Output

Terminal window
$ ./h3-stats --port 4433
conn closed by peer (CONNECTION_CLOSE)
Terminal window
$ probe h3req 127.0.0.1:4433 GET /stats
status 200
content-type: application/json


{"occupancy":{"sessions":0,"sessions_cap":4,"peer_streams":0,"peer_streams_cap":132},"usage":{"sessions":0,"streams":0,"datagrams":0}}

How it works

Section titled “How it works”
  • wired_server_wt_occupancy(&occ) is a point-in-time snapshot: WT sessions and client-opened streams open right now, against the compile-time capacity each is bounded by. peer_streams counts only streams the client opened; streams the server itself opens are not counted.
  • wired_srvrun_env_wt_usage(env, &usage) is the cumulative total since wired_srvrun_env_init: every session ever established, every stream ever offered, every datagram ever received. It never decreases.
  • The cumulative counters need an env the app can address, so this page calls wired_srvrun_serve_env instead of wired_server_run_opt. The env is wired_srvrun_env_size() bytes, allocated once with wired_arch_mmap and handed to the HTTP handler as its ctx.
  • With no WebTransport client ever connecting, every counter in the JSON is 0 except the two compile-time capacities, which is exactly what this page’s golden output shows.