Documentation

Documentation

    ›Debug Session

    General

    • Getting Started
    • Use Cases

    SDK Setup

    • Introduction
    • JVM
    • .NET
    • Python
    • Ruby
    • Node.js
    • Deployment Examples

    Debug Session

    • Debug session setup
    • Source Repositories
    • Labels

    Breakpoints

    • Breakpoints
    • Breakpoint Status
    • Conditional breakpoints
    • Breakpoint Tasks

    Organizations

    • Organizations

    Advanced

    • Integrations
    • Collaborations
    • Controller Setup
    • Scripting Reference
    • OpenTracing
    • Keyboard Shortcuts

    More

    • Software Versions
    • Controller License
    Edit

    Source Repositories

    Introduction

    Each Debug Session contains the source code you wish to debug. Rookout allows you to easily load sources from your local file system or your git provider. When you integrate your source code into Rookout, it remains between your code repository and your local browser. Rookout never sees nor has access to your source code. In fact, your code never even reaches the Rookout servers.

    Source Code Fetching

    Git Providers

    Rookout integrates directly to the cloud editions of the following Git Providers:

    1. Github
    2. BitBucket
    3. GitLab

    In addition, Rookout offers a desktop app for fetching source repositories from a local file system. This allows fetching source code from local editions of Git providers, as well as from Perforce.

    Automatic Fetching

    Rookout has the ability to connect to a repository in order to automatically fetch your source code anytime a specific application instance is selected for debugging. To automatically fetch source code repositories from cloud based Github, Bitbucket or Gitlab, use the following environment variables while deploying rookout:

    1. ROOKOUT_COMMIT - String that indicates your git commit
    2. ROOKOUT_REMOTE_ORIGIN - String that indicates your git remote origin

    After adding those environment variables, the sources will be loaded automatically once the instance will be filtered. As an example, the environment variables could be set as follows:

    export ROOKOUT_REMOTE_ORIGIN=https://github.com/Rookout/tutorial-python
    export ROOKOUT_COMMIT=3793853884cae77cc082961aa64cdb0ab93a0e35

    Note, we are setting the commit to a specific revision or branch name which should match the revision of your code deployed in the environment you are debugging. Oftentimes organizations opt to integrate setting of these parameters into their CI/CD process so that they can be dynamically configured upon each new deployment. After these environment variables are set, when viewing the Application Instances screen, you should see the Source origin and Revision fields set with the values you set in your environment variables:

    Now, when you select a Rookout Label to debug an application instance where these environments variables are set, Rookout will attempt to auto clone your repository on your local machine with the correct code revision so that you are immediately ready to start debugging. You should see the text auto loaded in parenthesis next to your repository when this happens successfully.

    When auto source loading happens the git files will be cloned on your local machine in the following locations:

    Windows: %APPDATA%/Rookout/git_root
    Mac: $HOME/Library/Application Support/Rookout/git_root
    Linux: $HOME/.Rookout/git_root

    For teams that have self-hosted / on-prem repositories, it is required that the Rookout Desktop Application be installed first. You must also have git or perforce command line tools installed on your machine. To install the Rookout Desktop App, click on the + button in the debugger view, choose Local Filesystem, and then follow the steps to download and install the Rookout Desktop App.

    Fo the on-prem git workflow, you can fine more details in this video:

    Manual Fetching

    You can load your sources manually in the web IDE as explained in the following video. When fetching source repositories manually, make sure to fetch the version of the code that is deployed in the app you are trying to debug.

    Local FileSystem - Rookout Desktop App

    If you are using any local git provider, or any hosted git provider besides Github, Gitlab or Bitbucket, you can associate source code files from the local filesystem into a Rookout debug session.

    To do that, please download and install Rookout Desktop App. See the following video to learn how to download Rookout Desktop App:

    Packaging Sources

    Java

    To make sure you are collecting data from the source line where you have set the breakpoint, please include your source files within your JAR/WAR/EAR library.

    For more information, please click here.

    JavaScript/TypeScript

    If you are transpiling your JavaScript/TypeScript on the fly (using babel-node or a similar tool), Rookout will work out of the box.

    If you are transpiling your JavaScript/TypeScript before execution (for instance in your CI/CD), you must include the source maps inline within the source files or as separate files (usually app.map.js) in your deployment.

    For more information, please click here.

    .Net

    To make sure you are collecting data from the source line where you have set the breakpoint, include your source files within your library.

    For more information, please click here.

    Repository Settings

    If you are deploying your software in some non-trival ways, Rookout offers the option of customizing the way breakpoints are set directly from your source repository.

    Simply create a file named .rookout at the root of your repository and add to it any of the configurations below.
    Feel free to add comments to the file in the form of lines starting with '#'.

    Source Path Mapping

    By default Rookout uses the repository relative path of the source file you are debugging to find it.

    You may have to change it in a couple of cases:

    • You are using serverless framework that deploys your app with different layout.
    • You are removing a part of the path when deploying your code.
    • The path is too short or generic, and you want to make it more specific to avoid path collisions.

    This is done through simple path substition instructions (in the .rookout file):

    Shortening a Path

    To convert microservice1/app.py to app.py use:

    /microservice1 /
    

    Replacing a Path

    To convert microservice1/app.py to app/app.py use:

    /microservice1 /app
    

    Lengthening a Path

    To convert app.py to microservice1/app.py use:

    / /microservice1
    

    Manipulating a Path with Spaces

    To convert my app/app.py to app.py use:

    "my app" /
    

    (Node) Debugging Packages

    By default, under NodeJS, Rookout ignores your project's dependencies the node_modules folder.

    If the project you are debugging is installed as a package on the server add the following snippet to your .rookout file:

    #package
    

    Note: Rookout does not map the most common NPM packages for performance reasons and does not allow setting breakpoints inside them.

    ← Debug session setupLabels →
    • Introduction
    • Source Code Fetching
      • Git Providers
      • Local FileSystem - Rookout Desktop App
    • Packaging Sources
      • Java
      • JavaScript/TypeScript
      • .Net
    • Repository Settings
      • Source Path Mapping
      • (Node) Debugging Packages
    Documentation
    General

    WelcomeUse Cases
    SDK Setup

    Setup IntroJvm SetupDotnet SetupPython SetupRuby SetupNode SetupDeployment Examples
    Debug Session

    Debug Session SetupSource ReposProjects Labels
    Breakpoints

    BreakpointsBreakpoints StatusBreakpoints ConditionalBreakpoints Tasks
    Organizations

    Organizations
    Advanced

    IntegrationsCollaborationsController SetupBreakpoints ReferenceOpen TracingKeyboard Shortcuts
    More

    Sdk DigestsLicense
    Other

    Status
    GitHub - RookoutFacebook - RookoutTwitter - RookoutLinkedIn - Rookout