Getting started with Arm Code Advisor's plug-in API

Use the plug-in API to expand and/or replace certain features of Code Advisor's analyze phase.

Prerequisites

Before you start:

  1. Ensure Code Advisor is installed and your environment is configured as described in Installing Arm Code Advisor 
  2. Create a folder called plugins, in the .armcadvisor directory. This is where you should store your plug-ins:
     $ mkdir ~/.armcadvisor/plugins
    Ensure you have executable permissions on files you create in this folder.
  3. Set up a virtual environment for python:
    virtualenv <name>
    source <name>/bin/activate
  4. Install the setup.py plug-in:
    cd <install_location>/share/python-api/
    python setup.py install

Write a plug-in

This example uses a python script to generate information and advice issues, and send them to Code Advisor. The following steps describe each line of code in the script. This example script can be found in your install location: /<install_location>/plugin-examples/example-issues.py

  1. Start your script by importing Code Advisor's API object:
    from codeadvisor import API
  2. As this plug-in will be used to generate issues, include the following to import the appropriate datatype:
    from codeadvisor.types import Issue 
  3. Next, define a function to generate the issues. This example creates a number of issues, gives them a unique ID, assigns a type (info or advice), a category and a title. It also specifies the path to the file the issue should appear in:
    def gen_issues(amount):
            for i in xrange(0, amount):
               issue = Issue()
               issue.id = "issue {}".format(i)
               issue.type = ["info", "advice"][i % 2]
               issue.categories.append("fish")
               issue.title = "AN ISSUE CALLED {}".format(i)
               issue.position.source_path = "/dev/null"
    
               yield issue
  4. Create an instance of the API object, specifying the plug-in name, the author and the type of encoding:
    plugin = API("example-issues", "ARM", "json")
  5. This plug-in will produce issues, so include the following to publish to the 'issues' datastream:
    plugin.add_producer("armcadvisor:issues")
  6. Define the main function:
    def main():
        plugin.setup()
        for issue in gen_issues(100):
            plugin.send("armcadvisor:issues", issue)
    This sets up the plug-in, creates the configuration details (--config) and generates 100 issues, which are sent to the issues datastream.
  7. Save your plug-in file to your ~/.armcadvisor/plugins directory.
  8. To list all the available plug-ins, use:
    armcadvisor plugins list
    This returns a list showing the default Arm plug-ins and any user-defined plug-ins you have created:

    name enabled version author executable
    samples true ARM <path to plugin file>
    decode  true ARM <path to plugin file>
    insight true ARM <path to plugin file>
    prioritize true ARM <path to plugin file>
    myplugin true User1 <path to plugin file>

Run your plug-in

  1. Run Code Advisor's analyze phase, using armcadvisor analyze.
    armcadvisor analyze
    Data will start being sent to the plug-in's stdin interface and read from its stdout interface. Once a plug-in has finished producing data, and has no further data to consume, it exits with a zero exit code, and the data streams are closed.
  2. Use armcadvisor display to list the plug-in issues:
    armcadvisor display
    
    AN ISSUE CALLED 0
    
    Type: info  Category: fish
    Source file: /dev/null, line 0, column 0 to the end of the line, impact 8
    
    AN ISSUE CALLED 10
    
    Type: info  Category: fish
    Source file: /dev/null, line 0, column 0 to the end of the line, impact 8
    
    AN ISSUE CALLED 12
    
    Type: info  Category: fish
    Source file: /dev/null, line 0, column 0 to the end of the line, impact 8
    
    AN ISSUE CALLED 14
    
    Type: info  Category: fish
    Source file: /dev/null, line 0, column 0 to the end of the line, impact 8
    
    ...
    
    Issue Statistics
      fish: 100 (advice 50, info 50)
      : 1 (advice 1, info 0)
    Total number of issues found: 101 (advice 51, info 50)
      impact 8: 101
    

Debug your plug-in

  1. Use the --config flag to list information about your plug-in, including its name, and the data streams it consumes and/or produces:
    ./my_plugin --config
    {
      "produces": [
        "armcadvisor:issues"
      ], 
      "author": "User", 
      "name": "issues", 
      "apiVersion": "1", 
      "encoding": "PROTOBUF"
    }
  2. If the armcadvisor analyze phase is taking a long time to complete, use the ? character to see the status of all running plug-ins.

  3. Use armcadvisor analyze with the --log-level info option to see detailed information about how your plug-ins are running:

    armcadvisor analyze --log-level info

Resources