AppMap Python Cheat Sheet

This is a quick reference guide for using the AppMap agent for Python.

Installation

Install the appmap package into your project's virtual environment.

pip:

pip install --require-virtualenv appmap

Poetry:

poetry add --group=dev appmap

Pipenv:

pipenv install --dev appmap

Configuration (`appmap.yml`)

Create an appmap.yml file in your project root to define what code to record.

# The name of your application
name: my_python_app

# List of packages/modules to instrument
packages:
  # Instrument the 'app.mod1' module
  - path: app.mod1
    # Shallow recording captures interactions without internal details
    shallow: true

  # Instrument the 'app.mod2' module
  - path: app.mod2
    # Exclude specific classes or functions from recording
    exclude:
    - MyClass
    - MyOtherClass.my_instance_method

  # You can also record installed packages (e.g., from pip)
  - dist: Django
    exclude:
    - django.db

Enabling Recording

AppMap is enabled by default when the package is installed. To make it explicit, or to control recording types, use the appmap-python script to run your application.

Run a Python script with AppMap:

appmap-python python my_script.py

Enable specific recording types (e.g., process):

appmap-python --record process <your application command>

Disable specific recording types (e.g., pytest):

appmap-python --no-record pytest pytest

Recording Methods

Test Recording

AppMaps are generated automatically for supported test frameworks.

pytest: AppMap is a pytest plugin. Just run pytest as usual (with appmap-python).
```
appmap-python pytest
```
unittest: AppMap records each test_* function in unittest.TestCase subclasses.

To disable recording for a specific test or class, use the @appmap.noappmap decorator.

Request Recording (Web Frameworks)

AppMap automatically records HTTP server requests in supported frameworks.

Django: Set DEBUG = True in settings.py.
Flask: Run the development server with the --debug flag.
```
appmap-python flask run --debug
```
FastAPI (with uvicorn): Run uvicorn with the --reload flag.
```
appmap-python uvicorn main:app --reload
```

If not using the standard development server, you may need to install the framework middleware manually.

Remote Recording

Remote recording is enabled automatically when running a web application in debug/development mode (see settings above).

Process Recording

Record the entire execution of a script from start to finish.

appmap-python --record process python my_script.py

or set the environment variable:

APPMAP_RECORD_PROCESS=true python my_script.py

Note: Process recording is not compatible with other recording methods.

Code Block Recording

Record a specific block of code using a context manager.

import appmap

r = appmap.Recording()
with r:
    # ... code to be recorded ...
    print("This block is being recorded.")

# Manually save the recording to a file
with open("my_recording.appmap.json", "w") as f:
    f.write(appmap.generation.dump(r, {"name": "My Manual Recording"}))

Decorators

@appmap.labels('label1', 'label2'): Adds labels to a function in the AppMap metadata, useful for analysis.
```
import appmap

@appmap.labels('provider.authentication')
def my_auth_function():
    # ...
```
@appmap.noappmap: Disables AppMap generation for a specific test function or an entire test class.
```
import appmap

@appmap.noappmap
def test_that_should_not_be_recorded():
    # ...
```

Key Environment Variables

Variable	Description	Example
`APPMAP`	Set to `true` to enable all AppMap instrumentation and recording.	`APPMAP=true python my_app.py`
`APPMAP_CONFIG`	Specifies the path to the configuration file.	`APPMAP_CONFIG=config/appmap.yml`
`APPMAP_RECORD_PYTEST`	Set to `false` to disable recording `pytest` tests.	`APPMAP_RECORD_PYTEST=false pytest`
`APPMAP_RECORD_UNITTEST`	Set to `false` to disable recording `unittest` tests.	`APPMAP_RECORD_UNITTEST=false ...`
`APPMAP_RECORD_REQUESTS`	Set to `false` to disable recording web requests.	`APPMAP_RECORD_REQUESTS=false ...`
`APPMAP_RECORD_REMOTE`	Set to `true` to force-enable remote recording (can be a security risk outside of dev).	`APPMAP_RECORD_REMOTE=true ...`
`APPMAP_RECORD_PROCESS`	Set to `true` to enable process recording.	`APPMAP_RECORD_PROCESS=true ...`
`APPMAP_LOG_LEVEL`	Sets the log level for the agent (`DEBUG`, `INFO`, `WARNING`, `ERROR`).	`APPMAP_LOG_LEVEL=DEBUG ...`

Note appmap-python script is the recommended way to enable recording, but it can also be configured manually by setting the appropriate environment variables.

Find the full documentation at AppMap Agent for Python Docs.

dividedmind/appmap-python-cheatsheet.md