Telemetry subsystem design improvements (umbrella)

[jimmyjames]

Note: This analysis was performed by AI with human assistance. The criticisms and proposed solutions below may warrant further discussion before acting on them.

Context

PR #290 fixes the immediate issue from #209 (sharing a single Telemetry instance per SDK client). During a comprehensive audit of the telemetry subsystem, several additional design limitations were identified. This umbrella issue tracks the larger improvements that require coordinated refactoring.

Related standalone bug fixes

These can be addressed independently in small PRs:

• Bug: All telemetry attributes exported as strings instead of correct OTel types #291 — All telemetry attributes exported as strings instead of correct types
• Bug: Metrics constructor mutates the Configuration object passed to it #292 — Metrics constructor mutates the Configuration object passed to it
• Bug: No telemetry recorded for failed requests #293 — No telemetry recorded for failed requests

---

Design Issues

1. ConfigurationOverride telemetry settings are silently ignored

Files: OpenFgaApi.java, HttpRequestAttempt.java

Every OpenFgaApi method accepts a ConfigurationOverride. When used, it creates a new Configuration via this.configuration.override(configurationOverride). However, the shared this.telemetry was constructed from the original configuration. So if an override changes telemetry settings, those changes are silently ignored.

Options:

• A) Telemetry/Metrics methods accept a Configuration parameter at recording time (not just at construction)
• B) HttpRequestAttempt creates a request-scoped Telemetry when an override is detected
• C) Document that ConfigurationOverride does not affect telemetry (if acceptable)

2. Users cannot provide their own OpenTelemetry instance

File: src/main/java/dev/openfga/sdk/telemetry/Metrics.java:26

Metrics hardcodes GlobalOpenTelemetry.get().getMeterProvider().get("openfga-sdk"). Users have no way to pass their own OpenTelemetry or MeterProvider instance.

Problems:

• Forces global state — Users must call buildAndRegisterGlobal(). Non-global instances (common in multi-tenant setups, testing) silently produce no metrics.
• Violates OTel best practices — The OTel Java library instrumentation guide says libraries should accept an OpenTelemetry instance rather than using the global singleton.
• Untestable — No way to inject an in-memory meter for unit/integration tests.

Recommended fix: Allow ClientConfiguration to accept an optional OpenTelemetry instance, falling back to GlobalOpenTelemetry.get() if none is provided (backward-compatible):

ClientConfiguration config = new ClientConfiguration()
    .apiUrl("https://...")
    .openTelemetry(myOtelInstance);  // optional

3. OAuth2Client creates a separate Telemetry instance

File: src/main/java/dev/openfga/sdk/api/auth/OAuth2Client.java:44

OAuth2Client creates its own Configuration copy and its own Telemetry. While PR #290 fixed the per-request issue, the credentialsRequest counter (line 61) still records against OAuth2Client's own separate Metrics instance. Credential request counts may not aggregate correctly with the parent client's metrics if the OTel implementation is sensitive to meter identity.

4. Telemetry class is unnecessary indirection

Telemetry is a thin wrapper that only lazily creates a Metrics instance. If it's not going to provide additional facilities (traces, logs, spans), it could be collapsed into Metrics directly, simplifying the API.

5. Missing fga-client.request.count metric from spec

The cross-SDK telemetry spec includes fga-client.request.count as a counter (disabled by default). The Java SDK doesn't implement it. The Python SDK added it in PR #135. While disabled by default, it should exist for spec parity and for users who want to enable it.

6. Poor DX — TelemetryConfiguration API is hard to use

The current configuration API requires:

Map<Metric, Map<Attribute, Optional<Object>>>

Problems:

1. Unreadable type signature — Intimidating and hard to remember; 20+ lines of boilerplate for simple customization.
2. Optional<Object> serves no purpose — Every usage passes Optional.empty(). The data structure is effectively a Set<Attribute> disguised as a Map<Attribute, Optional<Object>>.
3. No builder/fluent API — No way to express .disableAttribute(Attributes.URL_FULL).
4. All-or-nothing customization — To disable a single attribute on a single metric, users must copy the default map, mutate it, and reconstruct the full metrics map.

Recommended improvement: Add a builder pattern:

TelemetryConfiguration.builder()
    .metric(Histograms.REQUEST_DURATION, attrs -> attrs
        .defaults()
        .without(Attributes.URL_FULL))
    .metric(Counters.CREDENTIALS_REQUEST)  // all defaults
    .build();

Or at minimum, provide helper methods like withoutAttribute(Metric, Attribute) and withoutMetric(Metric).

---

Suggested Approach

These design issues are interrelated and would benefit from coordinated refactoring. A suggested ordering:

1. Design Issue 2 (accept OpenTelemetry instance) — foundational, unblocks testability
2. Design Issue 4 (simplify Telemetry → Metrics) — reduces surface area for other changes
3. Design Issue 3 (OAuth2Client telemetry sharing) — depends on design decisions from above
4. Design Issue 1 (ConfigurationOverride telemetry) — requires clarity on config architecture
5. Design Issue 5 (add fga-client.request.count) — straightforward once plumbing is settled
6. Design Issue 6 (builder API for TelemetryConfiguration) — can be done at any point