performance-requirements

name	performance-requirements
description	ClrProfiler-specific performance and memory requirements for CLR EventListener callbacks, GC event correlation, bounded channels, timer sampling, statistics values, callback dispatch, and Datadog or logger metric projection. Use when changing event ingestion, listener or timer hot paths, statistics models, tracker concurrency, or metric formatting and tag caching.

Performance Requirements

Treat overhead added to the profiled process as part of ClrProfiler's correctness. Apply these requirements to changes in src/ClrProfiler and src/ClrProfiler.DatadogTracing that run per CLR event, per timer tick, or per emitted metric.

Protect the producer path

• Keep EventListener.OnEventWritten, EventCreatedHandler, and ProcessEvent bounded and non-blocking. Never wait synchronously for user callbacks, logging, network I/O, or channel capacity.
• Parse only the payload fields needed by the matched event. Prefer typed payload values and invariant conversion; avoid ToString plus Parse on the normal path when the runtime already supplies a numeric value.
• Avoid LINQ, closures, temporary collections, interpolated diagnostic strings, and per-event lookup construction in listener callbacks.
• Keep exception handling at the event boundary. Route malformed payload and callback failures to the configured error callback without terminating the reader loop.
• Do not silently change delivery semantics. Channel capacity, full mode, reader/writer assumptions, event ordering, and loss behavior are observable design decisions and require explicit tests.

Preserve event correlation

• Correlate paired events using runtime identity, not arrival adjacency. In particular, background and foreground GCs can overlap, so match GCStart and GCEnd by GC index.
• Bound correlation state and avoid per-event allocation. If a fixed-size structure is used, test collisions, missing starts, stale entries, and overlapping collections before changing its capacity or indexing.