feat(logs): Add experimental user-callable logging methods #15442

colin-sentry · 2025-02-18T20:09:22Z

This PR adds logging APIs to the SDK. At the moment this is only exposed in @sentry/core and @sentry/browser.

Logging is gated by an experimental option, _experiments.enableLogs.

Sentry.init({
  _experiments: {
    enableLogs: true,
  },
});

These API are exposed in the Sentry._experiment_log namespace.

On the high level, there are functions for each of the logging severity levels fatal, error, warn, info, debug, trace. There is also a log function that is an alias to info.

Sentry._experiment_log.info('Adding item to cart', { item: 'sneakers' });

If you want to do structured logging, you'll need to use the fmt helper exposed in the Sentry._experiment_log namespace.

const { fmt } = Sentry._experiment_log;

Sentry._experiment_log.info(fmt`user ${username} just bought ${item}!`);

There is a buffer of logs that flushes every 5 seconds, or when you hit 25 logs, whichever comes first.

github-actions · 2025-02-18T20:19:02Z

size-limit report 📦

Path	Size	% Change	Change
@sentry/browser	23.89 KB	+3.19%	+755 B 🔺
@sentry/browser - with treeshaking flags	23.69 KB	+3.27%	+766 B 🔺
@sentry/browser (incl. Tracing)	36.88 KB	+1.87%	+690 B 🔺
@sentry/browser (incl. Tracing, Replay)	74.05 KB	+0.91%	+677 B 🔺
@sentry/browser (incl. Tracing, Replay) - with treeshaking flags	67.48 KB	+1.03%	+698 B 🔺
@sentry/browser (incl. Tracing, Replay with Canvas)	78.69 KB	+0.88%	+697 B 🔺
@sentry/browser (incl. Tracing, Replay, Feedback)	91.23 KB	+0.73%	+675 B 🔺
⛔️ @sentry/browser (incl. Feedback) (max: 41.02 KB)	41.03 KB	+1.82%	+749 B 🔺
@sentry/browser (incl. sendFeedback)	28.52 KB	+2.66%	+756 B 🔺
@sentry/browser (incl. FeedbackAsync)	33.31 KB	+2.25%	+750 B 🔺
@sentry/react	25.67 KB	+2.83%	+722 B 🔺
@sentry/react (incl. Tracing)	38.8 KB	+1.85%	+720 B 🔺
@sentry/vue	28.11 KB	+2.61%	+731 B 🔺
⛔️ @sentry/vue (incl. Tracing) (max: 38.57 KB)	38.61 KB	+1.89%	+731 B 🔺
@sentry/svelte	23.92 KB	+3.2%	+758 B 🔺
CDN Bundle	24.36 KB	-	-
CDN Bundle (incl. Tracing)	36.26 KB	-	-
CDN Bundle (incl. Tracing, Replay)	71.27 KB	-	-
CDN Bundle (incl. Tracing, Replay, Feedback)	76.44 KB	-	-
CDN Bundle - uncompressed	71.19 KB	-	-
CDN Bundle (incl. Tracing) - uncompressed	107.57 KB	-	-
CDN Bundle (incl. Tracing, Replay) - uncompressed	218.84 KB	-	-
CDN Bundle (incl. Tracing, Replay, Feedback) - uncompressed	231.4 KB	-	-
@sentry/nextjs (client)	39.94 KB	+1.7%	+683 B 🔺
@sentry/sveltekit (client)	37.31 KB	+1.88%	+703 B 🔺
@sentry/node	142.88 KB	+0.52%	+746 B 🔺
@sentry/node - without tracing	96.32 KB	+0.79%	+767 B 🔺
@sentry/aws-serverless	120.64 KB	+0.6%	+735 B 🔺

View base workflow run

packages/core/src/ourlogs.ts

packages/core/src/types-hoist/envelope.ts

stephanie-anderson · 2025-02-19T13:03:29Z

packages/core/src/utils-hoist/envelope.ts

@@ -223,6 +223,7 @@ const ITEM_TYPE_TO_DATA_CATEGORY_MAP: Record<EnvelopeItemType, DataCategory> = {
  feedback: 'feedback',
  span: 'span',
  raw_security: 'security',
+  otel_log: 'log_item',


Will there be any other type than otel_log? If not in the foreseeable future, I'd suggest we change it to

Suggested change

otel_log: 'log_item',

log: 'log',

Again singular, as in span, or replay

This is done because it matches the code in relay for data categories (rate limiting and client outcomes) https://github.com/getsentry/relay/blob/e36886a98c89af645e5c0d2109657deafa25d902/relay-server/src/envelope.rs#L182

codecov · 2025-02-20T17:14:11Z

❌ 1 Tests Failed:

Tests completed	Failed	Passed	Skipped
4648	1	4647	324

View the top 1 failed test(s) by shortest run time

should report ANR when event loop blocked worker can be stopped and restarted

Stack Traces | 15s run time

Error: thrown: "Exceeded timeout of 15000 ms for a test.
Use jest.setTimeout(newTimeout) to increase the timeout value, if this is a long-running test."
    at .../suites/anr/test.ts:204:3
    at _dispatchDescribe (.../jest-circus/build/index.js:98:26)
    at describe (.../jest-circus/build/index.js:60:5)
    at Object.<anonymous> (.../suites/anr/test.ts:109:1)
    at Runtime._execModule (.../jest-runtime/build/index.js:1646:24)
    at Runtime._loadModule (.../jest-runtime/build/index.js:1185:12)
    at Runtime.requireModule (.../jest-runtime/build/index.js:1009:12)
    at jestAdapter (.../build/legacy-code-todo-rewrite/jestAdapter.js:79:13)
    at processTicksAndRejections (node:internal/process/task_queues:105:5)
    at runTestInternal (.../jest-runner/build/runTest.js:389:16)

To view more test analytics, go to the Test Analytics Dashboard
_{📋 Got 3 mins? Take this short survey to help us improve Test Analytics.}

packages/core/src/log.ts

k-fish · 2025-02-20T20:20:03Z

packages/core/src/log.ts

+  trace: 1,
+  log: 2,
+  debug: 5,
+  info: 9,
+  warn: 13,
+  error: 17,
+  fatal: 21,


Suggested change

trace: 1,

log: 2,

debug: 5,

info: 9,

warn: 13,

error: 17,

fatal: 21,

trace: 1,

debug: 5,

info: 9,

log: 10,

warn: 13,

error: 17,

fatal: 21,

timfish · 2025-02-25T11:50:32Z

It's strange how this impacts bundle size. I would have expected the additional code to tree-shake out when it's not used!

Why is the _experiments.enableLogs option required? If users don't log anything via the new experimental API, logs wont be sent.

AbhiPrasad · 2025-02-26T19:10:50Z

It's strange how this impacts bundle size. I would have expected the additional code to tree-shake out when it's not used!

Yeah that feels weird to me too. I wonder if it's because of the log buffer side effect.

Why is the _experiments.enableLogs option required? If users don't log anything via the new experimental API, logs wont be sent.

Because we'll eventually also forward the console calls as logs, and that will be gated by _experiments.enableLogs. This experimental option will also graduate to be a top-level option, but we're bikeshedding naming because logs is super overloaded 😄

packages/core/src/log.ts

lforst · 2025-03-05T14:43:16Z

packages/core/src/exports.ts

+   * fatal(fmt`user ${username} just bought ${item}!`);
+   * ```
+   */
+  fatal: sendLog('fatal'),


This is the side-effect y'all are probably looking for.

k-fish · 2025-03-05T22:18:53Z

@AbhiPrasad we have to change the typing on the parametrize values to allow all the possible js types, do we want to change it or just make another function?

k-fish · 2025-03-05T22:50:03Z

@AbhiPrasad this #15600 maybe?

HofmannZ · 2025-03-06T08:36:28Z

How does this integrate with loggers like pino?

AbhiPrasad · 2025-03-06T14:33:01Z

How does this integrate with loggers like pino?

For now the focus is on frontend logging, but we'll have integrations for popular logging frameworks. You can see getsentry/sentry-docs#12920 for more details how SDKs will work with logging frameworks.

joshdales · 2025-03-07T11:03:19Z

Is there a reason that this couldn't be added to the Angular package as well?

Would be very nice if it could please 🥺

AbhiPrasad · 2025-03-11T15:43:03Z

@joshdales the angular package re-exports everything from the browser sdk, so this is included there.

The plan is that all JavaScript SDKs will have support for logs as soon as we're ready for users to use it :)

joshdales · 2025-03-11T16:02:46Z

@AbhiPrasad thanks for the context, as it wasn't included in the release notes I wasn't aware. Very excited to try this out 😄

AbhiPrasad · 2025-03-26T15:48:39Z

This can be closed, we split this PR up into multiple steps and merged it in accordingly: #15526

colin-sentry requested a review from AbhiPrasad February 18, 2025 20:09

colin-sentry force-pushed the colin/log-api branch from 1328016 to c5eb7fe Compare February 18, 2025 20:23

stephanie-anderson reviewed Feb 19, 2025

View reviewed changes

packages/core/src/ourlogs.ts Outdated Show resolved Hide resolved

stephanie-anderson reviewed Feb 19, 2025

View reviewed changes

packages/core/src/types-hoist/envelope.ts Outdated Show resolved Hide resolved

stephanie-anderson reviewed Feb 19, 2025

View reviewed changes

AbhiPrasad self-assigned this Feb 19, 2025

AbhiPrasad changed the title ~~feat(ourlogs): Add experimental user-callable logging methods~~ feat(logs): Add experimental user-callable logging methods Feb 20, 2025

colin-sentry commented Feb 20, 2025

View reviewed changes

packages/core/src/log.ts Outdated Show resolved Hide resolved

AbhiPrasad mentioned this pull request Feb 20, 2025

Branch for 9.2.0-alpha #15462

Closed

k-fish reviewed Feb 20, 2025

View reviewed changes

colin-sentry and others added 14 commits February 24, 2025 13:51

initial work on .log

bdcb9e1

improve a bit

4281cbe

linting, etc

1869d6f

fix: Rename ourlog -> log

4b89486

ref: Namespace logging methods in experiment obj

2fe0e1b

ref: Improve log creation logic and update option name

21b16e8

allow for multiple logs to be flushed in the same envelope

9ac58b1

feat: Add release and environment to logs

8fc4ae2

ref: Change log buffer max length from 100 -> 25

f3adcde

feat: Send severityNumber

bbc170d

ref: re-org functions and exports

bab4c6e

feat: Add log function

f750d08

fix: use correct severity number for log

7218377

chore: Bump size-limit

3e936c9

AbhiPrasad force-pushed the colin/log-api branch from 2a02335 to 3e936c9 Compare February 24, 2025 18:52

chore: size limit entries that were missed

b702cf0

fix: Duplicate export identifier

a8673b7

colin-sentry commented Mar 4, 2025

View reviewed changes

packages/core/src/log.ts Outdated Show resolved Hide resolved

ref: introduce format function and restructure exports

e9fa3bc

lforst reviewed Mar 5, 2025

View reviewed changes

AbhiPrasad added 2 commits March 5, 2025 09:57

Merge branch 'develop' into colin/log-api

2c3db7d

Merge branch 'develop' into colin/log-api

3ffc54b

AbhiPrasad mentioned this pull request Mar 5, 2025

Branch for 9.5.0-alpha #15596

Closed

chore: bump size-limit

cdf8bc5

AbhiPrasad added 7 commits March 6, 2025 10:46

fix: ParamaterizeString typing to allow more than string values

0e77407

feat: Add parent_span_id to outgoing logs

4d0678a

feat: Export logging methods for node/server-side SDKs

7b83155

fix: Set parent_span_id properly

6994781

fix: Remove unneeded import

8602f81

chore: bump size-limit

7d22aa2

Merge branch 'develop' into colin/log-api

d7e3479

AbhiPrasad mentioned this pull request Mar 6, 2025

Branch for 9.6.0-alpha #15614

Closed

colin-sentry and others added 4 commits March 11, 2025 16:26

Merge branch 'develop' into colin/log-api

bbb1698

feat(buffer): Add beforeSendLogs for sampling decisions

c4b6d2d

clean up

1da9a7f

remove old comment

5b66ccf

AbhiPrasad closed this Mar 26, 2025

AbhiPrasad deleted the colin/log-api branch March 26, 2025 15:48

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(logs): Add experimental user-callable logging methods #15442

feat(logs): Add experimental user-callable logging methods #15442

colin-sentry commented Feb 18, 2025 •

edited by AbhiPrasad

Loading

github-actions bot commented Feb 18, 2025 •

edited

Loading

stephanie-anderson Feb 19, 2025

AbhiPrasad Feb 20, 2025

codecov bot commented Feb 20, 2025 •

edited

Loading

k-fish Feb 20, 2025

timfish commented Feb 25, 2025 •

edited

Loading

AbhiPrasad commented Feb 26, 2025

lforst Mar 5, 2025

k-fish commented Mar 5, 2025

k-fish commented Mar 5, 2025

HofmannZ commented Mar 6, 2025

AbhiPrasad commented Mar 6, 2025

joshdales commented Mar 7, 2025 •

edited

Loading

AbhiPrasad commented Mar 11, 2025

joshdales commented Mar 11, 2025

AbhiPrasad commented Mar 26, 2025

feat(logs): Add experimental user-callable logging methods #15442

feat(logs): Add experimental user-callable logging methods #15442

Conversation

colin-sentry commented Feb 18, 2025 • edited by AbhiPrasad Loading

github-actions bot commented Feb 18, 2025 • edited Loading

size-limit report 📦

stephanie-anderson Feb 19, 2025

Choose a reason for hiding this comment

AbhiPrasad Feb 20, 2025

Choose a reason for hiding this comment

codecov bot commented Feb 20, 2025 • edited Loading

❌ 1 Tests Failed:

k-fish Feb 20, 2025

Choose a reason for hiding this comment

timfish commented Feb 25, 2025 • edited Loading

AbhiPrasad commented Feb 26, 2025

lforst Mar 5, 2025

Choose a reason for hiding this comment

k-fish commented Mar 5, 2025

k-fish commented Mar 5, 2025

HofmannZ commented Mar 6, 2025

AbhiPrasad commented Mar 6, 2025

joshdales commented Mar 7, 2025 • edited Loading

AbhiPrasad commented Mar 11, 2025

joshdales commented Mar 11, 2025

AbhiPrasad commented Mar 26, 2025

colin-sentry commented Feb 18, 2025 •

edited by AbhiPrasad

Loading

github-actions bot commented Feb 18, 2025 •

edited

Loading

codecov bot commented Feb 20, 2025 •

edited

Loading

timfish commented Feb 25, 2025 •

edited

Loading

joshdales commented Mar 7, 2025 •

edited

Loading