overview_dev.mdc

---
alwaysApply: true
description: Sentry Java SDK - Development Rules Overview
---

# Sentry Java SDK Development Rules

## Always Applied Rules

These rules are automatically included in every conversation:
- **coding.mdc**: General contributing guidelines, build commands, and workflow rules

## Domain-Specific Rules (Fetch Only When Needed)

Use the `fetch_rules` tool to include these rules when working on specific areas:

### Core SDK Functionality
- **`api`**: Use when working with:
  - Adding or modifying public API surface
  - Binary compatibility, `.api` files, `apiDump`
  - Understanding which classes to modify for new API (interfaces, implementations, no-ops, adapters)
  - `IScope`, `IScopes`, `Sentry` static API
  - Attributes, logging API, protocol classes

- **`options`**: Use when working with:
  - Adding or modifying SDK options (`SentryOptions`, namespaced options)
  - External options (`ExternalOptions`, `sentry.properties`, environment variables)
  - Android manifest metadata (`ManifestMetadataReader`)
  - Spring Boot properties (`SentryProperties`)

- **`scopes`**: Use when working with:
  - Hub/Scope management, forking, or lifecycle
  - `Sentry.getCurrentScopes()`, `pushScope()`, `withScope()`
  - `ScopeType` (GLOBAL, ISOLATION, CURRENT)
  - Thread-local storage, scope bleeding issues
  - Migration from Hub API (v7 → v8)

- **`deduplication`**: Use when working with:
  - Duplicate event detection/prevention
  - `DuplicateEventDetectionEventProcessor`
  - `enableDeduplication` option

- **`offline`**: Use when working with:
  - Caching, envelope storage/retrieval
  - Network failure handling, retry logic
  - `AsyncHttpTransport`, `EnvelopeCache`
  - Rate limiting, cache rotation
  - Android vs JVM caching differences

- **`feature_flags`**: Use when working with:
  - Feature flag tracking and evaluation
  - `addFeatureFlag()`, `getFeatureFlags()` methods
  - `FeatureFlagBuffer`, `SpanFeatureFlagBuffer`, `FeatureFlag` protocol
  - `maxFeatureFlags` option and buffer management
  - Feature flag merging across scope types
  - Scope-based vs span-based feature flag APIs
  - Scope-based API: `Sentry`, `IScopes`, `IScope` APIs
  - Span-based API: `ISpan`, `ITransaction` APIs
  - Integrations: LaunchDarkly (Android/JVM), OpenFeature (JVM)

- **`metrics`**: Use when working with:
  - Metrics API (`Sentry.metrics()`, `IScopes.metrics()`)
  - `IMetricsApi`, `MetricsApi` implementation
  - Metrics types: `count`, `distribution`, `gauge`
  - `MetricsBatchProcessor`, batching and queue management
  - `SentryMetricsEvent`, `SentryMetricsEvents`
  - `SentryOptions.getMetrics()`, `beforeSend` callback

- **`queues`**: Use when working with:
  - Sentry Queues product data or messaging span conventions
  - Queue tracing spans/transactions (`queue.publish`, `queue.process`)
  - `enableQueueTracing` option and `sentry.enable-queue-tracing`
  - Kafka instrumentation (`sentry-kafka`, `SentryKafkaProducer`, `SentryKafkaConsumerTracing`)
  - Spring Kafka queue auto-instrumentation and `SentryKafkaRecordInterceptor`
  - Messaging span data (`messaging.system`, `messaging.destination.name`, receive latency, retry count)
  - `sentry-task-enqueued-time` header and distributed trace propagation through queues

- **`continuous_profiling_jvm`**: Use when working with:
  - JVM continuous profiling (`sentry-async-profiler` module)
  - `IContinuousProfiler`, `JavaContinuousProfiler`
  - `ProfileChunk`, chunk rotation, JFR file handling
  - `ProfileLifecycle` (MANUAL vs TRACE modes)
  - async-profiler integration, ServiceLoader discovery
  - Rate limiting, offline caching, scopes integration

- **Android profiling**: There is currently no dedicated rule for this area yet.
  - Inspect the relevant `sentry-android-core` profiling code directly
  - Fetch other related rules as needed (for example `options`, `offline`, or `api`)

### Integration & Infrastructure
- **`opentelemetry`**: Use when working with:
  - OpenTelemetry modules (`sentry-opentelemetry-*`)
  - Agent vs agentless configurations
  - Span processing, sampling, context propagation
  - `OtelSpanFactory`, `SentrySpanExporter`
  - Tracing, distributed tracing

- **`new_module`**: Use when adding a new integration or sample module

### Workflow
- **`pr`**: Use when working with:
  - Creating pull requests
  - Stacked PRs, PR naming, stack comments
  - PR changelog entries
  - Merging or syncing stacked branches

### Testing
- **`e2e_tests`**: Use when working with:
  - System tests, sample applications
  - `system-test-runner.py`, mock Sentry server
  - End-to-end test infrastructure
  - CI system test workflows

## Usage Guidelines

1. **Start minimal**: Only include `coding.mdc` (auto-applied) for general tasks
2. **Fetch on-demand**: Use `fetch_rules ["rule_name"]` when you identify specific domain work
3. **Multiple rules**: Fetch multiple rules if task spans domains (e.g., `["scopes", "opentelemetry"]` for tracing scope issues)
4. **Context clues**: Look for these keywords in requests to determine relevant rules:
   - Public API/apiDump/.api files/binary compatibility/new method → `api`
   - Options/SentryOptions/ExternalOptions/ManifestMetadataReader/sentry.properties → `options`
   - Scope/Hub/forking → `scopes`
   - Duplicate/dedup → `deduplication`
   - OpenTelemetry/tracing/spans → `opentelemetry`
   - new module/integration/sample → `new_module`
   - Cache/offline/network → `offline`
   - System test/e2e/sample → `e2e_tests`
   - Feature flag/addFeatureFlag/flag evaluation → `feature_flags`
   - Metrics/count/distribution/gauge → `metrics`
   - Queues/queue tracing/Kafka/Spring Kafka/queue.publish/queue.process/enableQueueTracing/messaging spans → `queues`
   - PR/pull request/stacked PR/stack → `pr`
   - JVM continuous profiling/async-profiler/JFR/ProfileChunk → `continuous_profiling_jvm`
   - Android continuous profiling/AndroidProfiler/frame metrics/method tracing → no dedicated rule yet; inspect the code directly