Code Guidelines

Apply these guidelines to all new and modified code across every package in this monorepo. Existing code may not follow these conventions — do not refactor it unless asked.

Use only language features available in the Dart/Flutter versions specified in AGENTS.md.

For non-trivial work — a new feature or integration, a public barrel-file change, or a cross-package/native-interop change — load the design-first skill to shape the modules and seams before writing code. When writing or modifying tests as part of implementation, also load the test-guidelines skill.

SDK Development Rules

Integrations

Encapsulate SDK features as Integration classes that implement call() and close():

• Check feature flags and prerequisites early, log and return if disabled
• Mark the integration as active for usage tracking — see Usage Tracking below
• Clean up resources in close() if needed
• See packages/flutter/lib/src/integrations/ for examples
• Integrations should be order-independent; if yours requires running before/after another, reconsider the design

Usage Tracking

Record which integrations and features an app actually uses, so usage can be tracked internally. This metadata lives on options.sdk and is serialized onto events as sdk.integrations / sdk.features.

• options.sdk.addIntegration('IntegrationName') — mark an integration as active. Call it from the integration's call(). Do not confuse it with options.addIntegration(integration), which registers an integration to run — options.sdk.addIntegration only attaches the name as metadata.
• options.sdk.addFeature(SentryFeatures.x) — mark a feature as used, gated on whether it is actually configured (e.g. a beforeSend* callback is set, a privacy option is enabled).
• Use named constants from SentryFeatures (packages/dart/lib/src/constants.dart, @internal) — never inline string literals — so the analytics vocabulary stays consistent. Add a constant there when introducing a new feature.
• Both calls dedupe, so calling them more than once is safe.
• Canonical example: TrackBeforeSendUsageIntegration (packages/dart/lib/src/track_before_send_usage_integration.dart).

Logging

Use internalLogger for all diagnostic logging. options.log is deprecated — migrate any options.log calls you encounter to internalLogger.

Each package must have its own internalLogger instance. If one doesn't exist, create lib/src/internal_logger.dart:

import 'package:meta/meta.dart';
import 'package:sentry/sentry.dart';

/// Logger for the Sentry <Package> SDK.
@internal
const internalLogger = SentryInternalLogger('sentry_<package>');

Log levels:

Lazy evaluation — use a closure when the message involves expensive computation:

internalLogger.debug(() => 'Envelope size: ${envelope.computeSize()}');

Logs are debug-only — all logging is tree-shaken in release builds via RuntimeChecker.kDebugMode.

Privacy

• Never collect Personally Identifiable Information (PII) without checking options.sendDefaultPii
• Flag any changes that could leak PII for review

Breaking Changes

• Signal breaking changes clearly (API removals, behavior changes, renamed options)
• Prefer deprecation with migration path over immediate removal

Native Code (JNI/FFI)

• Release all native memory (JNI local refs, malloc allocations)
• Handle native exceptions gracefully—don't crash the host app

File Organization

Group by feature, not by type. A processor or integration a feature owns lives in that feature's dir (a replay processor in replay/); a cross-cutting one earns its own top-level concept dir (exception/, enricher/). Cohesive subsystems already do this — transport/, telemetry/span/, and native/ (the binding boundary to the platform SDKs; features call it rather than embed native code). Native interop is special for testing and memory, not for placement — see design-first and the Native Code (JNI/FFI) rules above.

Two shapes are scatter — grow neither, and don't read the repo's current use of them as the target:

• Type-buckets (event_processor/, integrations/) collect classes for sharing a base type. A bucket legitimately holds only its runner (run_event_processors.dart); the base contract belongs at src/ root (event_processor.dart, beside integration.dart). The repo hasn't finished migrating — enrichment, exceptions, and dedup still sit under event_processor/, and flutter has loose replay_event_processor/screenshot_event_processor.
• The loose src/ root. Core primitives (hub.dart, scope.dart, sentry_client.dart, the sentry.dart barrel) belong there; feature code does not. The v1 span/tracer files strewn across the root, protocol/, and tracing/ are the counter-example to telemetry/span/, which keeps the whole v2 subsystem in one dir.

Where a given piece goes is a locality judgment — see design-first (Shape the modules).