Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

Telemetry subsystem design improvements (umbrella)

Abierto
  • ¿Algo no está bien?
#294 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
25/100
Tipo de issue
Refactorización
Claridad
Bastante claro
Estado de actividad
Estancado
Stack tecnológico
java
Área
backend-api-design, observability-sre

Línea de trabajo

Comienza con Design Issue 2 y lee src/main/java/dev/openfga/sdk/telemetry/Metrics.java; después, sigue la construcción de la configuración a través de OpenFgaApi.java y HttpRequestAttempt.java. Revisa OAuth2Client.java y la API de TelemetryConfiguration en relación con los seis Design Issues enumerados. Se considera terminado cuando los maintainers estén de acuerdo con la arquitectura coordinada y cada cambio seleccionado tenga definidos sus resultados de compatibilidad, testabilidad y telemetry-spec.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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
Lenguaje dominante
Java
Estrellas
55
Forks
26
Merge medio
1 d 22 h
PR fusionados (30 d)
5

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de openfga/java-sdk

Todos los issues de openfga/java-sdk

Issues similares

Más issues de Java

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.