8. Using the Tideways CLI to Get Callgraphs

Introduction

The Tideways command-line interface simplifies tracing PHP console scripts and HTTP API requests. You can prefix any PHP, curl, httpie, or wget command that you want to trace with tideways run <app> and it will set local environment variables for a PHP script or arguments to send HTTP headers with curl/wget. The tool is currently available on both Linux and macOS.

Install the Command-line Tool

See the Downloads page for more information on how to install it.

The tool is currently supported on both Linux and macOS.

Command-line Tool Quick Overview

Now that the command-line tool is installed and configured let’s have a quick look at the available options. To do that, run tideways --help, or tideways -h. That will output the following to the console.

Usage:
  tideways [command]

Available Commands:
  benchmark    Run a benchmark against a list of URLs
  event        Manage events of an application
  help         Help about any command
  import       Import your profiling settings
  list         Print a list of all available applications
  run          Trigger profiling for a given command
  trace        Manage trace triggering rules of an application
  version      Print the version of Tideways CLI

We’re only going to be using run and import commands in the remainder of this chapter, but I thought it might be helpful to get a bit more of an idea of the functionality that the command-line tool offers. You can find more information about the available commands in the command-line interface documentation.

Setup

Now that the command-line tool is installed, it’s time to configure it by importing the settings for your account. When logged in to your Tideways account, under User Settings _ Commandline (or app.tideways.io/user/cli-import-settings) you’ll see a list of user tokens available for your account.

If you don’t see any, click Create UserToken, and in the form that appears, enter a name for the token, and click Create User Token. As an example, I’m going to name the token "Testing Token". After the form submits, you can then copy and paste the command to run to import the token’s settings.

Alternatively, if you already had a token available, as I have, to retrieve the token, click Show on the far right-hand side of the page for the token, and the token (along with the entire command) will be displayed. After you’ve copied the token, we need to use the tideways import command to import the token.

tideways import <copy your generated token here>

Regardless of your approach, you should see output similar to the example below, once the import is complete.

[OK] Imported Settings for Tideways CLI.
You can now start profiling with 'tideways run <args>'

Using the Command-Line Tool

As I mentioned earlier, the Tideways command-line interface simplifies tracing PHP console scripts and HTTP API requests. So let’s see how to do so, starting off by profiling a command-line script.

With Command Line Scripts

To generate a trace for use with a command-line PHP script, run the PHP script but prefix it with tideways run <organisation_name>/<app_name>.

tideways run {organization-name}/{app-name} php app/console slow:command

With Rest APIs

Next, let’s see how to profile a request to a Rest API. As with profiling PHP scripts, prefix the request to the Rest API with tideways run <organisation_name>/<app_name>. Here’s an example of how to do so, where we are profiling a request to a Rest API called with Curl.

tideways run {organization-name}/{app-name} curl http://{app-name}/api/call

With AJAX Requests

Ajax requests cannot easily be directly traced, because they usually require both an active/authenticated session and are called asynchronously in your application. This makes it hard to generate a trace with curl, but it is possible to generate traces for Ajax requests using the Tideways CLI.

How to Retrieve a Curl Request

To save yourself some time, first make a request using your browser, then copy the request as a Curl request. To do so, first use the developer tools in your browser of choice to copy the HTML request for the current page as a Curl request.

Firefox: In Firefox, open the Developer tools by clicking F12. Then, open the Network tab and filter by HTML. Finally, right-click the HTML request and click Copy Copy as cURL.
Google Chrome (and Chromium): In Google Chrome and Chromium, open the Developer tools by clicking F12. Then, open the Network tab and filter by Doc. Finally, right-click the request and click Copy Copy as cURL.

Summary

And that is how to install and configure the command-line tool, as well as how to use it to generate callgraphs with PHP scripts, requests to Rest APIs, and AJAX requests. There is more functionality available than I have covered so far, but we’ve covered the essentials that you need to know. If you would like more information about the command-line tool, check out the documentation.

Still need help? Email [email protected]