github.com/grafana/pyroscope@v1.18.0/docs/sources/configure-client/language-sdks/python.md (about)

     1  ---
     2  title: "Python"
     3  menuTitle: "Python"
     4  description: "Instrumenting Python applications for continuous profiling."
     5  weight: 40
     6  aliases:
     7    - /docs/phlare/latest/configure-client/language-sdks/python
     8  ---
     9  
    10  # Python
    11  
    12  The Python profiler, when integrated with Pyroscope, transforms the way you analyze and optimize Python applications.
    13  This combination provides unparalleled real-time insights into your Python codebase, allowing for precise identification of performance issues
    14  It's an essential tool for Python developers focused on enhancing code efficiency and application speed.
    15  
    16  {{< admonition type="note" >}}
    17  Refer to [Available profiling types](https://grafana.com/docs/pyroscope/<PYROSCOPE_VERSION>/configure-client/profile-types/) for a list of profile types supported by each language.
    18  {{< /admonition >}}
    19  
    20  ## Before you begin
    21  
    22  To capture and analyze profiling data, you need either a hosted Pyroscope OSS server or a hosted [Pyroscope instance with Grafana Cloud Profiles](/products/cloud/profiles-for-continuous-profiling/) (requires a free Grafana Cloud account).
    23  
    24  The Pyroscope server can be a local server for development or a remote server for production use.
    25  
    26  ### Profiling on macOS
    27  
    28  macOS has a feature called System Integrity Protection (SIP) that prevents even the root user from reading memory from any binary located in system folders.
    29  
    30  The easiest way to avoid interference from SIP, is by installing a Python distribution into your home folder. This can be achieved for example by using `pyenv`:
    31  
    32  ```bash
    33  # Setup pyenv
    34  brew update
    35  brew install pyenv
    36  echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
    37  echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
    38  echo 'eval "$(pyenv init - zsh)"' >> ~/.zshrc
    39  #  Restart your shell
    40  exec "$SHELL"
    41  # Install Python 3.12
    42  pyenv install 3.12
    43  ```
    44  
    45  ## Add Python profiling to your application
    46  
    47  Install the `pyroscope-io` pip package:
    48  
    49  ```bash
    50  pip install pyroscope-io
    51  ```
    52  
    53  ## Configure the Python client
    54  
    55  Add the following code to your application. This code will initialize the Pyroscope profiler and start profiling:
    56  
    57  ```python
    58  import pyroscope
    59  
    60  pyroscope.configure(
    61    application_name = "my.python.app", # replace this with some name for your application
    62    server_address   = "http://my-pyroscope-server:4040", # replace this with the address of your Pyroscope server
    63  )
    64  ```
    65  
    66  Optionally, you can configure several additional parameters:
    67  
    68  ```python
    69  import os
    70  import pyroscope
    71  
    72  pyroscope.configure(
    73      application_name    = "my.python.app", # replace this with some name for your application
    74      server_address      = "http://my-pyroscope-server:4040", # replace this with the address of your Pyroscope server
    75      sample_rate         = 100, # default is 100
    76      detect_subprocesses = False, # detect subprocesses started by the main process; default is False
    77      oncpu               = True, # report cpu time only; default is True
    78      gil_only            = True, # only include traces for threads that are holding on to the Global Interpreter Lock; default is True
    79      enable_logging      = True, # does enable logging facility; default is False
    80      tags                = {
    81          "region": f'{os.getenv("REGION")}',
    82      }
    83  )
    84  ```
    85  
    86  ## Add profiling labels to Python applications
    87  
    88  You can add tags to certain parts of your code:
    89  
    90  ```python
    91  # You can use a wrapper:
    92  with pyroscope.tag_wrapper({ "controller": "slow_controller_i_want_to_profile" }):
    93      slow_code()
    94  ```
    95  
    96  ## Sending data to Pyroscope OSS or Grafana Cloud Profiles with Python SDK
    97  
    98  
    99  ```python
   100  import pyroscope
   101  
   102  pyroscope.configure(
   103      application_name = "example.python.app",
   104      server_address = "<URL>",
   105      basic_auth_username = '<User>',
   106      basic_auth_password = '<Password>',
   107      # Optional Pyroscope tenant ID (only needed if using multi-tenancy). Not needed for Grafana Cloud.
   108      # tenant_id = "<TenantID>",
   109  )
   110  ```
   111  
   112  To configure the Python SDK to send data to Pyroscope, replace the `<URL>` placeholder with the appropriate server URL. This could be the Grafana Cloud URL or your own custom Pyroscope server URL.
   113  
   114  If you need to send data to Grafana Cloud, you'll have to configure HTTP Basic authentication. Replace `<User>` with your Grafana Cloud stack user and `<Password>` with your Grafana Cloud API key.
   115  
   116  If your Pyroscope server has multi-tenancy enabled, you'll need to configure a tenant ID. Replace `<TenantID>` with your Pyroscope tenant ID.
   117  
   118  ### Locate the URL, user, and password in Grafana Cloud Profiles
   119  
   120  [//]: # 'Shared content for URl location in Grafana Cloud Profiles'
   121  [//]: # 'This content is located in /pyroscope/docs/sources/shared/locate-url-pw-user-cloud-profiles.md'
   122  
   123  {{< docs/shared source="pyroscope" lookup="locate-url-pw-user-cloud-profiles.md" version="latest" >}}
   124  
   125  ## Python profiling examples
   126  
   127  Check out the following resources to learn more about Python profiling:
   128  - [Python examples](https://github.com/pyroscope-io/pyroscope/tree/main/examples/language-sdk-instrumentation/python) demonstrating how Django, Flask, and FastAPI apps can be profiled with Pyroscope.
   129  - A [Python demo](https://play.grafana.org/a/grafana-pyroscope-app/profiles-explorer?searchText=&panelType=time-series&layout=grid&hideNoData=off&explorationType=flame-graph&var-serviceName=pyroscope-rideshare-python&var-profileMetricId=process_cpu:cpu:nanoseconds:cpu:nanoseconds&var-dataSource=grafanacloud-profiles) on play.grafana.org.