feat(logs): Add Hint to beforeSend for logs, metrics, and spans

[buenaflor]

beforeSendLog, beforeSendMetric, and beforeSendSpan now receive a Hint as their second argument, matching beforeSend and beforeSendTransaction. This is a breaking change: user-defined callbacks must add the parameter.

// before
options.beforeSendLog = (log) { ...; return log; };
// after
options.beforeSendLog = (log, hint) { ...; return log; };

Each capture pipeline creates a single Hint and threads that same instance through the OnProcessLog/OnProcessMetric/OnProcessSpan lifecycle event and then into the callback. That's the mechanism that makes the hint useful: an SDK-side lifecycle callback can enrich the hint before beforeSend* reads it, since both hold the same instance.

// SDK/integration side (lifecycle callbacks are @internal)
options.lifecycleRegistry.registerCallback<OnProcessSpan>((event) {
  if (event.span.name == 'db.query') {
    event.hint.set('raw_statement', stmt);
  }
});
// user callback receives the same populated hint
options.beforeSendSpan = (span, hint) => hint.get('raw_statement');

Scope notes for reviewers:

• Public capture APIs (captureLog/captureMetric/captureSpan on Hub/Client) are intentionally unchanged — nobody emits through them directly, so a hint parameter there would have no caller. The hint is created in the pipeline.
• An emit-time seam for populating the hint from user code (e.g. Sentry.logger.info(hint:), or a hint carried on a live span) is deliberately deferred. It's a non-breaking addition and there's no populator today; the breaking signature change is what has to land in v10.
• Also migrates the metric pipeline's callback-error log from the deprecated options.log to internalLogger.

Each pipeline gains a test asserting the callback receives the same Hint instance dispatched to its OnProcess* event, so the threading can't silently regress.

Fixes #3836

[github-actions]

Semver Impact of This PR

🟡 Minor (new features)

📋 Changelog Preview

This is how your changes will appear in the changelog.
Entries from this PR are highlighted with a left border (blockquote style).

---

Features

• (grpc) Add integration support for GRPC by lucas-zimerman in #3721

• (logs) Add Hint to beforeSend for logs, metrics, and spans by buenaflor in #3847

Fixes

• Correct feature flag scope buffer updates by denrase in #3797

Dependencies

Deps

• chore(deps): update Android SDK to v8.46.0 by github-actions in #3793
• chore(deps): update Native SDK to v0.15.2 by github-actions in #3785

Internal Changes

• (skills) Expand test-guidelines and drop stale deps by buenaflor in #3807
• Add PR template checkbox for cross sdk review on public API changes by antonis in #3822
• Block manual CHANGELOG.md edits by buenaflor in #3810
• Fix Dependabot pub paths and pin GitHub Action by buenaflor in #3804
• Add AI Use section to CONTRIBUTING.md by christophaigner in #3803

---

_{🤖 This preview updates automatically when you update the PR.}

[codecov]

Codecov Report

❌ Patch coverage is 92.30769% with 1 line in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (v10-branch@59d7c7b). Learn more about missing BASE report.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
.../src/telemetry/metric/metric_capture_pipeline.dart	75.00%	1 Missing ⚠️

Additional details and impacted files

@@              Coverage Diff              @@
##             v10-branch    #3847   +/-   ##
=============================================
  Coverage              ?   87.30%           
=============================================
  Files                 ?      337           
  Lines                 ?    12260           
  Branches              ?        0           
=============================================
  Hits                  ?    10704           
  Misses                ?     1556           
  Partials              ?        0           

Flag	Coverage Δ
sentry	87.25% <92.30%> (?)
sentry_dio	97.73% <ø> (?)
sentry_drift	93.57% <ø> (?)
sentry_file	65.29% <ø> (?)
sentry_firebase_remote_config	100.00% <ø> (?)
sentry_flutter	91.33% <ø> (?)
sentry_grpc	99.09% <ø> (?)
sentry_hive	77.48% <ø> (?)
sentry_isar	74.37% <ø> (?)
sentry_link	21.50% <ø> (?)
sentry_logging	97.01% <ø> (?)
sentry_sqflite	88.81% <ø> (?)
sentry_supabase	97.27% <ø> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

[Copilot]

Pull request overview

This PR updates the Sentry Dart/Flutter telemetry pipelines so beforeSendLog, beforeSendMetric, and beforeSendSpan receive a Hint (as their second parameter), matching the beforeSend / beforeSendTransaction pattern and enabling lifecycle callbacks to enrich the hint before user callbacks run.

Changes:

• Add Hint to the BeforeSendLogCallback, BeforeSendMetricCallback, and BeforeSendSpanCallback typedefs.
• Thread a single Hint instance through each capture pipeline: OnProcess* lifecycle event → beforeSend* callback; add tests asserting the same instance is observed.
• Update metric callback error logging to use internalLogger instead of the deprecated options.log.

Standards

• 1 finding: BeforeSendMetricCallback doc comment contradicts the actual return type/behavior (it describes true/false, but the callback returns SentryMetric?, where null drops the metric).

Spec

• 0 findings: matches the issue/PR description (adds Hint param, constructs/passes Hint in pipelines, adds regression tests for “same instance” threading, updates call sites).

Correctness

• 0 findings: updated call sites appear consistent; internalLogger.error(..., error: ..., stackTrace: ...) matches the logger API; tests cover the new hint-threading invariant.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
packages/dart/lib/src/sentry_options.dart	Update beforeSend* callback typedefs to include Hint (public API change).
packages/dart/lib/src/sdk_lifecycle_hooks.dart	Add Hint to OnProcessLog / OnProcessMetric / OnProcessSpan lifecycle events.
packages/dart/lib/src/telemetry/log/log_capture_pipeline.dart	Create one Hint per log capture and pass it through lifecycle + beforeSendLog.
packages/dart/lib/src/telemetry/metric/metric_capture_pipeline.dart	Create one Hint per metric capture, pass it through lifecycle + beforeSendMetric, and log callback errors via internalLogger.
packages/dart/lib/src/telemetry/span/span_capture_pipeline.dart	Create one Hint per span capture and pass it through lifecycle + beforeSendSpan.
packages/dart/test/telemetry/log/log_capture_pipeline_test.dart	Update callback signatures and add test asserting lifecycle/callback see the same Hint instance.
packages/dart/test/telemetry/metric/metric_capture_pipeline_test.dart	Update callback signatures and add test asserting lifecycle/callback see the same Hint instance.
packages/dart/test/telemetry/span/span_capture_pipeline_test.dart	Update callback signatures and add test asserting lifecycle/callback see the same Hint instance.
packages/dart/test/track_before_send_usage_integration_test.dart	Update callback signatures used for feature tracking.
packages/dart/test/event_processor/enricher/enricher_integration_test.dart	Update lifecycle dispatch call sites to pass Hint().
packages/flutter/test/integrations/replay_telemetry_integration_test.dart	Update lifecycle dispatch call sites to pass Hint().
packages/flutter/test/integrations/load_contexts_integration_test.dart	Update lifecycle dispatch call sites to pass Hint().
packages/flutter/example/lib/main.dart	Update example beforeSendMetric / beforeSendSpan callback signatures to include Hint.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.