How-to › Operate integrations in production

How to export SDK call metrics to Prometheus#

Count every SDK request, error, and latency in Prometheus by operation and status class, once per retry attempt, and keep the label set bounded.

Audience
API consumer
Level
intermediate
Topic
Instrument and meter API calls
Languages
TypeScript and Python
Verified

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
Hey API interceptorsA Hey API client, where request, response, and error interceptors see each requestA meter you write, and the client sent a 503 back without retrying, so one request per callThe client must retry, and attempts must be counted
openapi-typescript and openapi-fetch middlewareA typed fetch client whose middleware receives the path template as schemaPathA meter you write, and the 503 here reached the caller unrepeated, so a request is a callYou want metrics that need no code beside the client
OpenTelemetry metrics with the Prometheus exporterMetrics, traces, and logs share one pipeline that may leave Prometheus laterAn SDK, an exporter package, and its own scrape port, 9464 by defaultOne process, one registry, and no plan beyond Prometheus
prom-client counters in a transport wrapperA generated client with a transport seam that each attempt passes throughPlacement matters: outside the retry the wrapper counts calls, not attemptsThe client exposes no transport seam
sdkgen metrics featureYou generate the SDK with sdkgen and want per-operation counts with no codeOnce per call, no status class, and no buckets; you export it yourselfYou 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.

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

  1. 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

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.