Installation on PHP

Install Tideways Extension and Daemon

In the first step you install the Tideways PHP Profiler extension and daemon to start collecting data.

Debian/Ubuntu

Execute the following commands in your shell. They will verify and register our Apt repository and then install Tideways daemon and PHP extension from it:

echo 'deb http://s3-eu-west-1.amazonaws.com/qafoo-profiler/packages debian main' > /etc/apt/sources.list.d/tideways.list
wget -qO - https://s3-eu-west-1.amazonaws.com/qafoo-profiler/packages/EEB5E8F4.gpg | sudo apt-key add -
sudo apt-get update
sudo apt-get install tideways-php tideways-daemon

Please follow additional installation instructions printed to the screen in case you are not using the default PHP installation of Debian/Ubuntu.

RedHat/Fedora/CentOS

Execute the following commands in your shell. They will verify and register our Yum repository and then install Tideways daemon and PHP extension from it:

echo "[tideways]
name = Tideways
baseurl = https://s3-eu-west-1.amazonaws.com/qafoo-profiler/rpm" > /etc/yum.repos.d/tideways.repo
rpm --import https://s3-eu-west-1.amazonaws.com/qafoo-profiler/packages/EEB5E8F4.gpg
yum makecache --disablerepo=* --enablerepo=tideways
yum install tideways-php tideways-cli tideways-daemon

Please follow additional installation instructions printed to the screen in case you are not using the default PHP installation of CentOS/RedHat.

Other Linux Distributions

You can download precompiled binary files from our download page. These are pre-compiled for i386 and AMD64 Linux architectures, non-ZTS only.

wget -Otideways-php.tar.gz "https://s3-eu-west-1.amazonaws.com/tideways/extension/4.1.6/tideways-php-4.1.6-x86_64.tar.gz"
tar xzvf tideways-php.tar.gz
cd tideways-php
bash install.sh

They contain the PHP extension for PHP version 5.3, 5.4, 5.5, 5.6 and 7.0 and the Tideways.php. After unpacking the archive execute the install.sh script.

Download the archive for the Tideways daemon and run the installer:

wget -Otideways-daemon.tar.gz "https://s3-eu-west-1.amazonaws.com/tideways/daemon/1.5.32/tideways-daemon_linux_amd64-1.5.32.tar.gz"
tar xzvf tideways-daemon.tar.gz
cd tideways-daemon
bash install.sh

MacOS Homebrew

We provide a homebrew tap and formula to install the Profiler on your MacOS development machine.

brew tap tideways/homebrew-profiler

If you are using homebrew-php you can then install the Profiler extension matching your PHP version with one of the following commands:

brew install php53-tideways
brew install php54-tideways
brew install php55-tideways
brew install php56-tideways
brew install php70-tideways

If you don't have homebrew-php installed you can install using the MacOS provided system PHP:

brew install php54-tideways --without-homebrew-php

Install the Tideways Daemon:

brew install tideways-daemon

Windows

INFO: Tideways on Windows is currently in BETA.

To install Tideways on Windows download the following ZIP-Archive which contains the pre-compiled DLLs for different PHP versions (5.5 and 5.6) and in both thread-safe and non-thread-safe mode.

Inside you will find a tideways-daemon.exe that you must run as a background-job with the following arguments:

./tideways-daemon.exe --address="127.0.0.1:8136"

Copy the php_tideways-*.dll that matches your PHP version and thread-safety requirements into your extension folder, rename it to php_tideways.dll.

Copy Tideways.php file to your extension folder next to the php_tideways.dll from the previous step.

Modify the php.ini to include the extension:

extension=php_tideways.dll
tideways.connection=tcp://127.0.0.1:8136

AWS Elastic Beanstalk

It is quite simple to install Tideways on AWS Elastic Beanstalk by adding two small Elastic Beanstalk configuration files to your web applications source code. If you don't have a folder called .ebextensions yet create it and add two files. Don't forget to modify the second to contain your Tideways API Key:

First .ebextensions/10_tideways_repo.config:

files:
  "/etc/yum.repos.d/tideways.repo":
    mode: "000644"
    content: |
      [tideways]
      name = Tideways
      baseurl = https://s3-eu-west-1.amazonaws.com/qafoo-profiler/rpm

commands:
  01_tideways_repo_gpg:
    command: "rpm --import https://s3-eu-west-1.amazonaws.com/qafoo-profiler/packages/EEB5E8F4.gpg"
  02_tideways_repo_makecache:
    command: "yum makecache --disablerepo=* --enablerepo=tideways"

Then .ebextensions/20_tideways_install.config:

packages:
    yum:
       tideways-php: []
       tideways-daemon: []

files:
  "/etc/php.d/40tideways.ini" :
    mode: "000755"
    owner: root
    group: root
    content: |
      extension=tideways.so
      tideways.api_key=< API KEY HERE >

Now create a new source package or use the EB-CLI to deploy the new version via Git and your application should start using Tideways after the next deployment.

Info: Two files are necessary, because Elastic Beanstalk processes the packages keyword before files and commands, so that it would try to install the packages before adding the repository.

Docker Compose

If you are using Docker Compose to setup your project, then integration of Tideways can be done with a dedicated container running the Tideways Daemon and all PHP containers send data to this single container.

This instruction help is based on the work of Samuel Roze, which you can see here on Github.

First, create a sub-folder for the tideways daemon including a Dockerfile with the following contents:

FROM phusion/baseimage:0.9.18

RUN echo 'deb http://s3-eu-west-1.amazonaws.com/qafoo-profiler/packages debian main' > /etc/apt/sources.list.d/tideways.list && \
    curl -sS 'https://s3-eu-west-1.amazonaws.com/qafoo-profiler/packages/EEB5E8F4.gpg' | sudo apt-key add - && \
    apt-get update && \
    DEBIAN_FRONTEND=noninteractive apt-get -yq install tideways-daemon && \
    apt-get autoremove --assume-yes && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*

ADD run.sh /run.sh

CMD ["/run.sh"]

Put the referended run.sh in the same folder next to the Dockerfile and add the following contents:

#!/bin/bash

tideways-daemon --hostname=tideways-daemon --address=0.0.0.0:9135 --udp=0.0.0.0:8135 >> /dev/stdout 2>/dev/stderr

/sbin/my_init

If you called the folder for the tideways daemon Dockerfile tideways, then you can reference the container in the Docker compose file with:

tideways:
    build: ./tideways

Every Docker container running PHP then only requires the Tideways PHP extension to be installed and a small change to php.ini configuration to point to the Daemons container:

tideways.udp_connection="tideways:8135"
tideways.connection="tcp://tideways:9135"

You can find notes about the installation of Tideways PHP on different Linux distributions in the sections above.

If you want to use Tideways inside a Docker container, then you are propably building a container already that adds all the extensions you need and modifies the php.ini according to your needs. This container Dockerfile needs additional setup instructions to get Tideways running.

This example is based on the php:5.6-fpm image on Docker Hub, but propably works similar with other PHP base images:

FROM php:5.6-fpm

RUN echo 'deb http://s3-eu-west-1.amazonaws.com/qafoo-profiler/packages debian main' > /etc/apt/sources.list.d/tideways.list && \
    curl -sS 'https://s3-eu-west-1.amazonaws.com/qafoo-profiler/packages/EEB5E8F4.gpg' | apt-key add - && \
    apt-get update && \
    DEBIAN_FRONTEND=noninteractive apt-get -yq install tideways-php && \
    apt-get autoremove --assume-yes && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*

COPY tideways.ini /usr/local/etc/php/conf.d/40-tideways.ini

The tideways.ini file then contains:

extension=tideways.so
tideways.api_key=<your key>
tideways.udp_connection=tcp://tideways:8135
tideways.connection=tcp://tideways:9135

You can alternatively pass the API Key via environment variable and remove tideways.api_key line.

Don't forget to link your PHP containers to the tideways container in docker-compose.yml:

php:
    build: ./php
    volumes:
        - ./app:/app
    links:
        - tideways

Heroku

Tideways can be installed on Heroku by using the PHP buildpack extension functionality that hooks into Composer.

In the first step you set an environment variable used by the PHP buildpack to discover the Tideways Composer packages:

heroku config:set HEROKU_PHP_PLATFORM_REPOSITORIES="https://s3-eu-west-1.amazonaws.com/tideways/heroku/"

If you already have another external platform repository configured then separate both urls by space.

Then modify the composer.json of your Heroku PHP project to add a dependency to ext-tideways fetched from the previously configured remote package repository:

{
    "require": {
        "php": "7.0.*",
        "ext-tideways": "@stable"
    },
    "config": {
        "platform": {
            "ext-tideways": "1.0.0"
        }
    }
}

The config.platform setting ensures that even without the extension installed on your local computer, a composer update will not complain about the missing extension.

Re-run Composer to generate the changes to a new lock file:

composer update ext-tideways --ignore-platform-reqs

Commit the changes and push your application to re-deploy:

git add composer.json composer.lock
git commit -m 'Add ext-tideways dependency to Heroku app'
git push heroku master

To enable Tideways on your Heroku app you still need to configure API Key, framework and sample rate as environment variables:

heroku config:set TIDEWAYS_APIKEY="abcdefg" TIDEWAYS_FRAMEWORK="symfony2" TIDEWAYS_SAMPLERATE="20"

You can find your API Key for your Tideways application from the dropdown menu entry "Application Settings".

As a last step you can (optionally) enable the deploy tracking, again on the "Application Settings" screen by clicking on Heroku in the Integrations section. It will show a command to activate a deployhook addon that looks like the following:

 heroku addons:create deployhooks:http --url="https://app.tideways.io/api/events/heroku/....."

Configure API-Key

The last step before we can start collecting data is the configuration of the ApiKey for Tideways. Pick your preferred way to do this. We recommend configuration using php.ini, which requires no code-changes.

PHP INI Setting

Add the following line to your php.ini:

tideways.api_key=<YOUR_API_KEY>
tideways.sample_rate=25
tideways.framework=<OPTIONAL, SEE BELOW>

Don't forget to restart your webserver after the changes to php.ini file!

php-fpm Environment

If you want to have different Tideways settings per PHP-FPM Pool configuration, open up your php-fpm.conf or an included child configuration file to add:

# /etc/php5/fpm/php-fpm.conf
env[TIDEWAYS_APIKEY]=<YOUR_API_KEY>
env[TIDEWAYS_SAMPLERATE]=25
env[TIDEWAYS_FRAMEWORK]=<OPTIONAL; See Below>

Don't forget to restart php-fpm after the changes to php-fpm.conf

Nginx Environment

If you only have one PHP-FPM pool, but multiple sites running and using this Pool, then you can configure the Tideways settings in Nginx Vhosts:

location ~ .php$ {
    ...
    fastcgi_param TIDEWAYS_APIKEY "<YOUR_API_KEY>";
    fastcgi_param TIDEWAYS_SAMPLERATE "25";
    fastcgi_param TIDEWAYS_FRAMEWORK "<OPTIONAL; See Below>";
    ...
}

Search for the location section in your Vhost that contains the fastcgi configuration and add the fastcgi_param TIDEWAYS_APIKEY line.

Apache Environment

If you have mod_php running on Apache with multiple applications, then configuration should be done on the Apache webserver level, either in .htaccess or directly in the VHOST.

# .htaccess
SetEnv TIDEWAYS_APIKEY <YOUR_API_KEY>
SetEnv TIDEWAYS_SAMPLERATE 25
SetEnv TIDEWAYS_FRAMEWORK <OPTIONAL; See Below>

Don't forget to restart your webserver after the changes to php.ini file!

PHP

If you want programmatic control over Tideways Profiling, or use it inside Worker scripts, React.PHP or with HHVM, then you can directly start profiling from PHP using the Tideways Profiler API.

<?php
// bootstrap.php

if (class_exists('Tideways\Profiler')) {
    \Tideways\Profiler::start(array(
        'api_key' => 'YOUR API KEY',
        'sample_rate' => 25,
        'framework' => 'OPTIONAL; See below',
    ));
}

Tideways automatically stops when the request shuts down. If you are profiling multiple traces in a single PHP request, then you can force this step manually:

<?php

if (class_exists('Tideways\Profiler')) {
    \Tideways\Profiler::stop();
}

Framework Configuration

Tideways groups traces from the same controller or script into Transactions. Unconfigured the data is collected wit a transaction named default.

The profiler can auto-detect the transaction name if you work with one of the following frameworks/applications:

  • Symfony 2 FrameworkBundle with symfony2
  • Symfony 2 Components with symfony2c
  • Zend Framework 1 with zend1
  • Zend Framework 2 with zend2
  • Laravel with laravel
  • Oxid with oxid
  • Shopware with shopware
  • Magento 1 with magento
  • Magento 2 with magento2
  • PrestaShop 1.6 with presta16
  • Wordpress with wordpress
  • Drupal 8 with drupal8
  • FLOW Framework with flow
  • TYPO3 CMS with typo3
  • Yii and Yii 2 with yii or yii2
  • CakePHP 2 and 3 with cake2 or cake3

Add this in your Tideways configuration (INI or Nginx or Apache or PHP-FPM or PHP) in the framework configuration setting as shown above.