| 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.
