Deprecate span event emission API

.changeset/deprecate-span-events.md

@@ -0,0 +1,19 @@
+---
+"effect": patch
+---
+
+Deprecate the span event emission API in line with OpenTelemetry.
+
+`Tracer.Span#event` and `Logger.tracerLogger` are now marked `@deprecated`.
+OpenTelemetry has deprecated the Span Event API in favour of emitting events
+through the Logs API, correlated to their span by trace and span id. Reading
+events back off a span, as an exporter does, is unaffected, and neither the
+method nor the logger is removed.
+
+`OtlpLogger` already stamps the trace and span id onto every log record, so a
+log exporter provides the same correlation without span events. Installing one
+alongside `tracerLogger` exports each log twice, once as a log record and once
+as a span event.
+
+See the [OpenTelemetry announcement](https://opentelemetry.io/blog/2026/deprecating-span-events/)
+and [OTEP 4430](https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/4430-span-event-api-deprecation-plan.md).

packages/effect/src/Logger.ts

@@ -969,13 +969,21 @@ export const consoleJson: Logger<unknown, void> = withConsoleLog(formatJson)
  *
  * **Details**
  *
- * This logger integrates logging with distributed tracing by recording
- * all log messages as events on the current trace span, making them visible
- * in tracing tools like OpenTelemetry, Jaeger, or Zipkin.
+ * This logger records every log message as an event on the current span.
+ * OpenTelemetry has deprecated that representation: events are now emitted
+ * through the Logs API and correlated to their span by trace and span id.
+ * `OtlpLogger` from `effect/unstable/observability/OtlpLogger`, and
+ * `OtelLogger` from `@effect/opentelemetry`, already stamp both ids onto every
+ * log record, so a log exporter gives the same correlation without span
+ * events.
  *
  * This logger is included in the default set of loggers for all Effect programs,
- * so log messages automatically appear as span events unless you override the
- * default loggers.
+ * so log messages appear as span events unless you override the default
+ * loggers. Installing a log exporter alongside it exports each log twice, once
+ * as a log record and once as a span event.
+ *
+ * Reach for it when a backend renders only events attached to spans, or for
+ * local debugging where the trace is the only sink you read.
  *
  * **Example** (Recording logs as trace span events)
  *
@@ -989,6 +997,11 @@ export const consoleJson: Logger<unknown, void> = withConsoleLog(formatJson)
  * Effect.runSync(program)
  * ```
  *
+ * @deprecated Emit logs through a log exporter instead, such as `OtlpLogger`
+ * from `effect/unstable/observability/OtlpLogger`, which correlates each log
+ * record to its span by trace and span id.
+ * @see https://opentelemetry.io/blog/2026/deprecating-span-events/
+ * @see https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/4430-span-event-api-deprecation-plan.md
  * @category constructors
  * @since 2.0.0
  */

packages/effect/src/Tracer.ts

@@ -383,6 +383,19 @@ export interface Span {
   readonly kind: SpanKind
   end(endTime: bigint, exit: Exit.Exit<unknown, unknown>): void
   attribute(key: string, value: unknown): void
+  /**
+   * Records an event on this span.
+   *
+   * @deprecated OpenTelemetry has deprecated the Span Event API in favour of
+   * emitting events through the Logs API, correlated to the active span by
+   * trace and span id. New instrumentation should emit a log record instead.
+   * Reading events back off a span, as an exporter does, is unaffected.
+   *
+   * @see https://opentelemetry.io/blog/2026/deprecating-span-events/
+   * @see https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/4430-span-event-api-deprecation-plan.md
+   *
+   * @since 2.0.0
+   */
   event(name: string, startTime: bigint, attributes?: Record<string, unknown>): void
   addLinks(links: ReadonlyArray<SpanLink>): void
 }