How to Use Palzin Monitor with PHP

Palzin Monitor is a powerful application performance monitoring tool that helps you identify and resolve performance issues in your PHP applications. This guide will walk you through the steps to install, configure, and use Palzin Monitor in your PHP application.

Step 1: Installation

To start using Palzin Monitor in your PHP application, you need to install the Palzin Monitor PHP package using Composer. Open your terminal or command prompt and run the following command in a fresh directory:

composer require palzin-apm/palzin-php

This command will download and install the Palzin Monitor PHP package along with its dependencies.

Step 2: Create a Palzin Monitor Instance

Once the package is installed, you need to create an instance of the Palzin class by providing the ingestion key. The ingestion key is used to identify your project in Palzin Monitor. Here's an example of how to create a Palzin Monitor instance:

require __DIR__ . '/vendor/autoload.php';

use Palzin\Configuration;
use Palzin\Palzin;

// Create a configuration instance.
$configuration = new Configuration('YOUR_INGESTION_KEY');

// Pass the configuration to the Palzin Monitor constructor.
$palzin = new Palzin($configuration);

Make sure to replace 'YOUR_INGESTION_KEY' with your actual ingestion key, which you can obtain by signing up for Palzin Monitor.

Step 3: Instrument Your Application

Now that you have created a Palzin Monitor instance, you can start instrumenting your PHP application to monitor its performance. The following sections will guide you through some common use cases.

Exception

Palzin Monitor provides monitoring of unhandled exceptions in your application. If you want to manually report an exception without blocking the execution of your code, you can use the following approach:

// Start a exception.
$ex = new Exception;
$palzin->reportException($ex);  

// Continue with your script...

Transactions

Transactions represent execution cycles in your application and can contain one or more segments. It is recommended to start a transaction as early as possible in your application to accurately measure the time it takes to fulfill a request. Typically, you would start a transaction in the entry point of your application, such as index.php. Here's an example:

// Start a transaction.
$palzin->startTransaction($_SERVER['REQUEST_URI']);

// Continue with your script...

Set Transaction Result

You can set the result of a transaction to indicate the outcome of the request, such as the HTTP status code. Here's an example:

// Set the result of the transaction.
$palzin->currentTransaction()->setResult(200);

Add Context

You can enrich each transaction with additional information to provide more context about the execution process. This can be done by adding contextual information as tabs to the current transaction. Here's an example:

// Add context to the current transaction.
$palzin->currentTransaction()->addContext('label', ['foo' => 'bar']);

The contextual information will be reported as additional tabs in the transaction view in Palzin Monitor.

Global Availability of Palzin APM Instance

To make the Palzin APM instance available throughout your application, you can use an IoC container or a similar strategy. For example, if your application uses the PHP-DI container, you can register the Palzin APM instance in the container and retrieve it when needed. Here's an example:

// Register the Palzin APM instance in the container.
$container->set('palzin', $palzin);

// Retrieve the Palzin APM instance from the container.
$palzin = $container->get('palzin');

By making the Palzin APM instance available globally, you can easily add segments or interact with the current transaction from any part of your application.

Example: Monitoring a Contact Form Submission

Let's consider an example where you want to monitor the performance of a contact form submission in your PHP application. Here's how you can use Palzin Monitor to monitor the submission process:

// Start a transaction for the contact form submission.
$palzin->startTransaction('Contact Form');

// Process the contact form submission.
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    // Validate and sanitize form inputs
    $name = $_POST['name'];
    $email = $_POST['email'];
    $message = $_POST['message'];

    // Send the contact form data to the server or save it in a database
    // ...

    // Set the result of the transaction based on the outcome
    if ($success) {
        $palzin->currentTransaction()->setResult(200);
    } else {
        $palzin->currentTransaction()->setResult(500);
    }

    // Add context information to the transaction
    $context = [
        'Name' => $name,
        'Email' => $email,
        'Message' => $message,
    ];
    $palzin->currentTransaction()->addContext('Contact Form Submission', $context);
}

// Continue with the rest of your script...
?>

<!DOCTYPE html>
<html>
<head>
    <title>Contact Us</title>
</head>
<body>
    <h1>Contact Us</h1>
    <form method="POST" action="">
        <label for="name">Name:</label>
        <input type="text" id="name" name="name" required><br><br>

        <label for="email">Email:</label>
        <input type="email" id="email" name="email" required><br><br>

        <label for="message">Message:</label>
        <textarea id="message" name="message" required></textarea><br><br>

        <input type="submit" value="Submit">
    </form>
</body>
</html>

In this example, we start a transaction for the contact form submission, set the result based on the outcome (success or failure), and add the form data as context information to the transaction.

Conclusion

Congratulations! You have learned how to install, configure, and use Palzin Monitor with your PHP application. By instrumenting your application with Palzin Monitor, you can gain valuable insights into its performance and identify any issues that need attention. Happy monitoring!