API Reference

API List

msMemScope provides open APIs to help users analyze memory and identify memory problems.

The analyzer is the new offline analysis module of msMemScope and is responsible for all offline analysis functions. You can import analyzer from msMemScope to implement memory leak analysis and custom inefficient memory identification.

msMemScope provides two methods for offline analysis: quick analysis APIs (recommended) and analyzer-based offline analysis.

• Quick analysis APIs

  The table below describes msMemScope's quick analysis APIs.

  Table 1 API list

  API	Description
  list_analyzers	Outputs all memory analysis types supported by msMemScope.
  get_analyzer_config	Views the parameters required for running a specific memory analysis type.
  analyze	Conducts a quick analysis. It supports memory leak analysis and custom inefficient memory identification.
  check_leaks	Supports memory leak analysis.
  check_inefficient	Identifies inefficient memory in a customized way.
  enable_npu_sanitizer	NPU Sanitizer enablement API provided by msMemScope, activating mstx instrumentation for custom operators with the native Sanitizer.

• analyzer

  You can import analyzer from msMemScope for offline analysis. Table 2 analyzer API description describes the involved APIs. However, this mode is not recommended due to complex code implementation.

  The example code is as follows:

  # Import analyzer and the corresponding config for memory leak detection.
  from msmemscope.analyzer import LeaksAnalyzer, LeaksConfig
  # Declare parameters and generate config.
  leaks_config = LeaksConfig(
      input_path="user/memscope.csv", # Use the actual path for input_path.
      mstx_info="test",
      start_index=0
  )
  # Generate an analyzer instance for analysis.
  leaks_analyzer=LeaksAnalyzer()
  leaks_analyzer.analyze(leaks_config)
  
  # Import analyzer of inefficient memory analysis and the corresponding config.
  from msmemscope.analyzer import InefficientConfig, InefficientAnalyzer
  # Declare parameters and generate config.
  ineff_config = InefficientConfig(
      input_path="user/ineff.csv", # Use the actual path for input_path.
      mem_size=0,
      inefficient_type=["early_allocation","late_deallocation","temporary_idleness"],
      idle_threshold=3000
  )
  # Generate an analyzer instance for analysis.
  ineff_analyzer=InefficientAnalyzer()
  ineff_analyzer.analyze(ineff_config)

  Table 2 analyzer API description

  API	Description
  LeaksAnalyzer	Memory leak analyzer
  LeaksConfig	Memory leak analysis parameters
  InefficientConfig	Inefficiency memory analysis parameters
  InefficientAnalyzer	Inefficiency memory analyzer

list_analyzers

Function

This API outputs all memory analysis types supported by msMemScope and supports printing. Currently, only memory leak analysis and inefficient memory identification are supported.

Prototype

list_analyzers() -> List[str]

Parameter Description

None

Returns

List[str]: List of strings

After the API is executed, the memory analysis types supported by msMemScope are displayed.

Example

import msmemscope
config_list = msmemscope.list_analyzers()
print(config_list)

get_analyzer_config

Function

This API views the parameters required for running a specific memory analysis type.

Prototype

get_analyzer_config(analyzer_type: str) -> Dict[str, Any]

Parameter Description

Returns

Dict[str, Any]: Dictionary of all parameters, which can be directly printed.

After the API is executed, the input parameters required for a specific memory analysis type are directly output.

Example

import msmemscope
leaks_para = msmemscope.get_analyzer_config("leaks")
print(leaks_para)
ineff_para = msmemscope.get_analyzer_config("inefficient")
print(ineff_para)

analyze

Function

This is an external analysis API provided by msMemScope. It supports memory leak analysis and custom inefficient memory identification.

• Memory leak analysis

  This API provides offline analysis on memory leaks in a specified range, supports offline analysis for the dumped .csv files generated by msMemScope, and triggers an alarm when memory leaks in the specified range are detected. Currently, this function applies only to HAL memory leak analysis.

  Before using this API, you need to mark the specified range using mstx and start the user process using msMemScope to obtain the dumped .csv file. Then, you can use the API to input the .csv file to be analyzed, instrumentation information, and start index for offline leak analysis.

• Custom inefficient memory identification

  Parameters can be customized to identify inefficient memory offline in the dumped .csv or .db file generated by msMemScope. You can flexibly set the memory block threshold, inefficient memory type, and temporary idle API interval based on the custom parameter specifications, thus accurately identifying inefficient memory in the dumped .csv or .db file.

  If the input .csv or .db file already has inefficient memory identification results, using the custom identification function will not remove them. The new identification results will be added instead. If you need to perform the custom inefficient memory identification function for multiple times, you are advised to back up the original file.

Prototype

analyze(analyzer_type: str, **kwargs):

Parameter Description

• Memory leak analysis

  leaks: see check_leaks for details.

• Custom inefficient memory identification

  inefficient: see check_inefficient for details.

Returns

None

After the API is executed, the analysis result is displayed.

Example

import msmemscope
msmemscope.analyze("leaks", input_path="user/memscope.csv", mstx_info="test",start_index=0)

msmemscope.analyze("inefficient",
  input_path="user/ineff.csv",mem_size=0,
  inefficient_type=["early_allocation","late_deallocation","temporary_idleness"],
  idle_threshold=3000
  )
# Use the actual path for input_path.

check_leaks

Function

This is a quick memory leak analysis API provided by msMemScope.

Prototype

check_leaks(input_path: str, mstx_info: str, start_index: int)

Parameter Description

All input parameters must be obtained based on list_analyzers and get_analyzer_config.

Returns

None.

After the API is executed, the memory leak analysis result is displayed.

Example

import msmemscope
msmemscope.check_leaks(input_path="user/memscope.csv",mstx_info="test",start_index=0)
# Use the actual path for input_path.

check_inefficient

Function

This is a quick analysis API provided by msMemScope for custom inefficient memory identification.

Prototype

check_inefficient(input_path: str, mem_size: int = 0, inefficient_type: List[str] = None, idle_threshold: int = 3000) # If no input is provided, the default value is used.

Parameter Description

All input parameters must be obtained based on list_analyzers and get_analyzer_config.

Returns

None.

After the API is executed, the analysis process is printed and displayed. The identification result is written to the original file.

Example

import msmemscope
msmemscope.check_inefficient(input_path="user/ineff.csv",mem_size=0,
     inefficient_type=["early_allocation","late_deallocation","temporary_idleness"],idle_threshold=3000
     )
# Use the actual path for input_path.

enable_npu_sanitizer

Function

This is the NPU Sanitizer enablement API provided by msMemScope, Internally, this API calls torch_npu.npu._sanitizer.enable_npu_sanitizer() to enable the native Sanitizer, while simultaneously notifying the C++ layer to activate the capture of mstx instrumentation messages with the sanitizer-op: prefix. After enablement, information reported by developers via the mstx API at custom operator call sites in the required format will be intercepted and converted into kernel launch events, which are then fed into the native Sanitizer analysis pipeline for synchronous error detection.

For more details, see NPU Sanitizer.

Prototype

enable_npu_sanitizer() -> None

Parameter Description

None

Returns

None

Example

import msmemscope

# Enable NPU Sanitizer via msMemScope
msmemscope.enable_npu_sanitizer()

# After enablement, report operator information at custom operator call sites via mstx.mark() according to the specification
# Pass torch_npu.npu.current_stream().npu_stream as the second parameter  to specify the stream for instrumentation
import mstx
import torch_npu
mstx.mark(
    "sanitizer-op: name=my_ext.my_op;"
    "read=input:0x7f00:1024;"
    "write=output:0x7f08:2048",
    torch_npu.npu.current_stream().npu_stream
)