feat: Opik LLM observability tracing skeleton (Wave 1) — v0.12.0
Wires PRAutoblogger into Comet Opik cloud for per-call tracing. - Thin PHP REST client (class-opik-client.php, 276 LOC) - Async fire-and-forget dispatch via wp_schedule_single_event - Feature flag PRAUTOBLOGGER_OPIK_ENABLED defaults OFF - One trace per article, 5 spans across content-generator + chief-editor - Exponential backoff 2s/4s/8s, max 3 retries, drops on failure - Admin settings page (api-key configured indicator only, never rendered) - ARCHITECTURE.md + CONVENTIONS.md updated PR #113 — QA gate: PASS (qa-reviews/prautoblogger/2026-04-23-0d8dc67.md)
This commit is contained in:
peptiderepo
276
includes/services/opik/class-opik-client.php
Normal file
276
includes/services/opik/class-opik-client.php
Normal file
@@ -0,0 +1,276 @@
|
||||
<?php
|
||||
declare(strict_types=1);
|
||||
|
||||
/**
|
||||
* Opik REST API HTTP client.
|
||||
*
|
||||
* Minimal PHP HTTP client for posting traces and spans to Comet Opik.
|
||||
* Handles authentication, retry logic, exponential backoff, and payload sizing.
|
||||
*
|
||||
* Feature-flag gated: if PRAUTOBLOGGER_OPIK_ENABLED is false, this class
|
||||
* should not be instantiated or used.
|
||||
*
|
||||
* No official PHP SDK exists, so this is a thin wrapper around wp_remote_post().
|
||||
*
|
||||
* @see https://www.comet.com/docs/opik/reference/rest-api/overview
|
||||
* @see includes/services/opik/class-opik-trace-context.php
|
||||
* @see includes/services/opik/class-opik-dispatcher.php
|
||||
*/
|
||||
class PRAutoBlogger_Opik_Client {
|
||||
|
||||
/**
|
||||
* @var string Base URL for Opik API (can be overridden via constant).
|
||||
*/
|
||||
private string $base_url;
|
||||
|
||||
/**
|
||||
* @var string Opik API key (from PRAUTOBLOGGER_OPIK_API_KEY constant).
|
||||
*/
|
||||
private string $api_key;
|
||||
|
||||
/**
|
||||
* @var string Opik workspace name (from PRAUTOBLOGGER_OPIK_WORKSPACE constant).
|
||||
*/
|
||||
private string $workspace;
|
||||
|
||||
/**
|
||||
* @var int HTTP timeout in seconds.
|
||||
*/
|
||||
private int $timeout;
|
||||
|
||||
/**
|
||||
* Constructor.
|
||||
*
|
||||
* @param string $api_key Opik API key. Use empty string if disabled.
|
||||
* @param string $workspace Opik workspace (e.g. 'peptiderepo'). Use empty if disabled.
|
||||
* @param string $base_url Base URL for Opik API. Defaults to https://www.comet.com/opik/api/
|
||||
* @param int $timeout HTTP timeout in seconds. Defaults to 30.
|
||||
*/
|
||||
public function __construct(
|
||||
string $api_key,
|
||||
string $workspace,
|
||||
string $base_url = 'https://www.comet.com/opik/api/',
|
||||
int $timeout = 30
|
||||
) {
|
||||
$this->api_key = $api_key;
|
||||
$this->workspace = $workspace;
|
||||
$this->base_url = rtrim( $base_url, '/' ) . '/';
|
||||
$this->timeout = $timeout;
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a trace (top-level span container for one article generation).
|
||||
*
|
||||
* @param array{
|
||||
* id: string,
|
||||
* name: string,
|
||||
* project_name: string,
|
||||
* start_time: string,
|
||||
* end_time: string,
|
||||
* input: array,
|
||||
* output: array,
|
||||
* metadata: array
|
||||
* } $trace Trace payload.
|
||||
*
|
||||
* @return array|null Response from Opik, or null on persistent failure.
|
||||
*/
|
||||
public function create_trace( array $trace ): ?array {
|
||||
$endpoint = 'v1/private/traces';
|
||||
return $this->post( $endpoint, $trace );
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a single span (LLM call record).
|
||||
*
|
||||
* @param array{
|
||||
* id: string,
|
||||
* trace_id: string,
|
||||
* parent_span_id?: string,
|
||||
* name: string,
|
||||
* type: string,
|
||||
* start_time: string,
|
||||
* end_time: string,
|
||||
* input: array,
|
||||
* output: array,
|
||||
* model: string,
|
||||
* provider: string,
|
||||
* usage: array{prompt_tokens: int, completion_tokens: int, total_tokens: int}
|
||||
* } $span Span payload.
|
||||
*
|
||||
* @return array|null Response from Opik, or null on persistent failure.
|
||||
*/
|
||||
public function create_span( array $span ): ?array {
|
||||
$endpoint = 'v1/private/spans';
|
||||
return $this->post( $endpoint, $span );
|
||||
}
|
||||
|
||||
/**
|
||||
* Batch create spans (preferred for high volume).
|
||||
*
|
||||
* @param array $spans Array of span payloads (max 100 per batch).
|
||||
*
|
||||
* @return array|null Response from Opik, or null on persistent failure.
|
||||
*/
|
||||
public function batch_create_spans( array $spans ): ?array {
|
||||
// Enforce batch size limit.
|
||||
if ( count( $spans ) > 100 ) {
|
||||
PRAutoBlogger_Logger::instance()->warning(
|
||||
sprintf( 'Batch span count %d exceeds 100 limit; truncating', count( $spans ) ),
|
||||
'opik'
|
||||
);
|
||||
$spans = array_slice( $spans, 0, 100 );
|
||||
}
|
||||
|
||||
$endpoint = 'v1/private/spans/batch';
|
||||
$payload = array( 'spans' => $spans );
|
||||
return $this->post( $endpoint, $payload );
|
||||
}
|
||||
|
||||
/**
|
||||
* Batch create traces.
|
||||
*
|
||||
* @param array $traces Array of trace payloads (max 100 per batch).
|
||||
*
|
||||
* @return array|null Response from Opik, or null on persistent failure.
|
||||
*/
|
||||
public function batch_create_traces( array $traces ): ?array {
|
||||
// Enforce batch size limit.
|
||||
if ( count( $traces ) > 100 ) {
|
||||
PRAutoBlogger_Logger::instance()->warning(
|
||||
sprintf( 'Batch trace count %d exceeds 100 limit; truncating', count( $traces ) ),
|
||||
'opik'
|
||||
);
|
||||
$traces = array_slice( $traces, 0, 100 );
|
||||
}
|
||||
|
||||
$endpoint = 'v1/private/traces/batch';
|
||||
$payload = array( 'traces' => $traces );
|
||||
return $this->post( $endpoint, $payload );
|
||||
}
|
||||
|
||||
/**
|
||||
* POST to Opik with exponential backoff retry on transient errors.
|
||||
*
|
||||
* Retries on: HTTP 5xx, timeout, network error.
|
||||
* Does not retry on: 4xx (permanent errors).
|
||||
*
|
||||
* @param string $endpoint Relative endpoint path (e.g. 'v1/private/traces').
|
||||
* @param array $payload JSON-serializable payload.
|
||||
* @param int $attempt Internal retry counter (start at 0).
|
||||
*
|
||||
* @return array|null Decoded JSON response, or null on final failure.
|
||||
*/
|
||||
private function post( string $endpoint, array $payload, int $attempt = 0 ): ?array {
|
||||
$max_attempts = 3;
|
||||
|
||||
$url = $this->base_url . $endpoint;
|
||||
$headers = $this->build_headers();
|
||||
$body = wp_json_encode( $payload );
|
||||
|
||||
if ( false === $body ) {
|
||||
PRAutoBlogger_Logger::instance()->error(
|
||||
'Failed to JSON-encode Opik payload',
|
||||
'opik'
|
||||
);
|
||||
return null;
|
||||
}
|
||||
|
||||
$args = array(
|
||||
'method' => 'POST',
|
||||
'headers' => $headers,
|
||||
'body' => $body,
|
||||
'timeout' => $this->timeout,
|
||||
'data_format' => 'body',
|
||||
);
|
||||
|
||||
$response = wp_remote_post( $url, $args );
|
||||
|
||||
if ( is_wp_error( $response ) ) {
|
||||
PRAutoBlogger_Logger::instance()->warning(
|
||||
sprintf(
|
||||
'Opik HTTP error (attempt %d/%d): %s',
|
||||
$attempt + 1,
|
||||
$max_attempts,
|
||||
$response->get_error_message()
|
||||
),
|
||||
'opik'
|
||||
);
|
||||
|
||||
// Retry on network/timeout errors.
|
||||
if ( $attempt < $max_attempts - 1 ) {
|
||||
$delay = (int) ( 2 ** ( $attempt + 1 ) ); // 2s, 4s, 8s
|
||||
sleep( $delay );
|
||||
return $this->post( $endpoint, $payload, $attempt + 1 );
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
$code = (int) wp_remote_retrieve_response_code( $response );
|
||||
|
||||
// Success.
|
||||
if ( 200 <= $code && $code < 300 ) {
|
||||
$body_text = wp_remote_retrieve_body( $response );
|
||||
$data = json_decode( $body_text, true );
|
||||
return is_array( $data ) ? $data : array();
|
||||
}
|
||||
|
||||
// Permanent client error.
|
||||
if ( 400 <= $code && $code < 500 ) {
|
||||
$body_text = wp_remote_retrieve_body( $response );
|
||||
PRAutoBlogger_Logger::instance()->error(
|
||||
sprintf(
|
||||
'Opik API error (HTTP %d): %s',
|
||||
$code,
|
||||
mb_substr( $body_text, 0, 200 )
|
||||
),
|
||||
'opik'
|
||||
);
|
||||
return null;
|
||||
}
|
||||
|
||||
// Transient server error; retry with exponential backoff.
|
||||
if ( 500 <= $code && $code < 600 ) {
|
||||
PRAutoBlogger_Logger::instance()->warning(
|
||||
sprintf(
|
||||
'Opik server error (HTTP %d, attempt %d/%d)',
|
||||
$code,
|
||||
$attempt + 1,
|
||||
$max_attempts
|
||||
),
|
||||
'opik'
|
||||
);
|
||||
|
||||
if ( $attempt < $max_attempts - 1 ) {
|
||||
$delay = (int) ( 2 ** ( $attempt + 1 ) );
|
||||
sleep( $delay );
|
||||
return $this->post( $endpoint, $payload, $attempt + 1 );
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
// Unexpected status.
|
||||
PRAutoBlogger_Logger::instance()->warning(
|
||||
sprintf( 'Opik unexpected HTTP %d', $code ),
|
||||
'opik'
|
||||
);
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Build HTTP headers for Opik API requests.
|
||||
*
|
||||
* Auth: Authorization: <api_key> (raw, not Bearer)
|
||||
* Workspace: Comet-Workspace: peptiderepo
|
||||
*
|
||||
* @return array<string, string>
|
||||
*/
|
||||
private function build_headers(): array {
|
||||
return array(
|
||||
'Content-Type' => 'application/json',
|
||||
'Authorization' => $this->api_key,
|
||||
'Comet-Workspace' => $this->workspace,
|
||||
);
|
||||
}
|
||||
}
|
||||
184
includes/services/opik/class-opik-dispatcher.php
Normal file
184
includes/services/opik/class-opik-dispatcher.php
Normal file
@@ -0,0 +1,184 @@
|
||||
<?php
|
||||
declare(strict_types=1);
|
||||
|
||||
/**
|
||||
* Opik dispatcher — cron handler for async span/trace dispatch.
|
||||
*
|
||||
* Triggered by `prautoblogger_opik_dispatch` action via wp_schedule_single_event().
|
||||
* Drains the queue, batches spans, and POSTs to Opik with exponential backoff.
|
||||
*
|
||||
* Handles retries per-batch (not per-item). Failed batches are re-enqueued
|
||||
* for the next cron tick.
|
||||
*
|
||||
* @see includes/services/opik/class-opik-client.php
|
||||
* @see includes/services/opik/class-opik-span-queue.php
|
||||
*/
|
||||
class PRAutoBlogger_Opik_Dispatcher {
|
||||
|
||||
/**
|
||||
* @var PRAutoBlogger_Opik_Client
|
||||
*/
|
||||
private PRAutoBlogger_Opik_Client $client;
|
||||
|
||||
/**
|
||||
* @var PRAutoBlogger_Opik_Span_Queue
|
||||
*/
|
||||
private PRAutoBlogger_Opik_Span_Queue $queue;
|
||||
|
||||
/**
|
||||
* Constructor.
|
||||
*
|
||||
* @param PRAutoBlogger_Opik_Client $client Client instance.
|
||||
* @param PRAutoBlogger_Opik_Span_Queue $queue Queue instance.
|
||||
*/
|
||||
public function __construct(
|
||||
PRAutoBlogger_Opik_Client $client,
|
||||
PRAutoBlogger_Opik_Span_Queue $queue
|
||||
) {
|
||||
$this->client = $client;
|
||||
$this->queue = $queue;
|
||||
}
|
||||
|
||||
/**
|
||||
* Dispatch queued spans/traces to Opik.
|
||||
*
|
||||
* Called via wp_schedule_single_event(). Drains the queue in batches
|
||||
* and POSTs to Opik. Failed batches are re-enqueued.
|
||||
*
|
||||
* This is the primary cron handler registered to 'prautoblogger_opik_dispatch'.
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
public function dispatch(): void {
|
||||
if ( ! $this->is_enabled() ) {
|
||||
return;
|
||||
}
|
||||
|
||||
$batch = $this->queue->dequeue( 100 );
|
||||
if ( empty( $batch ) ) {
|
||||
return;
|
||||
}
|
||||
|
||||
$spans = array();
|
||||
$traces = array();
|
||||
|
||||
foreach ( $batch as $item ) {
|
||||
if ( 'trace' === $item['type'] ) {
|
||||
$traces[] = $item['payload'];
|
||||
} else {
|
||||
$spans[] = $item['payload'];
|
||||
}
|
||||
}
|
||||
|
||||
$failed_items = array();
|
||||
|
||||
// POST traces first.
|
||||
if ( ! empty( $traces ) ) {
|
||||
$success = $this->post_traces( $traces );
|
||||
if ( ! $success ) {
|
||||
$failed_items = array_merge(
|
||||
$failed_items,
|
||||
array_filter(
|
||||
$batch,
|
||||
function ( $item ) {
|
||||
return 'trace' === $item['type'];
|
||||
}
|
||||
)
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
// Then POST spans.
|
||||
if ( ! empty( $spans ) ) {
|
||||
$success = $this->post_spans( $spans );
|
||||
if ( ! $success ) {
|
||||
$failed_items = array_merge(
|
||||
$failed_items,
|
||||
array_filter(
|
||||
$batch,
|
||||
function ( $item ) {
|
||||
return 'span' === $item['type'];
|
||||
}
|
||||
)
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
// Re-enqueue failed items with backoff.
|
||||
if ( ! empty( $failed_items ) ) {
|
||||
$this->queue->reenqueue( $failed_items );
|
||||
}
|
||||
|
||||
// Log summary.
|
||||
PRAutoBlogger_Logger::instance()->info(
|
||||
sprintf(
|
||||
'Opik dispatch: %d spans, %d traces, %d failed; queue depth now %d',
|
||||
count( $spans ),
|
||||
count( $traces ),
|
||||
count( $failed_items ),
|
||||
$this->queue->get_queue_depth()
|
||||
),
|
||||
'opik'
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* POST traces to Opik.
|
||||
*
|
||||
* @param array $traces Array of trace payloads.
|
||||
*
|
||||
* @return bool True on success, false on failure.
|
||||
*/
|
||||
private function post_traces( array $traces ): bool {
|
||||
if ( count( $traces ) === 1 ) {
|
||||
// Single trace: use create_trace.
|
||||
$response = $this->client->create_trace( $traces[0] );
|
||||
return null !== $response;
|
||||
}
|
||||
|
||||
// Multiple traces: use batch.
|
||||
$response = $this->client->batch_create_traces( $traces );
|
||||
return null !== $response;
|
||||
}
|
||||
|
||||
/**
|
||||
* POST spans to Opik.
|
||||
*
|
||||
* @param array $spans Array of span payloads.
|
||||
*
|
||||
* @return bool True on success, false on failure.
|
||||
*/
|
||||
private function post_spans( array $spans ): bool {
|
||||
if ( count( $spans ) === 1 ) {
|
||||
// Single span: use create_span.
|
||||
$response = $this->client->create_span( $spans[0] );
|
||||
return null !== $response;
|
||||
}
|
||||
|
||||
// Multiple spans: use batch.
|
||||
$response = $this->client->batch_create_spans( $spans );
|
||||
return null !== $response;
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if Opik is enabled via feature flag and has credentials.
|
||||
*
|
||||
* @return bool
|
||||
*/
|
||||
private function is_enabled(): bool {
|
||||
if ( ! get_option( 'prautoblogger_opik_enabled', false ) ) {
|
||||
return false;
|
||||
}
|
||||
|
||||
// Credentials must be defined in wp-config.php.
|
||||
if ( ! defined( 'PRAUTOBLOGGER_OPIK_API_KEY' ) ||
|
||||
! defined( 'PRAUTOBLOGGER_OPIK_WORKSPACE' ) ) {
|
||||
return false;
|
||||
}
|
||||
|
||||
$api_key = PRAUTOBLOGGER_OPIK_API_KEY;
|
||||
$workspace = PRAUTOBLOGGER_OPIK_WORKSPACE;
|
||||
|
||||
return ! empty( $api_key ) && ! empty( $workspace );
|
||||
}
|
||||
}
|
||||
170
includes/services/opik/class-opik-span-queue.php
Normal file
170
includes/services/opik/class-opik-span-queue.php
Normal file
@@ -0,0 +1,170 @@
|
||||
<?php
|
||||
declare(strict_types=1);
|
||||
|
||||
/**
|
||||
* Async queue for Opik span/trace payloads.
|
||||
*
|
||||
* Backs the queue with WP options (a single serialized array stored
|
||||
* in wp_options). Payloads are enqueued at the end of article
|
||||
* generation, dequeued and batch-posted via cron.
|
||||
*
|
||||
* Max queue depth is 1000 items; older items are expired TTL-based.
|
||||
*
|
||||
* @see includes/services/opik/class-opik-dispatcher.php — Drains the queue.
|
||||
*/
|
||||
class PRAutoBlogger_Opik_Span_Queue {
|
||||
|
||||
/**
|
||||
* @var string WP option key storing the queue.
|
||||
*/
|
||||
const QUEUE_OPTION_KEY = 'prautoblogger_opik_queue';
|
||||
|
||||
/**
|
||||
* @var int Max queue depth (items).
|
||||
*/
|
||||
const MAX_QUEUE_DEPTH = 1000;
|
||||
|
||||
/**
|
||||
* @var int Item TTL in seconds (12 hours).
|
||||
*/
|
||||
const ITEM_TTL_SECONDS = 43200;
|
||||
|
||||
/**
|
||||
* Enqueue a span or trace for async dispatch.
|
||||
*
|
||||
* @param array $payload Span or trace payload.
|
||||
* @param string $type Either 'span' or 'trace'.
|
||||
*
|
||||
* @return bool True if enqueued, false if queue full.
|
||||
*/
|
||||
public function enqueue( array $payload, string $type = 'span' ): bool {
|
||||
if ( ! in_array( $type, array( 'span', 'trace' ), true ) ) {
|
||||
$type = 'span';
|
||||
}
|
||||
|
||||
$queue = $this->get_queue();
|
||||
|
||||
if ( count( $queue ) >= self::MAX_QUEUE_DEPTH ) {
|
||||
PRAutoBlogger_Logger::instance()->warning(
|
||||
sprintf( 'Opik queue full (%d items); dropping span', count( $queue ) ),
|
||||
'opik'
|
||||
);
|
||||
return false;
|
||||
}
|
||||
|
||||
$item = array(
|
||||
'type' => $type,
|
||||
'payload' => $payload,
|
||||
'enqueued' => time(),
|
||||
'attempt' => 0,
|
||||
);
|
||||
|
||||
$queue[] = $item;
|
||||
update_option( self::QUEUE_OPTION_KEY, $queue );
|
||||
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* Dequeue the next N items from the queue for processing.
|
||||
*
|
||||
* @param int $limit Max items to dequeue.
|
||||
*
|
||||
* @return array Array of items with 'type', 'payload', 'enqueued', 'attempt'.
|
||||
*/
|
||||
public function dequeue( int $limit = 100 ): array {
|
||||
$queue = $this->get_queue();
|
||||
|
||||
if ( empty( $queue ) ) {
|
||||
return array();
|
||||
}
|
||||
|
||||
// Remove expired items.
|
||||
$now = time();
|
||||
$queue = array_filter(
|
||||
$queue,
|
||||
function ( $item ) use ( $now ) {
|
||||
return ( $now - $item['enqueued'] ) < self::ITEM_TTL_SECONDS;
|
||||
}
|
||||
);
|
||||
|
||||
// Grab the first $limit items.
|
||||
$batch = array_splice( $queue, 0, $limit );
|
||||
|
||||
// Save the remaining queue.
|
||||
update_option( self::QUEUE_OPTION_KEY, $queue );
|
||||
|
||||
return $batch;
|
||||
}
|
||||
|
||||
/**
|
||||
* Re-enqueue items that failed to post (typically after backoff).
|
||||
*
|
||||
* @param array $items Items from a failed batch.
|
||||
*/
|
||||
public function reenqueue( array $items ): void {
|
||||
$queue = $this->get_queue();
|
||||
|
||||
foreach ( $items as $item ) {
|
||||
$item['attempt'] = ( $item['attempt'] ?? 0 ) + 1;
|
||||
|
||||
// Drop items that have exceeded max retries (3).
|
||||
if ( $item['attempt'] >= 3 ) {
|
||||
PRAutoBlogger_Logger::instance()->warning(
|
||||
sprintf(
|
||||
'Dropping Opik item after %d attempts: %s',
|
||||
$item['attempt'],
|
||||
$item['type']
|
||||
),
|
||||
'opik'
|
||||
);
|
||||
continue;
|
||||
}
|
||||
|
||||
$queue[] = $item;
|
||||
}
|
||||
|
||||
update_option( self::QUEUE_OPTION_KEY, $queue );
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the current queue state.
|
||||
*
|
||||
* @return array
|
||||
*/
|
||||
public function get_queue(): array {
|
||||
$queue = get_option( self::QUEUE_OPTION_KEY, array() );
|
||||
return is_array( $queue ) ? $queue : array();
|
||||
}
|
||||
|
||||
/**
|
||||
* Get queue depth (item count).
|
||||
*
|
||||
* @return int
|
||||
*/
|
||||
public function get_queue_depth(): int {
|
||||
return count( $this->get_queue() );
|
||||
}
|
||||
|
||||
/**
|
||||
* Clear all items from the queue.
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
public function clear(): void {
|
||||
delete_option( self::QUEUE_OPTION_KEY );
|
||||
}
|
||||
|
||||
/**
|
||||
* Get a human-readable status string for admin display.
|
||||
*
|
||||
* @return string
|
||||
*/
|
||||
public function get_status(): string {
|
||||
$depth = $this->get_queue_depth();
|
||||
if ( 0 === $depth ) {
|
||||
return 'Queue empty';
|
||||
}
|
||||
return sprintf( 'Queue: %d item%s pending', $depth, 1 !== $depth ? 's' : '' );
|
||||
}
|
||||
}
|
||||
196
includes/services/opik/class-opik-trace-context.php
Normal file
196
includes/services/opik/class-opik-trace-context.php
Normal file
@@ -0,0 +1,196 @@
|
||||
<?php
|
||||
declare(strict_types=1);
|
||||
|
||||
/**
|
||||
* Per-request trace context singleton.
|
||||
*
|
||||
* Holds the current trace ID and manages the span stack for a single
|
||||
* article generation. Initialized at the top of the pipeline,
|
||||
* torn down at the end.
|
||||
*
|
||||
* Single-threaded per-request model: one trace per article generation,
|
||||
* child spans per LLM call.
|
||||
*
|
||||
* @see includes/services/opik/class-opik-client.php
|
||||
* @see includes/services/opik/class-opik-span-queue.php
|
||||
*/
|
||||
class PRAutoBlogger_Opik_Trace_Context {
|
||||
|
||||
/**
|
||||
* @var self|null
|
||||
*/
|
||||
private static ?self $instance = null;
|
||||
|
||||
/**
|
||||
* @var string Trace ID (UUID).
|
||||
*/
|
||||
private string $trace_id = '';
|
||||
|
||||
/**
|
||||
* @var float Trace start time (microtime).
|
||||
*/
|
||||
private float $trace_start = 0.0;
|
||||
|
||||
/**
|
||||
* @var array Stack of active spans; indexed by span_id.
|
||||
*/
|
||||
private array $span_stack = array();
|
||||
|
||||
/**
|
||||
* Get or create the current request's trace context.
|
||||
*
|
||||
* @return self
|
||||
*/
|
||||
public static function current(): self {
|
||||
if ( null === self::$instance ) {
|
||||
self::$instance = new self();
|
||||
}
|
||||
return self::$instance;
|
||||
}
|
||||
|
||||
/**
|
||||
* Initialize a new trace for this request.
|
||||
*
|
||||
* Generates a UUID and records the start time. Called once at the
|
||||
* top of the article generation pipeline.
|
||||
*
|
||||
* @return string The trace ID (UUID).
|
||||
*/
|
||||
public function init_trace(): string {
|
||||
$this->trace_id = wp_generate_uuid4();
|
||||
$this->trace_start = microtime( true );
|
||||
return $this->trace_id;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the current trace ID.
|
||||
*
|
||||
* @return string
|
||||
*/
|
||||
public function get_trace_id(): string {
|
||||
return $this->trace_id;
|
||||
}
|
||||
|
||||
/**
|
||||
* Start a span within the current trace.
|
||||
*
|
||||
* @param array{
|
||||
* name: string,
|
||||
* type: string,
|
||||
* model?: string,
|
||||
* provider?: string,
|
||||
* input?: array,
|
||||
* parent_span_id?: string
|
||||
* } $span_data Span metadata.
|
||||
*
|
||||
* @return string Generated span ID (UUID).
|
||||
*/
|
||||
public function start_span( array $span_data ): string {
|
||||
$span_id = wp_generate_uuid4();
|
||||
|
||||
$span = array(
|
||||
'id' => $span_id,
|
||||
'trace_id' => $this->trace_id,
|
||||
'name' => $span_data['name'] ?? 'unknown',
|
||||
'type' => $span_data['type'] ?? 'general',
|
||||
'start_time' => gmdate( 'Y-m-d\TH:i:s\Z' ),
|
||||
'start_time_ms' => microtime( true ),
|
||||
'end_time' => null,
|
||||
'end_time_ms' => null,
|
||||
'input' => $span_data['input'] ?? array(),
|
||||
'output' => array(),
|
||||
'model' => $span_data['model'] ?? null,
|
||||
'provider' => $span_data['provider'] ?? null,
|
||||
'parent_span_id' => $span_data['parent_span_id'] ?? null,
|
||||
'usage' => array(),
|
||||
);
|
||||
|
||||
$this->span_stack[ $span_id ] = $span;
|
||||
return $span_id;
|
||||
}
|
||||
|
||||
/**
|
||||
* End a span and record its output.
|
||||
*
|
||||
* @param string $span_id Span ID from start_span().
|
||||
* @param array{
|
||||
* output?: array,
|
||||
* usage?: array
|
||||
* } $span_data Final span data to merge.
|
||||
*/
|
||||
public function end_span( string $span_id, array $span_data = array() ): void {
|
||||
if ( ! isset( $this->span_stack[ $span_id ] ) ) {
|
||||
PRAutoBlogger_Logger::instance()->warning(
|
||||
sprintf( 'Attempt to end unknown span %s', $span_id ),
|
||||
'opik'
|
||||
);
|
||||
return;
|
||||
}
|
||||
|
||||
$span = &$this->span_stack[ $span_id ];
|
||||
$span['end_time'] = gmdate( 'Y-m-d\TH:i:s\Z' );
|
||||
$span['end_time_ms'] = microtime( true );
|
||||
$span['output'] = $span_data['output'] ?? array();
|
||||
$span['usage'] = $span_data['usage'] ?? array();
|
||||
}
|
||||
|
||||
/**
|
||||
* Get a completed span from the stack.
|
||||
*
|
||||
* @param string $span_id
|
||||
*
|
||||
* @return array|null
|
||||
*/
|
||||
public function get_span( string $span_id ): ?array {
|
||||
return $this->span_stack[ $span_id ] ?? null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all spans collected in this trace.
|
||||
*
|
||||
* @return array
|
||||
*/
|
||||
public function get_spans(): array {
|
||||
return $this->span_stack;
|
||||
}
|
||||
|
||||
/**
|
||||
* Finalize and return the trace object with all spans.
|
||||
*
|
||||
* @return array{
|
||||
* id: string,
|
||||
* name: string,
|
||||
* project_name: string,
|
||||
* start_time: string,
|
||||
* end_time: string,
|
||||
* input: array,
|
||||
* output: array,
|
||||
* metadata: array,
|
||||
* spans: array
|
||||
* }
|
||||
*/
|
||||
public function finalize_trace(): array {
|
||||
$trace_end = microtime( true );
|
||||
|
||||
return array(
|
||||
'id' => $this->trace_id,
|
||||
'name' => 'article_generation',
|
||||
'project_name' => get_option( 'prautoblogger_opik_project_name', 'prautoblogger' ),
|
||||
'start_time' => gmdate( 'Y-m-d\TH:i:s\Z', (int) $this->trace_start ),
|
||||
'end_time' => gmdate( 'Y-m-d\TH:i:s\Z', (int) $trace_end ),
|
||||
'input' => array( 'pipeline' => 'article_generation' ),
|
||||
'output' => array( 'spans_count' => count( $this->span_stack ) ),
|
||||
'metadata' => array( 'source' => 'prautoblogger' ),
|
||||
'spans' => $this->span_stack,
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Tear down the context (clear it for the next request).
|
||||
*
|
||||
* Called at the end of the article generation pipeline.
|
||||
*/
|
||||
public static function teardown(): void {
|
||||
self::$instance = null;
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user