Documentation

Documentation

    ›SDK Setup

    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

    Ruby SDK Instrumentation

    This page will dive into the nitty gritty details on installing Rookout under various configurations.
    If you are encountering any difficulties with deploying Rookout, this is the place to look.

    Ruby

    The Ruby SDK provides the ability to fetch debug data from a running application in real time.
    It can easily be installed by running the following command:

    gem install rookout
    

    Setup

    Start the SDK within your application as early as possible:

    require 'rookout'
    ::Rookout.start token: '[Your Rookout Token]', labels: {env: "dev"}
    

    The SDK should be imported as early as possible within your application code. This is due to the fact you can only set non-breaking breakpoints on ruby files that have been loaded after the Rookout SDK has been started.

    For Pre-forking servers please read the relevant section..

    SDK API

    start

    start(**options)
    

    The start method is used to initialize the SDK in the background and accepts the following options:

    Argument                          Environment Variable                              Default ValueDescription
    tokenROOKOUT_TOKENNoneThe Rookout token for your organization. Should be left empty if you are using a Rookout ETL Controller
    labelsROOKOUT_LABELS{}A dictionary of key:value labels for your application instances. Use k:v,k:v format for environment variables
    git_commitROOKOUT_COMMITNoneString that indicates your git commit or a branch name
    git_originROOKOUT_REMOTE_ORIGINNoneString that indicates your git remote origin
    forkROOKOUT_ENABLE_FORKFalseSet to True to enable support in forked processes
    hostROOKOUT_CONTROLLER_HOSTNoneIf you are using a Rookout ETL Controller, this is the hostname for it
    portROOKOUT_CONTROLLER_PORTNoneIf you are using a Rookout ETL Controller, this is the port for it
    proxyROOKOUT_PROXYNoneURL to proxy server (WIP)
    debugROOKOUT_DEBUGFalseSet to True to increase log level to debug
    throw_errorsNoneFalseSet to True to throw an exception if start fails (error message will not be printed in console)

    flush

    flush()
    

    The flush method allows explicitly flushing the Rookout logs and messages.

    Test connectivity

    To make sure the SDK was properly installed in your Ruby environment, and test your configuration (environment variables only), run the following command:

    rookout
    

    Source Commit Detection

    The Ruby SDK supports detecting the existing source code commit in the following methods, in descending order of priority:

    1. If the environment variable “ROOKOUT_COMMIT” exists, use it.
    2. If the main application is running from within a Git repository, use its head.

    Supported Ruby versions

    ImplementationVersions
    MRI2.6, 2.7

    Dependencies

    The Ruby SDK dependencies contain native extensions. To ensure optimum compatibility, we highly recommend you build them in your local environment. If you are using Bundler, please configure it by running:

    bundle config force_ruby_platform true
    

    Pre-forking servers

    Several popular application servers for Ruby load the application code during startup and then fork() the process multiple times to worker processes.

    If you are using one of those servers, you can set the fork argument in the SDK api to true to automatically enable Rookout in forked processes, and no additional changes will be required.

    Serverless and PaaS deployments (WIP)

    Integrating with Serverless

    When integrating Rookout into a Serverless application, you should explicitly flush the collected information.
    For most common Serverless runtimes, Rookout provides easy to use wrappers such as:

    TBD
    

    Note: Adding the Rookout SDK will slow down your Serverless cold-start times. Please make sure your timeout is no less then 10 seconds.

    For more information, please check out our deployment-examples.

    Building

    If you are running your application on a Serverless or PaaS (Platform as a Service), you must build your package in an environment similar to those used in production. If you are running on a Windows or Mac machine (or using an incompatible Linux distribution) you may encounter some issues here.

    Many Serverless frameworks (such as AWS SAM) have built-in support for it and will work out of the box.

    If you need to set up your own build, we recommend using Docker, with a command line such as:

    docker run -v `pwd`:`pwd` -w `pwd` -i -t lambci/lambda:build-ruby2.7 pip install -r requirements.txt
    

    For more information check out this blog post: https://www.rookout.com/3_min_hack_for_building_local_native_extensions/

    ← PythonNode.js →
    • Ruby
    • Setup
    • SDK API
      • start
      • flush
    • Test connectivity
    • Source Commit Detection
    • Supported Ruby versions
    • Dependencies
    • Pre-forking servers
    • Serverless and PaaS deployments (WIP)
      • Integrating with Serverless
      • Building
    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