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

Source: https://voxgig.com/howto/export-sdk-call-metrics-to-prometheus

- Audience: api-consumer
- Level: intermediate
- Languages: typescript, python
- Verified: 2026-11-22
- Published: 2026-11-22

## 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](https://github.com/siimon/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](https://heyapi.dev/docs/openapi/typescript/clients/fetch) | 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](https://openapi-ts.dev/openapi-fetch/middleware-auth) | 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](https://opentelemetry.io/docs/languages/js/exporters/) | 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](https://github.com/siimon/prom-client) | 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](https://github.com/voxgig/sdkgen/blob/main/docs/reference/features.md) | 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:

```aontu title="generated/metrics.aontu"
  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](https://github.com/voxgig/sdkgen/blob/main/docs/reference/features.md)
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:

```js title="sdkgen-metrics.mjs"
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:

```bash
node demo.mjs
```

```text output
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:

```js title="heyapi-metrics.mjs"
  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:

```bash
node cardinality.mjs
```

```text output
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](https://prometheus.io/docs/practices/naming/) 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:

```bash
node --test metrics.test.mjs
```

```text output
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

- [Choose the layer that instruments outbound API calls](/howto/choose-a-layer-to-instrument-outbound-calls)

- [Emit OpenTelemetry spans from a generated SDK](/howto/emit-opentelemetry-spans-from-a-generated-sdk)

- [Attribute API cost per operation and per caller in an SDK](/howto/attribute-api-cost-per-operation-and-caller)

- [Attribute API cost to a tenant from client-side metrics](/howto/attribute-api-cost-to-a-tenant)

- [Cap what an agent spends on the paid APIs its tools call](/howto/cap-what-an-agent-spends-on-apis)

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

[^1]: The reason phrase has been optional reading for some time.
[RFC 9112 section 4](https://www.rfc-editor.org/rfc/rfc9112.html#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](https://www.rfc-editor.org/rfc/rfc9113.html#section-8.3.2), and it
carries the status code. That section defines no field for a reason phrase.