nlsq.streaming.adaptive_hybrid.DefenseLayerTelemetry

class nlsq.streaming.adaptive_hybrid.DefenseLayerTelemetry

Bases: object

Telemetry for monitoring 4-layer defense strategy activations.

Tracks when each defense layer is triggered during warmup to help with production monitoring and tuning. This class maintains thread-safe statistics that can be queried or exported for monitoring dashboards.

The 4 layers tracked are:

• Layer 1: Warm start detection (skips warmup)

• Layer 2: Adaptive step size selection (refinement/careful/exploration)

• Layer 3: Cost-increase guard (aborts warmup if loss increases)

• Layer 4: Step clipping (limits update magnitude)

layer1_warm_start_triggers

Count of warm start detection activations (warmup skipped)

Type:

int

layer2_lr_mode_counts

Counts per LR mode: {“refinement”: n, “careful”: m, “exploration”: k}

Type:

dict[str, int]

layer3_cost_guard_triggers

Count of cost-increase guard aborts

Type:

int

layer4_clip_triggers

Count of step clipping activations

Type:

int

total_warmup_calls

Total number of warmup phase executions

Type:

int

__init__()

Initialize telemetry with zeroed counters.

reset()

Reset all telemetry counters to zero.

record_warmup_start()

Record start of a warmup phase.

record_layer1_trigger(relative_loss, threshold)

Record Layer 1 warm start detection trigger.

Parameters:

• relative_loss (float) – Relative loss that triggered warm start

• threshold (float) – Threshold value that was exceeded

record_layer2_lr_mode(mode, relative_loss)

Record Layer 2 adaptive LR mode selection.

Parameters:

• mode (str) – Selected LR mode: “refinement”, “careful”, “exploration”, or “fixed”

• relative_loss (float) – Relative loss that determined the mode

record_layer3_trigger(cost_ratio, tolerance, iteration)

Record Layer 3 cost-increase guard trigger.

Parameters:

• cost_ratio (float) – Cost increase ratio that triggered the guard

• tolerance (float) – Tolerance threshold that was exceeded

• iteration (int) – Iteration number when triggered

record_layer4_clip(original_norm, max_norm)

Record Layer 4 step clipping activation.

Parameters:

• original_norm (float) – Original update norm before clipping

• max_norm (float) – Maximum allowed norm (clipping threshold)

record_lbfgs_history_fill(iteration)

Record L-BFGS history buffer fill event.

Called when the L-BFGS history buffer becomes fully populated, signaling transition from cold start to full L-BFGS mode.

Parameters:

iteration (int) – Iteration number when history buffer filled

record_lbfgs_line_search_failure(iteration, reason='')

Record L-BFGS line search failure event.

Called when the L-BFGS line search fails to find an acceptable step.

Parameters:

• iteration (int) – Iteration number when line search failed

• reason (str, optional) – Reason for line search failure

get_trigger_rates()

Get trigger rates as percentage of total warmup calls.

Returns:

Trigger rates for each layer as percentages (0-100)

Return type:

dict[str, float]

get_summary()

Get summary statistics for all defense layers.

Returns:

Summary with counts and rates for each layer

Return type:

dict

get_recent_events(n=10)

Get most recent N events.

Parameters:

n (int) – Number of recent events to return

Returns:

Most recent events

Return type:

list[dict]

export_metrics()

Export metrics in a format suitable for monitoring systems.

Returns:

Metrics with consistent naming for Prometheus/Grafana/etc.

Return type:

dict