API Services TelemetryServiceInterface - evansims/openfga-php GitHub Wiki

Service interface for managing telemetry and observability in OpenFGA operations. This service provides a higher-level abstraction over the telemetry infrastructure, handling the creation, management, and coordination of telemetry spans, metrics, and events. It simplifies telemetry usage by providing business-focused methods that handle common patterns like operation timing and error tracking. ## Core Functionality The service manages the lifecycle of telemetry data for: - HTTP requests and responses with automatic span management - Business operations with timing and success/failure tracking - Error and exception handling with contextual information - Performance metrics and operational insights ## Usage Example php $telemetryService = new TelemetryService($telemetryProvider); Track a complete operation $context = $telemetryService->startOperation('check', $store, $model); try { $result = $businessLogic(); $telemetryService->recordSuccess($context, $result); return $result; } catch (Throwable $error) { $telemetryService->recordFailure($context, $error); throw $error; }

OpenFGA\Services

View source code

• TelemetryService (implementation)

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

Record an authentication event with duration and outcome. Tracks authentication-related operations including token acquisition, renewal, and validation. Provides insights into authentication performance and failure patterns.

View source

void

public function recordFailure(TelemetryContext $context, Throwable $exception, mixed $result = NULL): void

Record a failed operation with error details. Completes an operation context with failure information, including exception details and any additional error context. This provides structured error tracking for debugging and monitoring.

View source

void

public function recordHttpRequest(
    RequestInterface $request,
    ResponseInterface|null $response = NULL,
    Throwable|null $exception = NULL,
    float|null $duration = NULL,
): void

Record an HTTP request/response pair with automatic span management. Handles the complete lifecycle of HTTP request telemetry, including span creation, timing, and completion with response or error details. Ideal for tracking individual API calls.

View source

void

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

Record operational metrics for performance monitoring. Tracks operation-level metrics including timing, throughput, and contextual information about stores and models. Used for performance analysis and capacity planning.

View source

void

public function recordSuccess(TelemetryContext $context, mixed $result = NULL): void

Record a successful operation with results. Completes an operation context with success information and any relevant result data. This tracks successful operation patterns and performance characteristics.

View source

void

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

Start tracking a business operation. Creates a new telemetry context for tracking a complete business operation including timing, success/failure status, and contextual information. Returns a context object that should be passed to recordSuccess/recordFailure.

View source

TelemetryContext — Context for completing the operation tracking