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.

whatyouhide · 2026-01-07T16:09:33Z

lib/sentry/logs_handler.ex

@@ -0,0 +1,247 @@
+defmodule Sentry.LogsHandler do


I think it's going to be really confusing to have Sentry.LoggerHandler (for errors) and Sentry.LogsHandler (for logs). Have we thought about that?

@whatyouhide I was on the fence with this, decided to go with Logs because this is what we call the feature in Sentry, but for more clarity I think we could rename Sentry.LoggerHandler to Sentry.ErrorLogHandler and leave Sentry.LogsHandler. Another option is to collapse the two into one and unify behavior, where capturing error logs as exceptions would be one of the handler features, and sending logs would be another, both configurable.

Yeah this is a tough one. Renaming Sentry.LoggerHandler is annoying because it will require users who upgrade to do it manually, and there's no "nice" way to deprecate the name itself. I think keeping only Sentry.LoggerHandler and making it configurable is messier on the SDK side but might be a better experience for the end user, provided it:

validates configuration as much as possible automatically so that it's easy to make sure you're doing the right config

supports the new Structured Logs approach as opt in—for example, we use the logger handler for catching log errors and crashes but we do not use the Sentry Logs product at all (and wouldn't want to)

Thoughts?

Doing extra work on SDK side to improve DX is our principle guideline thus collapsing into one LoggerHandler sounds like the way to go even if it means more work for us.

fine with either decision, but to help decide: eventually, we will deprecate and remove the older error/issue creation from logs now that we have a dedicated logs product.

Co-authored-by: Andrea Leopardi <an.leopardi@gmail.com>

sl0thentr0py

2 comments about schema changes

sl0thentr0py · 2026-01-09T13:39:41Z

lib/sentry/log_event.ex

+    |> put_sentry_attr_if("sentry.environment", log_event.environment)
+    |> put_sentry_attr_if("sentry.release", log_event.release)
+    |> put_sentry_attr_if("sentry.address", log_event.server_name)
+    |> put_sentry_attr_if("sentry.trace.parent_span_id", log_event.parent_span_id)


this is now a top level span_id field, we no longer need sentry.trace.parent_span_id

sl0thentr0py · 2026-01-09T13:41:40Z

lib/sentry/log_event.ex

+      parent_span_id: parent_span_id,
+      environment: Config.environment_name(),
+      release: Config.release(),
+      server_name: Config.server_name(),


let's not have environment/release/server_name in the struct definition, they should just be added to attributes in the relevant payload construction.

the schema here should match
https://github.com/getsentry/relay/blob/0223f6f728feacb0a5de607bbe5c8621644b8a9e/relay-event-schema/src/protocol/ourlog.rs#L14-L37

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 <an.leopardi@gmail.com>

Update lib/sentry/log_event.ex

8d04f9b

Co-authored-by: Andrea Leopardi <an.leopardi@gmail.com>

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

	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

Uh oh!

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!

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!

sl0thentr0py left a comment

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

solnic commented Jan 2, 2026 •

edited

Loading