Telemetry hooks

Every generated client accepts an optional set of telemetry hooks — callbacks fired around each request so you can log, emit metrics, or open a trace span without wrapping the client. They are off unless you supply them, and add no overhead when absent.

import { Client } from 'glotto-sdk';

const client = new Client({
  hooks: {
    onRequest: ({ method, url }) => console.log('request', method, url),
    onResponse: ({ status, durationMs }) => console.log('response', status, durationMs),
  },
});

The callbacks

The hooks object accepts onRequest, onResponse, onError, and onRetry (named idiomatically per language — onRequest/onResponse in TypeScript, on_request/on_response in Python, OnRequest/OnResponse in Go). Each receives a telemetry context with the request method, URL, and — on the response side — the status and elapsed duration, so you can wire OpenTelemetry HTTP client spans or your own metrics pipeline.

Turning hooks off from the environment

Every generated client also reads OTEL_SDK_DISABLED from the process environment, once when the client is constructed. When it is set to true, the hooks you passed are ignored and no callback fires — so an operator can silence client-side telemetry in an environment without a code change or a redeploy of the calling service.

OTEL_SDK_DISABLED=true ./your-service

The value must be true, in any casing. true, TRUE and True all disable telemetry, in every one of the generated SDKs. Every other value leaves telemetry enabled, including 1, yes, 0, false, an empty value, and the variable being unset.

That 1 does not disable telemetry is deliberate and worth stating plainly, because it is the spelling most people try first. It is the rule OpenTelemetry’s own specification sets for this variable: it declares OTEL_SDK_DISABLED to be of the Boolean type, and defines that type as true only for the case-insensitive string true, with implementations explicitly forbidden from accepting anything wider. Following that rule is what makes the switch mean the same thing in a Glotto SDK as it does in the rest of your OpenTelemetry stack — your language agent, your auto-instrumentation, your collector — so one variable set once behaves the same everywhere. A Glotto SDK that also honoured 1 would disable itself while the conformant implementations beside it kept exporting, which is worse than not honouring it at all.

A value the SDK cannot read is not silent. Set it to anything that is neither true nor false — 1, yes, 0, a typo — and the client writes one line to your language’s warning channel when it is constructed, naming the value it ignored:

glotto: OTEL_SDK_DISABLED is set to 1, which is not a boolean; telemetry stays enabled. Only true (any casing) disables it.

It goes to the warning sink, never to standard output, so it cannot corrupt a program whose stdout carries a protocol: console.warn in TypeScript and React Native, logging in Python, standard error in Go, Ruby, Java, Kotlin, C#, Rust, Swift and Dart, error_log in PHP, IO.warn in Elixir. Nothing is written when the variable is unset, empty, true or false — a correct configuration produces no output at all, so the line only ever appears while there is something to fix.

Two further things follow from the kill switch being an environment setting rather than a config one, and both are deliberate:

• It is not a glotto.yml key, and you will not find it in your configuration. glotto.yml describes what gets generated; this decides what an already-generated client does at runtime, in a particular deployment. Baking it into the config would make silencing telemetry a regeneration.
• It is read once, at construction. Changing the variable in a running process does not affect a client that already exists — set it before the process starts.

Hooks vs. telemetry headers

These callbacks are a client-side observability seam and are distinct from client_settings.telemetry_headers — a separate, opt-in feature that makes every request send the X-Glotto-Retry-Count and X-Glotto-Timeout headers so your server can see the client’s retry state and timeout budget. Hooks observe locally; telemetry headers tell the server. See the glotto.yml reference for telemetry_headers.