Pipeline.Metrics.NestedPerformance (pipeline v0.0.1)

@type depth_metric() :: %{
  depth: non_neg_integer(),
  pipeline_count: non_neg_integer(),
  total_duration_ms: non_neg_integer(),
  avg_duration_ms: float(),
  min_duration_ms: non_neg_integer(),
  max_duration_ms: non_neg_integer(),
  success_rate: float(),
  step_count: non_neg_integer()
}

performance_metrics()

@type performance_metrics() :: %{
  execution_id: String.t(),
  trace_id: String.t(),
  start_time: DateTime.t(),
  end_time: DateTime.t() | nil,
  total_duration_ms: non_neg_integer() | nil,
  pipeline_metrics: [pipeline_metric()],
  depth_metrics: %{required(non_neg_integer()) => depth_metric()},
  resource_metrics: resource_metric(),
  summary: performance_summary()
}

performance_summary()

@type performance_summary() :: %{
  total_pipelines: non_neg_integer(),
  total_steps: non_neg_integer(),
  max_depth: non_neg_integer(),
  overall_success_rate: float(),
  performance_grade: atom(),
  bottlenecks: [String.t()],
  recommendations: [String.t()]
}

pipeline_metric()

@type pipeline_metric() :: %{
  pipeline_id: String.t(),
  depth: non_neg_integer(),
  duration_ms: non_neg_integer() | nil,
  step_count: non_neg_integer(),
  success: boolean(),
  error: String.t() | nil,
  memory_usage_mb: float() | nil,
  child_pipelines: [String.t()]
}

resource_metric()

@type resource_metric() :: %{
  peak_memory_mb: float(),
  avg_memory_mb: float(),
  total_memory_allocated_mb: float(),
  gc_collections: non_neg_integer(),
  process_count_peak: non_neg_integer()
}

Functions

analyze_performance(performance_metrics)

@spec analyze_performance(performance_metrics()) :: map()

Analyze performance metrics and identify issues.

Parameters

performance_metrics: Completed performance metrics

Returns

Performance analysis with insights and recommendations

compare_performance(performance_metrics_list, options \\ %{})

@spec compare_performance([performance_metrics()], map()) :: String.t()

Compare performance between multiple executions.

Parameters

performance_metrics_list: List of performance metrics to compare
options: Comparison options

Returns

Performance comparison report

complete_performance_tracking(performance_context)

@spec complete_performance_tracking(performance_metrics()) :: performance_metrics()

Complete performance tracking and generate final metrics.

Parameters

performance_context: Current performance tracking context

Returns

Completed performance metrics with analysis

emit_performance_telemetry(performance_metrics, event_type \\ :completion)

@spec emit_performance_telemetry(performance_metrics(), atom()) :: :ok

Emit telemetry events for performance metrics.

Parameters

performance_metrics: Performance metrics to emit
event_type: Type of telemetry event

generate_performance_report(performance_metrics, options \\ %{})

@spec generate_performance_report(performance_metrics(), map()) :: String.t()

Generate a performance report.

Parameters

performance_metrics: Performance metrics to report on
options: Report generation options

Returns

Formatted performance report

record_pipeline_metric(performance_context, pipeline_id, depth, duration_ms, step_count, success, error \\ nil, metadata \\ %{})

@spec record_pipeline_metric(
  performance_metrics(),
  String.t(),
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer(),
  boolean(),
  String.t() | nil,
  map()
) :: performance_metrics()

Record metrics for a single pipeline execution.

Parameters

performance_context: Current performance tracking context
pipeline_id: Pipeline that was executed
depth: Nesting depth of the pipeline
duration_ms: Execution duration in milliseconds
step_count: Number of steps in the pipeline
success: Whether execution was successful
error: Error message if execution failed
metadata: Additional metadata

Returns

Updated performance context

start_performance_tracking(trace_id, pipeline_id)

@spec start_performance_tracking(String.t(), String.t()) :: performance_metrics()

Start performance tracking for a nested pipeline execution.

Parameters

trace_id: The trace ID for this execution
pipeline_id: The root pipeline ID

Returns

Performance tracking context