TRB PRO

TRB PRO is a collection of additional tools for working with Trailblazer, such as the following.

• A web debugger that integrates with our tracing tools like #wtf.
• Our BPMN editor for designing long-running workflows that are executed by the trailblazer-workflow process engine.

It is free of charge for low-volume users. Please consider purchasing a subscription in order to support Trailblazer development.

Rails support

Using our web debugger in your project is as easy as the following five steps.

1. In your Rails’ Gemfile, add the gem.

      gem "trailblazer-pro-rails"

1. Get your API key from https://pro.trailblazer.to/settings. You have to sign up with Github if you haven’t before. We’re not asking for a credit card number, upgrading is always possible.
2. In your Rails app, run our generator and enter your API key.

      $ rails g trailblazer:pro:install

You’re now ready to trace and debug on the web.

1. Run your operation via #WTF?.

      result = API::V1::Diagram::Operation::Update.wtf?(params: params)

Click the [TRB PRO] link in your terminal and start debugging.

• Rails support
• Explicit tracing

You can use the new method Operation.WTF? to explicitly trace using the web debugger.

  result = API::V1::Diagram::Operation::Update.wtf?(params: params)

This will always send the trace to the web, regardless of any configuration.

• Rails support
• Automatic tracing

It’s possible to web-trace operation that’re invoked with the generic Operation.().

For example, you could automatically web-trace specific operation run from a controller with the following configuration in config/environments/development.rb.

  config.trailblazer.pro.trace_operations = {
    "API::V1::Diagram::Operation::Update" => true,
  }

The trace_operations directive allows you to enable web-tracing for particular operations.

If needed, you can enable it for all operations.

# TODO

• Rails support
• Planned

Please note that trailblazer-pro and trailblazer-pro-rails are still experimental, and we’re presently collecting “power user” experiences and feature requests.

Planned features are

• End-to-end encryption for traces, so we won’t be able to see anything your app is doing.
• Activity tracing.
• More configuration of the tracing process.
• Better production mode: collect the trace (which is fast), and only render it if something went wrong. Add the web-trace link to your exception handlers.
• Please contact us if you need more: https://github.com/trailblazer/trailblazer-pro-rails/issues or https://trailblazer.zulipchat.com

License

All Trailblazer core gems are licensed under the LGPLv3. Additional gems are MIT.

The commercial license can be found here.

FAQ

There is a lot of confusion around the LGPLv3 license. It is actually not as restrictive as you might’ve thought! Here are the most commonly asked questions that we answered with the help of a lawyer specialized in licensing.

• FAQ
• Why is TRB licensed under LGPL, not MIT?

Trailblazer (TRB) is an Open-Source project. Since we want to keep it that way, we decided to raise awareness for the “cost” of our work - providing new versions and features is incredibly time-consuming for us, but we love what we do. The GNU Lesser General Public License (LGPL) has no implications for 75% of our users. Nevertheless, the license change has lead to an increasing number of inquiries for a commercial license. This creates a win-win situation, you as the user have your peace of mind, and we can continue working with your funds.

• FAQ
• What are the implications of LGPL and how can I avoid those?

The LGPL allows users to use and integrate LGPL software components into their own software without being required to release the source code of their own software components. However, if users modify LGPL software components (“derivative work”), they are required to make the modified software component available under the same LGPL license.

To avoid the latter with TRB, users have to comply with para. 5 LGPLv2.1:

A program that contains no derivative of any portion of the Library, but is designed to work with the Library by being compiled or linked with it, is called a “work that uses the Library”. Such a work, in isolation, is not a derivative work of the Library, and therefore falls outside the scope of this License.

In other words: if you use the TRB libraries in your commercial applications or Open-Source projects, you’re not creating a derivative work of Trailblazer. Your software can be distributed under any terms.

• FAQ
• I use TRB in my MIT-OSS project. Does that mean I have to relicense mine to LPGL?

No, just make sure you that you don’t use a derivative of any portion of the Library (see above). Again, using Trailblazer in your projects, overriding its methods, “monkey-patching”, etc is not considered a derivate. You’re free to pick your own license.

• FAQ
• We use TRB in a commercial, closed-source application. Do we have to publish our source code now?

No, you don’t have to license your project under LGPL and you don’t have to provide your source code publicly.

However, if you use TRB modules licensed under LGPLv3 please

• provide a relinking mechanism for TRB libraries
• provide a license copy & explicitly acknowledge TRB usage
• make a TRB source code copy available for customers or link to our repositories
• note that TRB source code modifications are not proprietary

Editor

Whether you want to visualize a complex operation or model a long-running business process with dozens of steps, resume/suspend points and different branches, the editor will be your best friend.

You can import diagrams from the command line into your project using the trailblazer-developer gem, transform them into Ruby and implement the steps with your own business logic.

We use a subset of BPMN for the visual language in the editor, but added our own set of restrictions and semantics to it. It is possible to organize huge applications and their workflows in our editor backend, model and debug visually, and import them into your real Ruby applications.

Known Bugs

The current editor is first-generation and was about 2 years of work. It is sufficient to work with and allows creating complex workflows and collaborations. We use it in several commercial projects.

There are a bunch of known issues with the first-generation editor. Always save your diagram after you added or rearranged a new element. You can then reload should you encounter a bug.

• Arrows or connections are a PITA in more complex diagrams. When dragging arrows, they might suddenly snap to some random point or even add another joint. It is very hard to rearrange arrows laying behind other objects. This is one main reason we’re working hard on gen2.
• You can’t label arrows. This is annoying when a task or event has several outgoing arrows - you’re not able to assign a semantic via the editor. In the meantime, you can do this by #TODO