<?php

declare(strict_types=1);

namespace Drupal\native_observability_execution\Service;

/**
 * Records execution spans into the current request span stack.
 *
 * This is a lightweight internal API meant to be used by:
 * - Service decorators
 * - HTTP client (Guzzle) middleware
 * - Custom code that wants to measure execution blocks.
 */
interface ExecutionSpanRecorderInterface {

  /**
   * Records a span.
   *
   * @param string $category
   *   A logical span category (e.g. "service", "external.http", "request").
   * @param string $name
   *   A short span name (e.g. service id, "GET api.example.com").
   * @param int $duration_ms
   *   Execution duration in milliseconds.
   * @param array<string, mixed> $meta
   *   Optional metadata.
   */
  public function record(string $category, string $name, int $duration_ms, array $meta = []): void;

  /**
   * Measures a callable and records the span automatically.
   *
   * @param string $category
   *   The logical span category.
   * @param string $name
   *   The span label.
   * @param callable():T $callback
   *   The callback to measure.
   * @param array<string, mixed> $meta
   *   Optional metadata to persist with the span.
   *
   * @template T
   *
   * @return T
   *   The callback result.
   *
   * @throws \Throwable
   *   Re-throws any exception from the callback after recording an error span.
   */
  public function measure(string $category, string $name, callable $callback, array $meta = []);

}
