lisa.analysis.functions.FunctionsAnalysis

class lisa.analysis.functions.FunctionsAnalysis(trace, proxy=None)

Bases: TraceAnalysisBase

Support for ftrace events-based kernel functions profiling and analysis

Attributes

name	Name of the analysis class.

Properties

logger inherited

Convenience short-hand for self.get_logger().

Methods

compare_with_traces()	Compare the Trace it’s called on with the other traces passed as others. The reference is the trace it’s called on.
df_calls()	Return a pandas.DataFrame with a row for each function call, along some metrics:.
df_funcgraph()	Return augmented dataframe of the event with the following column:.
df_resolve_ksym()	Resolve the kernel function names.
profile_stats()	Create a lisa.stats.Stats out of profiling information of the trace.
cache() inherited	Decorator to enable caching of the output of dataframe getter function in the trace cache.
call_on_trace() inherited	Call a method of a subclass on a given trace.
df_method() inherited	Dataframe function decorator.
get_all_events() inherited	Returns the set of all events used by any of the methods.
get_analysis_classes() inherited
get_default_plot_path() inherited	Return the default path to use to save plots for the analysis.
get_df_methods() inherited
get_logger() inherited	Provides a logging.Logger named after cls.
get_plot_methods() inherited
log_locals() inherited	Debugging aid: log the local variables of the calling function.
plot_method() inherited	Plot function decorator.
save_plot() inherited	Save a holoviews element or matplotlib.figure.Figure as an image file.

Attributes

FunctionsAnalysis.name = 'functions'

Name of the analysis class.

Properties

property FunctionsAnalysis.logger

Inherited property, see lisa.utils.Loggable.logger

Convenience short-hand for self.get_logger().

Methods

FunctionsAnalysis.compare_with_traces(others, normalize=True, **kwargs)

Called on Trace instances as trace.ana.functions.compare_with_traces()

Compare the Trace it’s called on with the other traces passed as others. The reference is the trace it’s called on.

Returns:

a lisa.stats.Stats object just like profile_stats().

Parameters:

others (list(lisa.trace.Trace)) – List of traces to compare against.

Variable keyword arguments:

Forwarded to profile_stats().

Required trace events:

• funcgraph_entry or funcgraph_exit

• one group of: (sched_pelt_cfs or sched_load_cfs_rq or sched_load_avg_cpu) , sched_util_est_cfs , sched_cpu_capacity

FunctionsAnalysis.df_calls(tag_df=None, thread_root_functions=None, normalize=True, *, df_fmt=None)

Called on Trace instances as trace.ana.functions.df_calls()

Return a pandas.DataFrame with a row for each function call, along some metrics:

• cum_time: cumulative time spent in that function. This

  includes the time spent in all children too.

• self_time: time spent in that function only. This

  excludes the time spent in all children.

Parameters:

• tag_df (pandas.DataFrame) – Dataframe containing the tag event, which is used to tag paths in the callgraph. The __cpu column is mandatory in order to know which CPU is to be tagged at any index. Other colunms will be used as tag keys. Tags are inherited from from both parents and children. This allows a leaf function to emit an event and use it for the whole path that lead to there. Equally, if a function emits a tag, all the children of this call will inherit the tag too. This allows a top-level function to tag a whole subtree at once.

• thread_root_functions (list(str) or None) – Functions that are considered to be a root of threads. When they appear in the callgraph, the profiler will consider the current function to be preempted and will not register the call as a child of it and will avoid to count it in the cumulative time.

• normalize (bool) –

  Normalize metrics according to the current CPU capacity so that they appear to have run on the fastest CPU at maximum frequency. This allows merging calls regardless of their origin (CPU and frequency).

  Note

  Normalization only currently takes into account the capacity of the CPU when the function is entered. If it changes during execution, the result will be somewhat wrong.

Note

Calls during which the current function name changes are not accounted for. They are typically a sign of functions that did not properly return, for example functions triggering a context switch and returning to userspace.

Added by lisa.analysis.base.TraceAnalysisBase.df_method():

Parameters:

df_fmt (str or None) –

Format of dataframe to return. One of:

• "pandas": pandas.DataFrame

• "polars-lazyframe": polars.LazyFrame

Returns:

The return type is determined by the dataframe format chosen for the trace object.

Required trace events:

• funcgraph_entry or funcgraph_exit

• one group of: (sched_pelt_cfs or sched_load_cfs_rq or sched_load_avg_cpu) , sched_util_est_cfs , sched_cpu_capacity

FunctionsAnalysis.df_funcgraph(event, *, df_fmt=None)

Called on Trace instances as trace.ana.functions.df_funcgraph()

Return augmented dataframe of the event with the following column:

• func_name: Name of the calling function if it could be resolved.

Parameters:

event (str) –

One of:

• entry (funcgraph_entry event)

• exit (funcgraph_exit event)

Added by lisa.analysis.base.TraceAnalysisBase.df_method():

Parameters:

df_fmt (str or None) –

Format of dataframe to return. One of:

• "pandas": pandas.DataFrame

• "polars-lazyframe": polars.LazyFrame

Returns:

The return type is determined by the dataframe format chosen for the trace object.

Added by lisa.analysis.base.TraceAnalysisBase.df_method():

Parameters:

df_fmt (str or None) –

Format of dataframe to return. One of:

• "pandas": pandas.DataFrame

• "polars-lazyframe": polars.LazyFrame

Returns:

The return type is determined by the dataframe format chosen for the trace object.

Required trace events:

• funcgraph_entry or funcgraph_exit

FunctionsAnalysis.df_resolve_ksym(df, addr_col, name_col='func_name', addr_map=None, exact=True, *, df_fmt=None)

Called on Trace instances as trace.ana.functions.df_resolve_ksym()

Resolve the kernel function names.

Note

If the addr_col is not of a numeric dtype, it will be assumed to be function names already and the content will be copied to name_col.

Parameters:

• df (pandas.DataFrame) – Dataframe to augment

• addr_col (str) – Name of the column containing a kernel address.

• name_col – Name of the column to create with symbol names

• name_col – str

• addr_map (dict(int, str)) – If provided, the mapping of kernel addresses to symbol names. If missing, the symbols addresses from the lisa.platforms.platinfo.PlatformInfo attached to the trace will be used.

• exact (bool) – If True, an exact symbol address is expected. If False, symbol addresses are sorted and paired to form intervals, which are then used to infer the name. This is suited to resolve an instruction pointer that could point anywhere inside of a function (but before the starting address of the next function).

Added by lisa.analysis.base.TraceAnalysisBase.df_method():

Parameters:

df_fmt (str or None) –

Format of dataframe to return. One of:

• "pandas": pandas.DataFrame

• "polars-lazyframe": polars.LazyFrame

Returns:

The return type is determined by the dataframe format chosen for the trace object.

FunctionsAnalysis.profile_stats(tag_df=None, normalize=True, ref_function=None, ref_tags=None, **kwargs)

Called on Trace instances as trace.ana.functions.profile_stats()

Create a lisa.stats.Stats out of profiling information of the trace.

Parameters:

• tag_df (pandas.DataFrame or None) – Dataframe of tags, forwarded to df_calls()

• normalize (bool) – Normalize execution time according to CPU capacity, forwarded to to df_calls()

• metric (str) –

  Name of the metric to use for statistics. Can be one of:

  • self_time: Time spent in the function, not accounting for time spent in children

  • cum_time: Total time spent in the function, including the time spent in children.

  Defaults to self_time.

• functions (list(str) or None) – Restrict the statistics to the given list of function.

• ref_function (str or None) – Function to compare to.

• ref_tags (dict(str, set(object)) or None) – Function tags to compare to. Ignored if ref_function is None.

• cpus (list(int) or None) – List of CPUs where the functions were called to take into account. If left to None, all CPUs are considered.

• per_cpu (bool or None) – If True, the per-function statistics are separated for each CPU they ran on. This is useful if the frequency was fixed and the only variation in speed was coming from the CPU it ran on.

• tags (dict(str, object)) – Restrict the statistics to the function tagged with the given tag values. If a function has multiple values for a given tag and one of the value is in tags, the function is selected.

Variable keyword arguments:

Forwarded to lisa.stats.Stats.

Note

Recursive calls are treated as if they were inlined in their callers. This means that the count of calls will be counting the toplevel calls only, and that the self_time for a recursive function is directly linked to how much time each level consumes multiplied by the number of levels. cum_time will also be tracked on the top-level call only to provide a more accurate result.

Required trace events:

• funcgraph_entry or funcgraph_exit

• one group of: (sched_pelt_cfs or sched_load_cfs_rq or sched_load_avg_cpu) , sched_util_est_cfs , sched_cpu_capacity

classmethod FunctionsAnalysis.cache(f, fmt='parquet', ignored_params=None)

Inherited method, see lisa.analysis.base.TraceAnalysisBase.cache()

Decorator to enable caching of the output of dataframe getter function in the trace cache.

classmethod FunctionsAnalysis.call_on_trace(meth, trace, meth_kwargs)

Inherited method, see lisa.analysis.base.TraceAnalysisBase.call_on_trace()

Call a method of a subclass on a given trace.

classmethod FunctionsAnalysis.df_method(f, index=None)

Inherited method, see lisa.analysis.base.TraceAnalysisBase.df_method()

Dataframe function decorator.

classmethod FunctionsAnalysis.get_all_events()

Inherited method, see lisa.analysis.base.TraceAnalysisBase.get_all_events()

Returns the set of all events used by any of the methods.

classmethod FunctionsAnalysis.get_analysis_classes()

Inherited method, see lisa.analysis.base.TraceAnalysisBase.get_analysis_classes()

FunctionsAnalysis.get_default_plot_path(**kwargs)

Inherited method, see lisa.analysis.base.TraceAnalysisBase.get_default_plot_path()

Return the default path to use to save plots for the analysis.

classmethod FunctionsAnalysis.get_df_methods(*args, **kwargs)

Inherited method, see lisa.analysis.base.TraceAnalysisBase.get_df_methods()

classmethod FunctionsAnalysis.get_logger(suffix=None)

Inherited method, see lisa.utils.Loggable.get_logger()

Provides a logging.Logger named after cls.

classmethod FunctionsAnalysis.get_plot_methods(*args, **kwargs)

Inherited method, see lisa.analysis.base.AnalysisHelpers.get_plot_methods()

classmethod FunctionsAnalysis.log_locals(var_names=None, level='debug')

Inherited method, see lisa.utils.Loggable.log_locals()

Debugging aid: log the local variables of the calling function.

classmethod FunctionsAnalysis.plot_method(f)

Inherited method, see lisa.analysis.base.AnalysisHelpers.plot_method()

Plot function decorator.

FunctionsAnalysis.save_plot(figure, filepath=None, img_format=None, backend=None)

Inherited method, see lisa.analysis.base.AnalysisHelpers.save_plot()

Save a holoviews element or matplotlib.figure.Figure as an image file.