API Observability OpenTelemetryProvider - evansims/openfga-php GitHub Wiki

OpenTelemetry implementation for OpenFGA SDK observability. This class provides comprehensive telemetry capabilities for the OpenFGA SDK using OpenTelemetry APIs. It creates structured traces for all operations, records performance metrics, and tracks reliability indicators such as retry attempts and circuit breaker state changes. The implementation follows OpenTelemetry semantic conventions for HTTP clients and RPC operations, ensuring compatibility with standard observability tools and platforms. All telemetry is optional and gracefully degrades when OpenTelemetry is not configured.

OpenFGA\Observability

View source code

• TelemetryInterface

public function endHttpRequest(
    ?object $span,
    ?Psr\Http\Message\ResponseInterface $response = NULL,
    ?Throwable $exception = NULL,
): void

End tracing for an HTTP request. Completes the HTTP request span, recording the response status and any errors that occurred. The span should include standard HTTP response attributes such as status code and response size.

View source

void

public function endOperation(
    ?object $span,
    bool $success,
    ?Throwable $exception = NULL,
    array $attributes = [],
): void

End tracing for an OpenFGA API operation. Completes the trace span started with startOperation(), recording the operation outcome and any relevant metrics. If an exception occurred during the operation, it should be recorded in the span.

View source

void

public function recordAuthenticationEvent(
    string $event,
    bool $success,
    float $duration,
    array $attributes = [],
): void

Record authentication events. Records metrics and traces related to authentication flows, including token acquisition, refresh operations, and authentication failures. This helps monitor authentication performance and troubleshoot auth issues.

View source

void

public function recordCircuitBreakerState(
    string $endpoint,
    string $state,
    int $failures,
    float $failureRate,
): void

Record circuit breaker state changes. Records metrics about circuit breaker state transitions and failure rates. This helps monitor the health of individual API endpoints and the SDK's resilience mechanisms.

View source

void

public function recordOperationMetrics(
    string $operation,
    float $duration,
    OpenFGA\Models\StoreInterface|string $store,
    ?OpenFGA\Models\AuthorizationModelInterface|string|null $model = NULL,
    array $attributes = [],
): void

Record performance metrics for OpenFGA operations. Records timing and throughput metrics for OpenFGA API operations, allowing monitoring of operation latency and identifying performance bottlenecks or degradations.

View source

void

public function recordRetryAttempt(
    string $endpoint,
    int $attempt,
    int $delayMs,
    string $outcome,
    ?Throwable $exception = NULL,
): void

Record retry attempt metrics. Records metrics about retry attempts, including the retry count, delay, and eventual outcome. This helps track the reliability and performance of API requests under various network conditions.

View source

void

public function recordSpan(string $name, array $attributes = []): void

Record a telemetry span with attributes. Records a complete telemetry span for events that don't require start/end semantics. This is useful for event-driven telemetry where the event represents a point in time rather than a duration.

View source

void

public function startHttpRequest(Psr\Http\Message\RequestInterface $request): object

Start tracing an HTTP request. Creates a new trace span for an outgoing HTTP request to the OpenFGA API. The span should follow OpenTelemetry semantic conventions for HTTP client operations, including standard HTTP attributes.

View source

object — A span identifier or context that can be passed to endHttpRequest()

public function startOperation(
    string $operation,
    OpenFGA\Models\StoreInterface|string $store,
    ?OpenFGA\Models\AuthorizationModelInterface|string|null $model = NULL,
    array $attributes = [],
): object

Start tracing an OpenFGA API operation. Creates a new trace span for a high-level OpenFGA operation such as check, expand, or write operations. The span should include relevant attributes such as store ID, authorization model ID, and operation-specific metadata.

View source

object — A span identifier or context that can be passed to endOperation()