Hacktoberfest 2026: die Issues, die Maintainer für den Oktober markiert haben – offen und einsteigerfreundlich. Hacktoberfest-Issues durchsuchen

Telemetry subsystem design improvements (umbrella)

Offen
  • Stimmt etwas nicht?
#294 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Maintainer antworten meist innerhalb von 1 Tag

Dieses Issue hat noch niemand übernommen.

Bewertung

Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Anfängerfreundlichkeit
25/100
Issue-Typ
Refactoring
Klarheit
Größtenteils klar
Aktivitätsstatus
Veraltet
Tech-Stack
java
Bereich
backend-api-design, observability-sre

Rechercherichtung

Beginnen Sie mit Design Issue 2 und lesen Sie src/main/java/dev/openfga/sdk/telemetry/Metrics.java, verfolgen Sie anschließend die Konstruktion der Konfiguration durch OpenFgaApi.java und HttpRequestAttempt.java. Prüfen Sie OAuth2Client.java und die TelemetryConfiguration API anhand der sechs aufgeführten Design Issues. Erledigt ist die Aufgabe, wenn die Maintainer der abgestimmten Architektur zustimmen und für jede ausgewählte Änderung die Ergebnisse in Bezug auf Kompatibilität, Testbarkeit und telemetry-spec festgelegt sind.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

enhancement

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:

  • #291 — All telemetry attributes exported as strings instead of correct types
  • #292 — Metrics constructor mutates the Configuration object passed to it
  • #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
Vorherrschende Sprache
Java
Sterne
54
Forks
26
Ø Merge
2 T. 15 Std.
Gemergte PRs (30 T.)
11

Entwicklungsumgebung

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus openfga/java-sdk

Alle Issues in openfga/java-sdk

Ähnliche Issues

Weitere Issues zu Java

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.