Skip to content

Deprecate span event emission API - #8300

Closed
yordis wants to merge 1 commit into
Effect-TS:mainfrom
yordis:yordis/docs-deprecate-span-events
Closed

yordis wants to merge 1 commit into
Effect-TS:mainfrom
yordis:yordis/docs-deprecate-span-events

Conversation

@yordis

@yordis yordis commented Sep 18, 2026

Copy link
Copy Markdown

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. Effect currently documents the opposite: Logger.tracerLogger tells readers that recording logs as span events is how you make them visible in OpenTelemetry, Jaeger, or Zipkin, which now points new instrumentation away from the supported path.

  • OtlpLogger already stamps the trace and span id onto every log record, so the replacement is available today and needs no new API. Installing it alongside tracerLogger exports each log twice, once as a log record and once as a span event, which is the duplication the deprecation exists to remove.
  • Reading events back off a span is explicitly retained by the spec, so the accessors, exporters, and the @effect/opentelemetry bridge are untouched, and neither Span#event nor tracerLogger is removed.
  • Span#event is user-implementable, so the tag surfaces on custom Span implementations as well as call sites. That is the accurate signal, but happy to drop it to tracerLogger alone if the noise is unwelcome.

Deliberately scoped to the deprecation. Whether tracerLogger should stay in the default logger set, and whether @effect/opentelemetry's NodeSdk should stop installing a log exporter beside it, are behaviour changes worth deciding separately, and the release candidate is the cheap moment to make them.

References:

OpenTelemetry is consolidating on a single way to emit events, so guidance
that points instrumentation at span events now leads users away from the
supported path.

Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>
@changeset-bot

changeset-bot Bot commented Sep 18, 2026

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 8e0e027

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 31 packages
Name Type
effect Patch
@effect/opentelemetry Patch
@effect/vitest Patch
@effect/ai-anthropic Patch
@effect/ai-openai-compat Patch
@effect/ai-openai Patch
@effect/ai-openrouter Patch
@effect/ai-typesafe Patch
@effect/atom-react Patch
@effect/atom-solid Patch
@effect/atom-vue Patch
@effect/platform-browser Patch
@effect/platform-bun Patch
@effect/platform-deno Patch
@effect/platform-node-shared Patch
@effect/platform-node Patch
@effect/sql-clickhouse Patch
@effect/sql-d1 Patch
@effect/sql-libsql Patch
@effect/sql-mssql Patch
@effect/sql-mysql2 Patch
@effect/sql-pg Patch
@effect/sql-pglite Patch
@effect/sql-sqlite-bun Patch
@effect/sql-sqlite-do Patch
@effect/sql-sqlite-node Patch
@effect/sql-sqlite-react-native Patch
@effect/sql-sqlite-wasm Patch
@effect/docgen Patch
@effect/doctest Patch
@effect/openapi-generator Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@yordis

yordis commented Sep 18, 2026

Copy link
Copy Markdown
Author

Related to pingdotgg/t3code#12493

@github-actions

Copy link
Copy Markdown
Contributor

Bundle Size Analysis

Generated from PR build output; treat the content below as untrusted.

File Name Current Size Previous Size Difference
arbitrary-combinators.ts 37.71 KB 37.71 KB 0.00 KB (0.00%)
basic.ts 6.87 KB 6.87 KB 0.00 KB (0.00%)
batching.ts 9.95 KB 9.95 KB 0.00 KB (0.00%)
brand.ts 6.45 KB 6.45 KB 0.00 KB (0.00%)
cache.ts 10.77 KB 10.77 KB 0.00 KB (0.00%)
config.ts 21.83 KB 21.83 KB 0.00 KB (0.00%)
differ.ts 20.67 KB 20.67 KB 0.00 KB (0.00%)
http-client.ts 21.94 KB 21.94 KB 0.00 KB (0.00%)
http-router.ts 36.96 KB 36.96 KB 0.00 KB (0.00%)
logger.ts 10.88 KB 10.88 KB 0.00 KB (0.00%)
metric.ts 9.02 KB 9.02 KB 0.00 KB (0.00%)
optic.ts 6.70 KB 6.70 KB 0.00 KB (0.00%)
pubsub.ts 15.10 KB 15.10 KB 0.00 KB (0.00%)
queue.ts 11.85 KB 11.85 KB 0.00 KB (0.00%)
schedule.ts 10.96 KB 10.96 KB 0.00 KB (0.00%)
schema-bigdecimal.ts 13.40 KB 13.40 KB 0.00 KB (0.00%)
schema-binary.ts 39.82 KB 39.82 KB 0.00 KB (0.00%)
schema-class.ts 20.38 KB 20.38 KB 0.00 KB (0.00%)
schema-fromJsonSchemaDocument.ts 31.18 KB 31.18 KB 0.00 KB (0.00%)
schema-representation-roundtrip.ts 26.60 KB 26.60 KB 0.00 KB (0.00%)
schema-string-transformation.ts 13.96 KB 13.96 KB 0.00 KB (0.00%)
schema-string.ts 11.55 KB 11.55 KB 0.00 KB (0.00%)
schema-template-literal.ts 15.70 KB 15.70 KB 0.00 KB (0.00%)
schema-toArbitrary.ts 37.24 KB 37.24 KB 0.00 KB (0.00%)
schema-toCodeDocument.ts 24.84 KB 24.84 KB 0.00 KB (0.00%)
schema-toCodecJson.ts 19.61 KB 19.61 KB 0.00 KB (0.00%)
schema-toEquivalence.ts 19.75 KB 19.75 KB 0.00 KB (0.00%)
schema-toFormatter.ts 19.85 KB 19.85 KB 0.00 KB (0.00%)
schema-toJsonSchemaDocument.ts 24.15 KB 24.15 KB 0.00 KB (0.00%)
schema-toRepresentation.ts 19.89 KB 19.89 KB 0.00 KB (0.00%)
schema.ts 19.59 KB 19.59 KB 0.00 KB (0.00%)
stm.ts 12.80 KB 12.80 KB 0.00 KB (0.00%)
stream.ts 9.83 KB 9.83 KB 0.00 KB (0.00%)

@mikearnaldi
mikearnaldi requested a review from tim-smart October 6, 2026 22:09
@tim-smart

tim-smart commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

Thanks for the PR. I think we will wait a bit longer before depreciating span events.

Logger.layer defaults mergeWithExisting to false, so if you provide a OtlpLogger the tracerLogger will get removed by default.

There are still a few otlp services around that only injest traces and not logs, so we should wait for the ecosystem to catch up first.

@tim-smart tim-smart closed this Oct 7, 2026
@yordis

yordis commented Oct 7, 2026

Copy link
Copy Markdown
Author

Wouldn't be better to give the signal to catch up sooner rather than later? That is why I didn't do much code change.

Regardless, I am ok with anything, thank you for the review

This branch is waiting to be deployed

1 waiting deployment
fork — 8e0e0274 Waiting Sep 18, 2026 by yordis via approval-gate #26069
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants