Your dashboard shows one failed getItem an hour while the API provider bills you for three. The
SDK retried each failure twice, and the counter you added sits outside the retry, so it sees one
call where the provider saw three requests. The counter you labelled with the URL meanwhile holds
a series for every item id it has met.
What you get
You will end up with request, error, and latency series in Prometheus for three clients, counted per HTTP attempt and labelled by operation and status class, plus a test that scrapes them. This is for you if you call an API through an SDK and must see its traffic.
Short answer
Count requests where each HTTP attempt passes: a transport wrapper in an sdkgen client, an
interceptor in Hey API, or a middleware in openapi-fetch. Write a prom-client counter and histogram
labelled by operation and status class, and serve the registry on /metrics. The sdkgen metrics
feature counts each call once, retries included, so place the wrapper inside retry to count
attempts.
You will need
Node 22.18 or later, which runs the .ts file here directly, and an SDK client whose calls you
want counted. The document here, api.json, is a three-operation Stock API, and a stand-in for it
runs on 127.0.0.1. The registry is prom-client, served on
an address this process opens, so no Prometheus server is needed to check the text it scrapes.
The code is TypeScript and JavaScript: the leaf’s Python route, prometheus_client, was not run.
Verified 2026-11-22 against Node 22.23.5.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| Hey API interceptors | A Hey API client, where request, response, and error interceptors see each request | A meter you write, and the client sent a 503 back without retrying, so one request per call | The client must retry, and attempts must be counted |
| openapi-typescript and openapi-fetch middleware | A typed fetch client whose middleware receives the path template as schemaPath | A meter you write, and the 503 here reached the caller unrepeated, so a request is a call | You want metrics that need no code beside the client |
| OpenTelemetry metrics with the Prometheus exporter | Metrics, traces, and logs share one pipeline that may leave Prometheus later | An SDK, an exporter package, and its own scrape port, 9464 by default | One process, one registry, and no plan beyond Prometheus |
| prom-client counters in a transport wrapper | A generated client with a transport seam that each attempt passes through | Placement matters: outside the retry the wrapper counts calls, not attempts | The client exposes no transport seam |
| sdkgen metrics feature | You generate the SDK with sdkgen and want per-operation counts with no code | Once per call, no status class, and no buckets; you export it yourself | You need attempts, status classes, or latency buckets |
Voxgig maintains sdkgen; the table gives it two rows, and neither is the recommendation.
Hey API and openapi-fetch hand you a seam per request and no retry, so a request is a call. The sdkgen client retries, so a call can be several requests, and the seam you pick decides which you count. OpenTelemetry buys a vendor-neutral pipeline at the price of more packages than prom-client.
Read what the sdkgen metrics feature counts
The feature’s model file in the generated project turns it off by default and hooks three stages of each operation call:
config: {
options: {
active: false
}
}
hook: {
PrePoint: active: true
PreDone: active: true
PreUnexpected: active: true
}
Turn it on with feature: { metrics: { active: true } } in the constructor. The
features reference
documents the result as client._metrics, a total and one bucket per <entity>.<op>, each
{ count, ok, err, totalMs, maxMs }. That is a call count with a pass or fail, kept without a
status code or latency buckets. count-probe.cjs, run by generate.sh on 4.44.3 and on 4.45.0,
sent one call whose first attempt got a 503, with the features given four ways. Each sent two
requests and counted one call.
The feature map, in either key order, adds metrics before retry, because the client sorts the
names. The array form [retry, metrics] reverses that order, and the count stays at one: the
feature records at PrePoint and PreDone, once per operation call, outside the transport.
Count every attempt at the transport seam
The sdkgen client takes an object in extend. With an init method and an active entry under its
name in feature, it can wrap ctx.utility.fetcher, the transport every attempt passes through.
__before__: 'retry' puts it inside the retry feature, so each attempt reaches it, labelled with
the model’s operation name. In the probe it counted two requests for the retried call. Without
__before__ it counted one, and without the prommeter entry it counted zero, because init
never ran:
export function attemptMeter({ requests, duration }, client = 'sdkgen') {
return {
name: 'prommeter',
_options: { __before__: 'retry' },
init(ctx) {
const inner = ctx.utility.fetcher
ctx.utility.fetcher = async (callctx, url, fetchdef) => {
// The operation name comes from the model, so the label set is fixed by the API.
const operation = `${callctx.op?.entity ?? 'unknown'}.${callctx.op?.name ?? 'unknown'}`
const end = duration.startTimer({ client, operation })
let status
try {
const res = await inner(callctx, url, fetchdef)
status = res instanceof Error ? undefined : res?.status
return res
} finally {
end()
requests.inc({ client, operation, status_class: statusClass(status) })
}
}
},
}
}
demo.mjs makes three calls through each client against a stand-in that answers the first
request for item i1 with a 503. It then scrapes the /metrics endpoint the process serves:
node demo.mjs
api_client_requests_total
client=hey-api operation=GET /items status_class=2xx 1
client=hey-api operation=GET /items/{itemId} status_class=4xx 1
client=hey-api operation=GET /items/{itemId} status_class=5xx 1
client=openapi-fetch operation=GET /items status_class=2xx 1
client=openapi-fetch operation=GET /items/{itemId} status_class=4xx 1
client=openapi-fetch operation=GET /items/{itemId} status_class=5xx 1
client=sdkgen operation=item.list status_class=2xx 1
client=sdkgen operation=item.load status_class=2xx 1
client=sdkgen operation=item.load status_class=4xx 1
client=sdkgen operation=item.load status_class=5xx 1
sdkgen_metrics_calls_total
operation=item.list outcome=err 0
operation=item.list outcome=ok 1
operation=item.load outcome=err 1
operation=item.load outcome=ok 1
requests the stand-in received: sdkgen 4, hey-api 3, openapi-fetch 3
The sdkgen client retried the 503, so the wrapper counted four requests while the feature, read
by featureCollector, counted three calls. Hey API and openapi-fetch do not retry, so their 503
reached the caller and each request was a call.
Write the same counters from Hey API and openapi-fetch
Hey API’s client takes request, response, and error interceptors. The request interceptor’s second
argument carries the SDK function’s path template as url. Its error interceptors also run for a
non-2xx answer, which the response interceptor has already counted, so this meter counts there
only when no response arrived:
c.interceptors.request.use((request, opts) => {
// opts.url is the template an SDK function passes, or any path a caller wrote by hand.
const operation = operationLabel(request.method, opts.url)
open.set(request, { operation, end: duration.startTimer({ client, operation }) })
return request
})
c.interceptors.response.use((response, request) => {
finish(request, response.status)
return response
})
// An error with no response is a request that never got one.
c.interceptors.error.use((error, response, request) => {
if (!response && request) finish(request, undefined)
return error
})
openapi-fetch’s middleware gets onRequest, onResponse, and onError, each with the request’s
id, and onRequest also gets the path template as schemaPath. openapi-fetch-metrics.ts keys an open timer by id and writes the
same two metrics, and a test type-checks it against the types openapi-typescript wrote. Neither
client retried a request in the demo, so in both a request is a call.
Keep the label set bounded
Every distinct set of label values is one series. cardinality.mjs sends fifty requests for missing
items through openapi-fetch and labels them three ways:
node cardinality.mjs
50 lookups of missing items, answered with status 404
label series example
full URL 50 {"url":"/v1/items/i100"}
status message 50 {"message":"No item i100"}
operation and status class 1 {"operation":"GET /items/{itemId}","status_class":"4xx"}
The stand-in writes the item id into its reason phrase, as some servers do with a request id, so
the status message is as unbounded as the URL.1 Prometheus’s
naming practices say not to use labels for
unbounded sets of values. A path template is bounded by the document only when it comes from it.
openapi-fetch’s schemaPath and Hey API’s url hold whatever path the caller passed, so
operationLabel in prom.mjs turns a path the document lacks into other. A status outside 200
to 599 becomes error.
Check it worked
The tests scrape /metrics after each scenario and assert on the counter values, the histogram
counts, and the label sets:
node --test metrics.test.mjs
1..13
# tests 13
# suites 0
# pass 13
# fail 0
# cancelled 0
# skipped 0
# todo 0
One sends a call whose first two attempts fail and expects three requests, two of them 5xx,
beside one call in the feature. Another checks the text itself: a # TYPE line per family,
escaped label values, and a histogram with its +Inf bucket, _sum, and _count.
When it goes wrong
The counter matches the calls and the provider’s bill does not. The meter wraps the retry instead
of sitting inside it. Without __before__: 'retry' the same object is added after retry and
sees one attempt per call, which a test shows.
A failed call counts twice in Hey API. Its error interceptors run for a 4xx or 5xx answer too. Count in the response interceptor, and in the error interceptor only when there is no response.
The series count climbs every hour. A label holds an id, a URL, or a reason phrase. Label by operation and status class, and log the detail instead.
When not to do this
Do not add a client-side meter when the API provider already exports request metrics per consumer that you can scrape or query. Two counts of one request then need reconciling, and the provider’s count is the one on the bill.
Do not use the sdkgen metrics feature as a request counter. It counts calls, keeps no status
code, and needs a collector to reach Prometheus. Pick Hey API or openapi-fetch when you want a
TypeScript client with an obvious per-request seam and you can live without retries. Pick
OpenTelemetry when the metrics must also leave for a vendor that is not Prometheus.
Do not label by tenant here. Bounded per-tenant labels need their own budget, and an open-ended tenant list is the same problem as an item id.
Related how-tos
Last verified
Verified 2026-11-22 against Node 22.23.5, @voxgig/create-sdkgen 0.31.9 with @voxgig/sdkgen
4.44.3, and 4.45.0 for the call count, @hey-api/openapi-ts 0.99.0, openapi-fetch 0.17.0, and
prom-client 15.1.3. Every output block is what the command preceding it printed. The clients were
generated once, in generate.sh, and committed. The OpenTelemetry row was read from its
documentation and not run.
Footnotes
-
The reason phrase has been optional reading for some time. RFC 9112 section 4 tells a client to ignore it, because it might be translated, overwritten by intermediaries, or discarded when the message passes through other versions of HTTP. For a response, HTTP/2 defines one pseudo-header,
:status, in RFC 9113 section 8.3.2, and it carries the status code. That section defines no field for a reason phrase. ↩︎ Back to text