Feature request: hints

[jpnurmi]

Allow callers to pass sentry_hint_t to event capture and use it in before_send callbacks, matching the hint support already available for feedback. This enables event-specific attachments, including attachments added by callbacks before sending.

Hints are particularly useful for downstream SDK integrations. Applications that do not need them should ideally retain convenient capture calls. The design therefore needs to balance migration costs, everyday usability, and the number of API variants.

The tables below show call signatures; return types remain unchanged. All hint arguments accept NULL.

Option 1: Preserve existing capture signatures

Add _with_hint alternatives for global and scoped event capture.

Before	After
sentry_capture_event(event)	Unchanged
—	Add sentry_capture_event_with_hint(event, hint)
sentry_scope_capture_event(scope, event)	Unchanged
—	Add sentry_scope_capture_event_with_hint(scope, event, hint)
sentry_capture_feedback(feedback)	Unchanged
sentry_capture_feedback_with_hint(feedback, hint)	Unchanged
sentry_scope_capture_feedback(scope, feedback, hint)	Unchanged

Breaking consequences: No existing capture calls change. The shared before_send callback change described below still applies.

Tradeoffs:

• Preserves convenient event capture without hints.
• Lets integrations opt into hints explicitly.
• Adds two functions.
• Leaves scoped event capture with two variants, while scoped feedback has one function accepting a hint.

Sentry Go provides a precedent for this approach:

Without a hint	With a hint
Hub.CaptureEvent(event)	Hub.CaptureEventWithHint(event, hint)

Hub.CaptureEvent delegates to Hub.CaptureEventWithHint(event, nil), preserving convenient capture for users who do not need hints.

Option 2: Keep _with_hint alternatives only for global capture

Preserve global capture signatures, but add a hint argument directly to scoped event capture, matching scoped feedback. This is the current implementation.

Before	After
sentry_capture_event(event)	Unchanged
—	Add sentry_capture_event_with_hint(event, hint)
sentry_scope_capture_event(scope, event)	sentry_scope_capture_event(scope, event, hint)
sentry_capture_feedback(feedback)	Unchanged
sentry_capture_feedback_with_hint(feedback, hint)	Unchanged
sentry_scope_capture_feedback(scope, feedback, hint)	Unchanged

Breaking consequences: Existing scoped event callers must add a hint or NULL. Global capture calls remain compatible. The shared callback change also applies.

Tradeoffs:

• Preserves convenient global capture without hints, using the separate-alternative pattern shown in Sentry Go above.
• Makes scoped event and feedback capture consistent.
• Adds only one function.
• Requires scoped event callers to pass NULL even when they only want to apply a scope.
• Limits capture signature changes to the relatively recently introduced scoped event API.

Option 3: Accept hints directly in all event and feedback capture functions

Use one function for each capture operation, always accepting a hint argument.

Before	After
sentry_capture_event(event)	sentry_capture_event(event, hint)
sentry_scope_capture_event(scope, event)	sentry_scope_capture_event(scope, event, hint)
sentry_capture_feedback(feedback)	sentry_capture_feedback(feedback, hint)
sentry_capture_feedback_with_hint(feedback, hint)	Remove; use sentry_capture_feedback(feedback, hint)
sentry_scope_capture_feedback(scope, feedback, hint)	Unchanged

No sentry_capture_event_with_hint function would be introduced.

Breaking consequences: Global event, global feedback, and scoped event callers must add a hint or NULL. Existing feedback _with_hint callers must rename their calls. The shared callback change also applies.

Tradeoffs:

• Provides consistent signatures without _with_hint alternatives.
• Requires migration of the widely used sentry_capture_event API.
• Introduces permanent friction for applications that do not need hints: even basic capture requires sentry_capture_event(event, NULL).

Go's lower-level client API illustrates accepting a hint directly:

API	Signature
Client.CaptureEvent	CaptureEvent(event *Event, hint *EventHint, scope EventModifier)

Source. Go also retains the convenient Hub functions shown in Option 1, so this is precedent for explicit hints at a lower level, rather than requiring them throughout the public capture API.

Callback changes shared by all options

Change the before_send hint parameter from void * to sentry_hint_t *. Feedback already uses the typed hint.

Callback	Before	After
before_send	(sentry_value_t event, void *hint, void *user_data)	(sentry_value_t event, sentry_hint_t *hint, void *user_data)
before_send_feedback	(sentry_value_t feedback, sentry_hint_t *hint, void *user_data)	Unchanged

This is a breaking callback signature change. Return types and callback registration functions remain unchanged.

External usage and migration impact

The relevant migration burden is external applications and libraries, excluding Sentry projects, downstream SDKs, forks, and vendored SDK code.

The earlier manually filtered search reported:

Existing API	External caller files	External repositories	Capture calls affected by
sentry_capture_event	75	69	Option 3
sentry_capture_feedback	3	2	Option 3
sentry_capture_feedback_with_hint	1	1	Option 3

These are provisional historical counts, not an exhaustive census; the saved results are no longer available to reverify. They count files containing callers, not individual calls. No verified external counts were established for scoped event capture or before_send.

Inspect sentry_capture_event usage on GitHub. This query excludes Sentry organizations, forks, sentry.h, and sentry_core.c; downstream SDKs and other SDK copies still require manual filtering. The browser query has not been successfully verified and does not reproduce the counts above.

Comparison

Consideration	Option 1	Option 2	Option 3
Existing global capture calls	Preserved	Preserved	Must migrate
Existing scoped event calls	Preserved	Must migrate	Must migrate
Global capture without hints	No extra argument	No extra argument	Must pass NULL
Scoped event capture without hints	No extra argument	Must pass NULL	Must pass NULL
API variants	Global and scoped event alternatives	Global alternatives only	No alternatives
before_send callback signature	Breaking change	Breaking change	Breaking change

Option 1 prioritizes compatibility and convenience. Option 2 preserves global convenience while making scoped event and feedback capture consistent. Option 3 reduces API variants but imposes migration work and ongoing extra arguments on callers who do not need hints.

[linear-code]

NATIVE-229

[jpnurmi]

Given that:

• before_send has barely any external non-fork/non-sentry users
• sentry_capture_event is naturally more widely used
• direct native SDK users barely ever need hints
• downstream SDKs almost exclusively use scope APIs

We don't:

• mind breaking before_send signature, which already has void *hint (very low friction)
• want to break sentry_capture_xxx by adding hint arguments
• need global sentry_capture_xxx_with_hint overloads
• need multiple scope-level overloads

Conclusion: we'll extend sentry_scope_capture_xxx with a hint argument and eventually get rid of the _with_hint overloads in the scope API.