Support for Structured Logs #969

solnic · 2026-01-02T08:40:17Z

Initial work on support for Logs.

This follows requirements described in https://develop.sentry.dev/sdk/telemetry/logs/

Closes #906
Closes #907
Closes #908

lib/sentry/envelope.ex

whatyouhide

I think there's quite a few things to think about here and a couple of race conditions in the buffer process, but I’m excited for this getting in the SDK.

lib/sentry/config.ex

whatyouhide · 2026-01-07T15:43:28Z

lib/sentry/client.ex

+  @doc since: "12.0.0"
+  @spec send_log_events([LogEvent.t()]) ::
+          {:ok, envelope_id :: String.t()} | {:error, ClientError.t()}
+  def send_log_events([]), do: {:ok, ""}


If we have a "log batch" struct, would it make sense to have send_log_batch instead of this?

whatyouhide · 2026-01-07T15:43:57Z

lib/sentry/envelope.ex

+            | ClientReport.t()
+            | Event.t()
+            | LogBatch.t()
+            | LogEvent.t()


When do we have an envelope with log events in it instead of a log batch?

whatyouhide · 2026-01-07T15:44:20Z

lib/sentry/envelope.ex

+  Creates a new envelope containing log events.
+
+  According to the Sentry Logs Protocol, log events are sent in batches
+  within a single envelope item with content_type "application/vnd.sentry.items.log+json".


Nits:

Suggested change

within a single envelope item with content_type "application/vnd.sentry.items.log+json".

within a single envelope item with content type `application/vnd.sentry.items.log+json`.

whatyouhide · 2026-01-07T15:44:32Z

lib/sentry/envelope.ex

+  within a single envelope item with content_type "application/vnd.sentry.items.log+json".
+  All log events are wrapped in a single item with { items: [...] }.
+  """
+  @doc since: "11.0.0"


Typo?

Suggested change

@doc since: "11.0.0"

@doc since: "12.0.0"

whatyouhide · 2026-01-07T15:53:27Z

lib/sentry/log_event_buffer.ex

+  @impl GenServer
+  def handle_cast({:add_event, event}, state) do
+    # Check if queue is at max capacity
+    if length(state.events) >= @max_queue_size do


This is going to be called constantly. Can we keep track of the current number of events instead of recomputing length(state.events) every time?

whatyouhide · 2026-01-07T15:53:53Z

lib/sentry/log_event_buffer.ex

+    else
+      events = [event | state.events]
+
+      if length(events) >= state.max_events do


If we do what I suggest above we don't need to calculate length(events) again here (it's just that number + 1)

whatyouhide · 2026-01-07T16:06:58Z

lib/sentry/log_event_buffer.ex

+  @impl GenServer
+  def handle_call(:flush, _from, state) do
+    send_events(state.events)
+    cancel_timer(state.timer_ref)


There's an (unlikely) race condition here where the timer fired while we're in this function and cancel_timer/1 has no effect, leading to the :flush message being in the message queue and handled right after flushing here.

Two solutions:

Switch to gen_statem, which makes all this pretty easy with its timeout handling.

Flush the :flush_timeout message by using a receive do :flush_timeout -> :ok after 0 -> :ok end or something.

whatyouhide · 2026-01-07T16:08:17Z

lib/sentry/log_event_buffer.ex

+        do_send_events(events)
+      else
+        # Send asynchronously to avoid blocking in production
+        Task.start(fn -> do_send_events(events) end)


Can we start this task under a Task.Supervisor with a configured number of :max_children? We run the (low) risk of blowing things up here if these tasks become backlogged and this GenServer keeps spawning new ones.

lib/sentry/logs_handler.ex

Co-authored-by: Andrea Leopardi <[email protected]>

sl0thentr0py

2 comments about schema changes

lib/sentry/log_event.ex

solnic linked an issue Jan 2, 2026 that may be closed by this pull request

Sentry logger handler for Structured Logging #906

Open

solnic force-pushed the 906-sentry-logger-handler-for-structured-logging branch 15 times, most recently from bcacf6e to bcb816d Compare January 5, 2026 12:17

solnic marked this pull request as ready for review January 5, 2026 12:21

solnic requested review from dingsdax, sl0thentr0py and whatyouhide January 5, 2026 12:21

solnic mentioned this pull request Jan 5, 2026

Prep 12.0.0 #967

Draft

solnic force-pushed the 906-sentry-logger-handler-for-structured-logging branch from bcb816d to 094f947 Compare January 6, 2026 12:31

sentry bot reviewed Jan 6, 2026

View reviewed changes

lib/sentry/envelope.ex Show resolved Hide resolved

solnic force-pushed the 906-sentry-logger-handler-for-structured-logging branch from 094f947 to 9e1f449 Compare January 7, 2026 07:49

Introduce Logs handler for structured logging

6ecc086

solnic force-pushed the 906-sentry-logger-handler-for-structured-logging branch from 9e1f449 to 3258a25 Compare January 7, 2026 10:17

whatyouhide reviewed Jan 7, 2026

View reviewed changes

solnic added 3 commits January 8, 2026 09:03

fix: timer race condition in LogEventBuffer flush

5cd67ea

fix: use Task.Supervisor for async log event sending

973bb37

perf: track event count in state to avoid repeated length/1 calls

0232c0d

solnic added 6 commits January 8, 2026 09:03

refactor: rename send_log_events/1 to send_log_batch/1

8880d32

fix: remove LogEvent.t() from get_data_category/1 type spec

1bfc6ba

docs: fix version typo (11.0.0 -> 12.0.0)

119d1c1

docs: add version annotations to logs config options

237ab44

docs: format content type with backticks

92f63b6

docs: link URLs properly

0b7962a

solnic force-pushed the 906-sentry-logger-handler-for-structured-logging branch from 3258a25 to 4ea6119 Compare January 8, 2026 09:03

solnic and others added 6 commits January 8, 2026 09:27

refactor: make buffer configurable

e50dc37

Update CHANGELOG.md

22f2436

Update lib/sentry/log_event.ex

cb2fd6d

Co-authored-by: Andrea Leopardi <[email protected]>

Update lib/sentry/log_event.ex

8d04f9b

Co-authored-by: Andrea Leopardi <[email protected]>

fix: remove LogEvent from envelope items

021cabf

fix: enabled_logs -> enable_logs

515fa87

solnic force-pushed the 906-sentry-logger-handler-for-structured-logging branch from 7c929ff to 515fa87 Compare January 8, 2026 09:27

fix: formatting

afbd8d1

sl0thentr0py requested changes Jan 9, 2026

View reviewed changes

lib/sentry/log_event.ex Outdated Show resolved Hide resolved

lib/sentry/log_event.ex Outdated Show resolved Hide resolved

dingsdax removed their request for review January 12, 2026 08:43

solnic added 2 commits January 14, 2026 08:40

refactor: introduce a unified logger handler

33ffad1

fixup: update log event structure to match relay requirements

d9b04fc

solnic requested a review from sl0thentr0py January 14, 2026 12:58

sl0thentr0py approved these changes Jan 14, 2026

View reviewed changes

fixup: flush stale also in handle_cast

35dfb1b

solnic requested a review from whatyouhide January 14, 2026 14:13

	within a single envelope item with content_type "application/vnd.sentry.items.log+json".
	within a single envelope item with content type `application/vnd.sentry.items.log+json`.

Uh oh!

Support for Structured Logs #969

Are you sure you want to change the base?

Support for Structured Logs #969

Conversation

solnic commented Jan 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

whatyouhide left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sl0thentr0py left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

solnic commented Jan 2, 2026 •

edited

Loading