Skip to content

JetBrains/intellij-community / .claude/skills/compose-ui

compose-ui

Verified

Write or audit Compose Desktop UI state, effects, and boundaries.

FileKindSize
OWNERSHIPother20 B
SKILL.mdskill md637 B
architecture/GUIDE.mdmarkdown5.7 KB
architecture/evals/evals.jsonconfig6.5 KB
architecture/references/animation.mdmarkdown11.3 KB
architecture/references/component-api-lists-performance.mdmarkdown4.1 KB
architecture/references/desktop-seams-review-output.mdmarkdown1.5 KB
architecture/references/effects.mdmarkdown1.7 KB
architecture/references/state-boundaries.mdmarkdown5.4 KB
architecture/skill-source.jsonconfig2.0 KB
audit/GUIDE.mdmarkdown14.1 KB
audit/evals/evals.jsonconfig18.1 KB
audit/references/api-hygiene.mdmarkdown8.8 KB
audit/references/audit-search-patterns.mdmarkdown3.9 KB
audit/references/boundary-violations.mdmarkdown3.3 KB
audit/references/effects/derived-state-of-guide.mdmarkdown2.2 KB
audit/references/effects/effect-selection-guide.mdmarkdown2.7 KB
audit/references/effects/infinite-loop-patterns.mdmarkdown2.6 KB
audit/references/effects/overview.mdmarkdown7.7 KB
audit/references/lazy-layouts/animate-item.mdmarkdown2.0 KB
audit/references/lazy-layouts/cache-window-and-prefetch.mdmarkdown3.2 KB
audit/references/lazy-layouts/desktop-scroll-measurement.mdmarkdown2.0 KB
audit/references/lazy-layouts/keys-and-content-type.mdmarkdown2.2 KB
audit/references/lazy-layouts/nested-lazy-layouts.mdmarkdown1.6 KB
audit/references/lazy-layouts/overview.mdmarkdown7.5 KB
audit/references/measurement/benchmarking-methodology.mdmarkdown1.9 KB
audit/references/measurement/overview.mdmarkdown5.5 KB
audit/references/measurement/profiler-setup.mdmarkdown2.5 KB
audit/references/modifiers/custom-modifier-node.mdmarkdown3.4 KB
audit/references/modifiers/modifier-order.mdmarkdown2.1 KB
audit/references/modifiers/overview.mdmarkdown7.4 KB
audit/references/modifiers/phase-deferral.mdmarkdown2.6 KB
audit/references/reporting-guidance.mdmarkdown2.3 KB
audit/references/stability/ci-stability-gate.mdmarkdown2.0 KB
audit/references/stability/desktop-measurement.mdmarkdown2.2 KB
audit/references/stability/overview.mdmarkdown7.6 KB
audit/references/stability/reading-classes-txt.mdmarkdown2.1 KB
audit/references/stability/reading-composables-txt.mdmarkdown1.9 KB
audit/references/stability/stabilising-types.mdmarkdown3.1 KB
audit/references/stability/stability-config-syntax.mdmarkdown1.6 KB
audit/references/stability/stability-inference-algorithm.mdmarkdown3.4 KB
audit/references/stability/strong-skipping-escape-hatches.mdmarkdown2.6 KB
audit/references/subcomposition/desktop-subcomposition-measurement.mdmarkdown1.7 KB
audit/references/subcomposition/overview.mdmarkdown7.2 KB
audit/references/subcomposition/subcomposition-decision-tree.mdmarkdown1.8 KB
audit/references/subcomposition/swing-panel-subcomposition.mdmarkdown1.8 KB
audit/references/tracing-setup.mdmarkdown5.3 KB
audit/references/tracing-usage.mdmarkdown6.3 KB
audit/skill-source.jsonconfig2.5 KB

audit/references/tracing-usage.md

View on GitHub
# Tracing API Usage Guide

This guide covers how to use the AndroidX Tracing 2.0 API for adding custom trace sections and metadata.

---

## Basic Trace Sections

### Sync blocks

```kotlin
AppTracing.trace(AppTracing.CATEGORY_STATE, "buildTimeline") {
    // work to trace
}
```

### Suspend blocks (with coroutine context propagation)

```kotlin
AppTracing.traceCoroutine(AppTracing.CATEGORY_MARKDOWN, "processAssistantText") {
    withContext(dispatcher) {
        // async work to trace
    }
}
```

The `traceCoroutine` variant automatically propagates the coroutine context, so the trace continues across
suspend/resume boundaries on different threads.

---

## Categories (Semantic Grouping)

Define categories for different subsystems:

```kotlin
object AppTracing {
    const val CATEGORY_UI = "ui"
    const val CATEGORY_STATE = "state"
    const val CATEGORY_MARKDOWN = "markdown"
    const val CATEGORY_RPC = "rpc"
    const val CATEGORY_DB = "db"
    const val CATEGORY_NETWORK = "network"
}
```

Categories appear in Perfetto UI and help filter/find slices.

---

## Adding Metadata (KVPs)

For rich trace data, use `EventMetadata` to add key-value pairs:

```kotlin
val tracer = AppTracing.tracer ?: return buildTimeline()

val metadata = tracer.beginSectionWithMetadata(
    category = "state",
    name = "buildTimeline",
    token = null,  // null = auto-propagate
    isRoot = false,
)

// Add metadata entries
metadata.addMetadataEntry("messageCount", messages.size)
metadata.addMetadataEntry("workspaceRoot", workspaceRoot.toString())
metadata.addMetadataEntry("isStreaming", isStreaming)

// Optional: add correlation ID to link with other traces
// metadata.addCorrelationId(correlationId)

try {
    // work
} finally {
    metadata.dispatchToTraceSink()
    metadata.close()
}
```

### Available metadata types

| Method | Type | Example |
|--------|-----|---------|
| `addMetadataEntry(name, String)` | Text | `"userId": "user_123"` |
| `addMetadataEntry(name, Long)` | Integer | `"messageCount": 42` |
| `addMetadataEntry(name, Double)` | Floating | `"latencyMs": 15.5` |
| `addMetadataEntry(name, Boolean)` | Flag | `"isStreaming": true` |
| `addCorrelationId(Long)` | ID | Link traces across threads |
| `addCorrelationId(String)` | ID | Link traces across threads |

---

## Why Add Metadata?

1. **Debugging**: See actual values (counts, sizes, IDs) directly in the trace without guessing
2. **Filtering**: Find slices by metadata in PerfettoSQL: `WHERE messageCount > 100`
3. **Correlation**: Link related traces (e.g., RPC request → DB query → response)
4. **Debug**: `addCallStackEntry` shows where the trace section was created

Example PerfettoSQL (metadata is in the `args` table, joined via `arg_set_id`):

```sql
SELECT s.name, s.dur / 1000 as duration_ms,
       EXTRACT_ARG(s.arg_set_id, 'messageCount') as message_count
FROM slice s
WHERE s.name = 'buildTimeline'
ORDER BY s.dur DESC
```

---

## Propagation Tokens

Tokens connect trace sections across threads or coroutines:

```kotlin
val token = tracer.tokenFromCoroutineContext()  // Auto from coroutine context

// Or create a custom flow ID:
val flowId = System.nanoTime()  // Unique per trace flow

val section = tracer.beginSection(
    category = "rpc",
    name = "executeTool",
    token = object : PropagationToken {
        override fun contextElementOrNull(): CoroutineContext.Element? = null
    },
    isRoot = false,
)
```

When `token = null`, the tracer automatically uses `tokenFromCoroutineContext()` to propagate across coroutine
suspend/resume boundaries.

---

## Best Practices

### 1. Always use the facade

```kotlin
// Good: uses AppTracing which handles null tracer
AppTracing.trace("state", "buildTimeline") { ... }

// Avoid: raw tracer calls without null check
tracer.trace(...)  // Risk: NPE when tracing disabled
```

### 2. Use categories consistently

- `ui` — Compose recomposition, layout, drawing
- `state` — presenter/state holder transformations
- `markdown` — text processing
- `rpc` — subprocess communication
- `db` — database operations (if any)

### 3. Keep span names stable

```kotlin
// Good: stable operation name
AppTracing.trace("state", "buildTimeline") { ... }

// Avoid: including variable data in span name
// This creates one slice per unique message!
AppTracing.trace("state", "processed ${message.id}") { ... }
// Instead use metadata:
AppTracing.trace("state", "processMessage") {
    val metadata = ...
    metadata.addMetadataEntry("messageId", message.id)
}
```

### 4. Don't trace too finely

```kotlin
// Coarse is better:
// Single span for whole operation
AppTracing.trace("markdown", "processMessage") {
    // everything
}

// Fine-grained is harder to read:
AppTracing.trace("markdown", "enrichFileLinks") { ... }
AppTracing.trace("markdown", "parseMarkdown") { ... }
AppTracing.trace("markdown", "buildBlocks") { ... }
```

### 5. Use metadata for variable data

```kotlin
// Good: stable name + metadata via beginSectionWithMetadata
val tracer = AppTracing.tracer ?: return process(message)
val meta = tracer.beginSectionWithMetadata(category = "state", name = "processMessage", token = null, isRoot = false)
meta.addMetadataEntry("messageId", message.id)
meta.addMetadataEntry("blockCount", blocks.size)
try {
    process(message)
} finally {
    meta.dispatchToTraceSink()
    meta.close()
}

// Bad: creates one slice per unique message ID
AppTracing.trace("state", "processMessage:${message.id}") { ... }
```

---

## Complete Example

```kotlin
suspend fun processMessage(message: Message): RenderModel {
    val tracer = AppTracing.tracer
    if (tracer == null) return buildRenderModel(listOf(message))

    val meta = tracer.beginSectionWithMetadata(
        category = AppTracing.CATEGORY_STATE,
        name = "buildRenderModel",
        token = null,  // auto-propagates coroutine context
        isRoot = false,
    )
    meta.addMetadataEntry("workspaceRoot", workspaceRoot.toString())

    return try {
        buildRenderModel(listOf(message)).also {
            meta.addMetadataEntry("messageCount", 1)
        }
    } finally {
        meta.dispatchToTraceSink()
        meta.close()
    }
}
```

---

## Resources

- [AndroidX Tracing API](https://developer.android.com/reference/androidx/tracing/package-summary)
- [Perfetto UI](https://ui.perfetto.dev)
- [PerfettoSQL reference](https://perfetto.dev/docs/analysis/trace-processor)
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall