Hacktoberfest 2026 : les issues que les mainteneurs ont marquées pour octobre, ouvertes et accessibles aux débutants. Parcourir les issues Hacktoberfest

Telemetry subsystem design improvements (umbrella)

Ouverte
  • Quelque chose ne va pas ?
#294 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

Personne n'a encore pris cette issue.

Évaluation

Difficulté
5/5
Temps estimé
Plus d'une semaine
Accessibilité débutants
25/100
Type d'issue
Refactorisation
Clarté
Plutôt claire
Activité
À l'abandon
Stack technique
java
Domaine
backend-api-design, observability-sre

Piste de recherche

Commencez par Design Issue 2 et lisez src/main/java/dev/openfga/sdk/telemetry/Metrics.java, puis suivez la construction de la configuration à travers OpenFgaApi.java et HttpRequestAttempt.java. Examinez OAuth2Client.java et l’API TelemetryConfiguration au regard des six Design Issues listés. Le travail est considéré comme terminé lorsque les maintainers sont d’accord sur l’architecture coordonnée et que chaque changement sélectionné a des résultats définis en matière de compatibilité, de testabilité et de telemetry-spec.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

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
Langage dominant
Java
Étoiles
54
Forks
26
Merge moyen
2 j 7 h
PR mergées (30 j)
9

Préparer son environnement

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de openfga/java-sdk

Toutes les issues de openfga/java-sdk

Issues similaires

Plus d'issues Java

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.