Add Logger::logRecordBuilder() (#1859)

* Add `Logger::logRecordBuilder()`

* Duplicate current `Logger` tests for `LogRecordBuilder`

* Update SDK branch alias

* Update SDK conflict version in API package

* Add log record span context test

* Add `CoversClass` `LogRecordBuilder` attribute

Author: Nevay

Logs/LateBindingLogger.php

@@ -17,6 +17,12 @@ public function __construct(
     ) {
     }
 
+    #[\Override]
+    public function logRecordBuilder(): LogRecordBuilderInterface
+    {
+        return ($this->logger ??= ($this->factory)())->logRecordBuilder();
+    }
+
     #[\Override]
     public function emit(LogRecord $logRecord): void
     {

Logs/LogRecord.php

@@ -6,6 +6,9 @@
 
 use OpenTelemetry\Context\ContextInterface;
 
+/**
+ * Deprecated, use {@link LoggerInterface::logRecordBuilder()} instead.
+ */
 class LogRecord
 {
     public const NANOS_PER_SECOND = 1_000_000_000;

Logs/LogRecordBuilderInterface.php

@@ -0,0 +1,80 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\API\Logs;
+
+use OpenTelemetry\Context\ContextInterface;
+use Throwable;
+
+interface LogRecordBuilderInterface
+{
+    /**
+     * Time when the event occurred measured by the origin clock, i.e. the time at the source.
+     *
+     * @param int $timestamp nanoseconds since UNIX epoch
+     * @see https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-timestamp
+     */
+    public function setTimestamp(int $timestamp): LogRecordBuilderInterface;
+
+    /**
+     * Time when the event was observed by the collection system
+     *
+     * @param int $timestamp nanoseconds since UNIX epoch
+     * @see https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-observedtimestamp
+     */
+    public function setObservedTimestamp(int $timestamp): LogRecordBuilderInterface;
+
+    /**
+     * @param ContextInterface|false|null $context the log context, null to use the current
+     *        context, false to use no context
+     * @see https://opentelemetry.io/docs/specs/otel/logs/data-model/#trace-context-fields
+     */
+    public function setContext(ContextInterface|false|null $context): LogRecordBuilderInterface;
+
+    /**
+     * Numerical value of the severity.
+     *
+     * @see https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-severitynumber
+     */
+    public function setSeverityNumber(int|Severity $severityNumber): LogRecordBuilderInterface;
+
+    /**
+     * The original string representation of the severity as it is known at the source.
+     *
+     * @see https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-severitytext
+     */
+    public function setSeverityText(string $severityText): LogRecordBuilderInterface;
+
+    /**
+     * @see https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-body
+     */
+    public function setBody(mixed $body): LogRecordBuilderInterface;
+
+    /**
+     * @see https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-attributes
+     */
+    public function setAttribute(string $key, mixed $value): LogRecordBuilderInterface;
+
+    /**
+     * @see https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-attributes
+     */
+    public function setAttributes(iterable $attributes): LogRecordBuilderInterface;
+
+    /**
+     * Sets the `exception.message` `exception.type`, and `exception.stacktrace` attributes.
+     *
+     * @see https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-logs/#attributes
+     */
+    public function setException(Throwable $exception): LogRecordBuilderInterface;
+
+    /**
+     * @see https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-eventname
+     */
+    public function setEventName(string $eventName): LogRecordBuilderInterface;
+
+    /**
+     * @see https://opentelemetry.io/docs/specs/otel/logs/api/#emit-a-logrecord
+     */
+    public function emit(): void;
+}

Logs/LoggerInterface.php

@@ -8,8 +8,31 @@
 
 interface LoggerInterface
 {
+    /**
+     * Deprecated, use {@link LoggerInterface::logRecordBuilder()} instead.
+     *
+     * Deprecated:
+     * ```
+     * $logger->emit(new LogRecord()
+     *     ->setTimestamp($timestamp)
+     *     ...
+     *     ->setEventName($eventName)
+     * );
+     * ```
+     *
+     * Instead, use:
+     * ```
+     * $logger->logRecordBuilder()
+     *     ->setTimestamp($timestamp)
+     *     ...
+     *     ->setEventName($eventName)
+     *     ->emit();
+     * ```
+     */
     public function emit(LogRecord $logRecord): void;
 
+    public function logRecordBuilder(): LogRecordBuilderInterface;
+
     /**
      * Determine if the logger is enabled. Instrumentation authors SHOULD call this method each time they
      * emit a LogRecord, to ensure they have the most up-to-date response.

Logs/NoopLogRecordBuilder.php

@@ -0,0 +1,80 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\API\Logs;
+
+use OpenTelemetry\Context\ContextInterface;
+use Throwable;
+
+/**
+ * @psalm-internal OpenTelemetry
+ */
+final class NoopLogRecordBuilder implements LogRecordBuilderInterface
+{
+    #[\Override]
+    public function setTimestamp(int $timestamp): LogRecordBuilderInterface
+    {
+        return $this;
+    }
+
+    #[\Override]
+    public function setObservedTimestamp(int $timestamp): LogRecordBuilderInterface
+    {
+        return $this;
+    }
+
+    #[\Override]
+    public function setContext(ContextInterface|false|null $context): LogRecordBuilderInterface
+    {
+        return $this;
+    }
+
+    #[\Override]
+    public function setSeverityNumber(int|Severity $severityNumber): LogRecordBuilderInterface
+    {
+        return $this;
+    }
+
+    #[\Override]
+    public function setSeverityText(string $severityText): LogRecordBuilderInterface
+    {
+        return $this;
+    }
+
+    #[\Override]
+    public function setBody(mixed $body): LogRecordBuilderInterface
+    {
+        return $this;
+    }
+
+    #[\Override]
+    public function setAttribute(string $key, mixed $value): LogRecordBuilderInterface
+    {
+        return $this;
+    }
+
+    #[\Override]
+    public function setAttributes(iterable $attributes): LogRecordBuilderInterface
+    {
+        return $this;
+    }
+
+    #[\Override]
+    public function setException(Throwable $exception): LogRecordBuilderInterface
+    {
+        return $this;
+    }
+
+    #[\Override]
+    public function setEventName(string $eventName): LogRecordBuilderInterface
+    {
+        return $this;
+    }
+
+    #[\Override]
+    public function emit(): void
+    {
+        // no-op
+    }
+}

Logs/NoopLogger.php

@@ -18,6 +18,14 @@ public static function getInstance(): self
         return $instance ??= new self();
     }
 
+    #[\Override]
+    public function logRecordBuilder(): LogRecordBuilderInterface
+    {
+        static $logRecordBuilder = new NoopLogRecordBuilder();
+
+        return $logRecordBuilder;
+    }
+
     /**
      * @codeCoverageIgnore
      */

composer.json

@@ -23,7 +23,7 @@
         "symfony/polyfill-php82": "^1.26"
     },
     "conflict": {
-        "open-telemetry/sdk": "<=1.0.8"
+        "open-telemetry/sdk": "<=1.11"
     },
     "autoload": {
         "psr-4": {