API Observability TelemetryInterface - evansims/openfga-php GitHub Wiki

Interface for OpenTelemetry integration in the OpenFGA SDK. This interface provides methods for instrumenting OpenFGA operations with observability features including distributed tracing, metrics collection, and structured logging. Implementations should integrate with OpenTelemetry or other observability platforms to provide insights into SDK performance and operation outcomes. The interface supports both automatic instrumentation of HTTP requests and business-level instrumentation of OpenFGA API operations. All methods are designed to be safe to call even when no telemetry backend is configured, ensuring the SDK remains functional without observability dependencies.

OpenFGA\Observability

View source code

public function endHttpRequest(
    object|null $span,
    ResponseInterface|null $response = NULL,
    Throwable|null $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|null $span,
    bool $success,
    Throwable|null $exception = NULL,
    array<string, mixed> $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<string, mixed> $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,
    StoreInterface|string $store,
    AuthorizationModelInterface|string|null $model = NULL,
    array<string, mixed> $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|null $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<string, mixed> $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(RequestInterface $request): object|null

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 | null — A span identifier or context that can be passed to endHttpRequest()

public function startOperation(
    string $operation,
    StoreInterface|string $store,
    AuthorizationModelInterface|string|null $model = NULL,
    array<string, mixed> $attributes = [],
): object|null

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 | null — A span identifier or context that can be passed to endOperation()