<?php

declare(strict_types=1);

namespace Drupal\native_observability_spans\Service;

/**
 * Lightweight span recorder API.
 *
 * This interface is intentionally minimal:
 * - startSpan() returns a span_id
 * - endSpan() closes the span and computes duration.
 *
 * Implementations must be fail-safe and must not break the request flow.
 */
interface SpanRecorderInterface {

  /**
   * Starts a new span.
   *
   * @param string $name
   *   Span name (e.g. service.method, http.request).
   * @param string|null $category
   *   Span category (service, http, db, custom, ...).
   * @param string|null $parent_span_id
   *   Parent span id for nesting.
   * @param array $payload
   *   Additional payload attributes (stored as JSON).
   *
   * @return string
   *   Generated span identifier.
   */
  public function startSpan(string $name, ?string $category = NULL, ?string $parent_span_id = NULL, array $payload = []): string;

  /**
   * Ends an existing span.
   *
   * @param string $span_id
   *   Span identifier.
   * @param array $payload
   *   Optional final payload attributes (overwrites payload if provided).
   */
  public function endSpan(string $span_id, array $payload = []): void;

}
