Before you Begin

The support for OpenTracing, an API and vendor-neutral instrumentation framework, allows application developers to instrument their application code and analyze the trace data in Oracle Cloud Infrastructure (OCI) Application Performance Monitoring (APM). This is an example of instrumentation of a PHP application using a Zipkin tracer.

Concepts

Distributed tracing is a method used to profile and monitor applications. This method is especially used to monitor applications built using a microservices architecture. OpenTracing is an open-source project that provides vendor-neutral APIs and instrumentation for distributed tracing. It allows developers to add instrumentation to their application code using APIs.

Application Performance Monitoring consumes telemetry data collected by OpenTracing and provides information on requests, through various microservices or functions. Therefore, APM allows real end user monitoring and complete analysis of the impact of services on the overall end-user digital experience.

Our Scenario

In this example, we are using a sample PHP application with two PHP services that collaborate on an HTTP request. This application is using Zipkin PHP, the official PHP Tracer implementation for Zipkin supported by the OpenZipkin community. Our application requests timing is recorded into Zipkin, a distributed tracing system that APM supports. The recorded data allows you to see each operation timing as well as how much time was spent in each service. This is the data that we will upload to APM for visualization and further analysis.

Prerequisites

Composer is a tool for dependency management in PHP. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you. These libraries are managed on a per-project basis, installing them in a directory inside your project. Composer was installed with the sample application used in this case.

Let's see how you can upload Zipkin PHP collected data to APM!

Step 1: Create an APM Domain

  1. Sign in to the Oracle Cloud Infrastructure console, open the navigation menu, and click Observability and Management. Under Application Performance Monitoring, click Administration:

    OCI Main Menu
    Description of the illustration apm.png
  2. Click Create APM Domain and enter the domain details:
    Create Menu
    Description of the illustration create.png

  3. Click on the domain you just created and make a note (copy/paste) of the domain values Data Upload Endpoint and private Datakey:

    Domain Details
    Description of the illustration domain_details.png

Step 2: Examine the Tracer Code

For PHP applications, functions.php calls a function named create_tracing that allows you to create a tracing component by passing the a custom zipkin server URL, the $httpReporterURL. Here is what this section of our functions.php file looks like by default:

              
function create_tracing($localServiceName, $localServiceIPv4, $localServicePort = null)
{
    $httpReporterURL = getenv('HTTP_REPORTER_URL');
    if ($httpReporterURL === false) {
        $httpReporterURL = 'http://localhost:9411/api/v2/spans';
    }

    $endpoint = Endpoint::create($localServiceName, $localServiceIPv4, null, $localServicePort);

Step 3: Customize the Tracer Code

Replace the default ReporterURL with the Data Upload Endpoint you noted earlier.

              
function create_tracing($localServiceName, $localServiceIPv4, $localServicePort = null)
{
    $httpReporterURL = getenv('HTTP_REPORTER_URL');
    if ($httpReporterURL === false) {
        $httpReporterURL = 'https://aaaacxxxxxxxxx.oci.oraclecloud.com/20200101/observations/public-span?dataFormat=zipkin&dataFormatVersion=2&dataKey=XXXXXXXXXXXXXXXX65BZFDOZ2NVHBZTX';
    }

    $endpoint = Endpoint::create($localServiceName, $localServiceIPv4, null, $localServicePort);

Step 4: Add Tags

    In our case, the frontend.php file of our app defines the HTTP request to the backend.

  1. Examine the frontend.php that looks like this: 
    /* HTTP Request to the backend */
$httpClient = new Client();
$request = new \GuzzleHttp\Psr7\Request('POST', 'localhost:9000', $headers);
$childSpan->annotate('request_started', Timestamp\now());
$response = $httpClient->send($request);
$childSpan->annotate('request_finished', Timestamp\now());

$childSpan->finish();

$span->finish();

  2. Add tags in this code block, after the childSpan->finish line: 
    /* HTTP Request to the backend */
$httpClient = new Client();
$request = new \GuzzleHttp\Psr7\Request('POST', 'localhost:9000', $headers);
$childSpan->annotate('request_started', Timestamp\now());
$response = $httpClient->send($request);
$childSpan->annotate('request_finished', Timestamp\now());

$childSpan->finish();
$childSpan->tag("HTTP_PATH", $request->getUri());
$childSpan->tag("HTTP_STATUS_CODE", "200");

$span->finish();

Step 5: View Data in Trace Explorer

We are now ready to view and analyze trace data in APM Trace Explorer.

  1. Start the sample application. In this case, the frontend runs in Terminal 1 and the backend runs in Terminal 2:

    # In terminal 1: composer run-frontend

    # In terminal 2 composer run-backend

  2. From the OCI main menu, navigate to Trace Explorer:
    OCI Main Menu
    Description of the illustration trace.png

  3. Select your compartment and domain and view all trace data, under the Traces tab:

    Trace Explorer
    Description of the illustration traceexplorer.png

  4. Click on any trace to view more details about it:

    Trace Details
    Description of the illustration tracedetails.png

  5. Under the span details we see the HTTP_PATH and HTTP_STATUS_CODE tags that we defined:

    Trace Details
    Description of the illustration span.png

Next Steps

An APM Browser Agent records user interaction with websites and sends browser spans and real user monitoring metrics to Application Performance Monitoring. These metrics can provide further insight into the real experience of your end users and identifies performance problems as your users navigate to your site from different web browsers and devices. For more information on how to deploy an APM Browser Agent, see Configure APM Browser Agent.

Learn More