This page describes how to define information points for PHP applications.

Information points reflect key performance metrics and custom metrics for methods and code data points that you configure.

About PHP Information Points

To create an information point for PHP:

  1. Define the information point using JSON notation.
  2. In the definition, specify the method for the information point 
  3. Optionally, specify a point in the code that you want to capture as a custom metric, such as a parameter value or return value. 
  4. Navigate to More > Information Points and add an information point. 
  5. Choose PHP as the agent type and then paste the definition into the information point text box.

The elements of the definition correspond to configuration options available in the Add Information Point dialog for Java or .NET applications.

However, for PHP, the information point is defined in JSON syntax, and there are a few limits on configuration options. For one, class matching is limited to classname-based matches only. (Superclass matching or annotation matching are not available.) Also, you can only define a single match condition on a matched method. (A match condition refines the match of a method by testing a parameter or return value.)

If you do not configure a custom metric, the information point captures the generic KPIs for a matched method (response time, calls and calls per minute, errors an errors per minute). Custom metrics extend the information point by capturing the return or parameter value of a method, or the value of an invoked object.   

Before Starting

To create information points in the Controller UI, you need to be logged in as a user with Configure Information Points permissions. See Create and Manage Custom Roles. 

Method Match Conditions

A match definition specifies the method associated with the value you want to capture as an information point. The match definition must specify the method, but it may also specify the containing class and a refining match condition. The match condition can test the value of a method parameter, return value, or the return value of an invoked object.

Use this template to create a match definition:

{
  "probe": {
    "phpDefinition": {
      "classMatch": {
        "type": "MATCHES_CLASS",
        "classNameCondition": {
          "type": "EQUALS",
          "matchStrings": [
            "<class name>"
          ]
        }
      },
      "methodMatch": {
        "methodNameCondition": {
          "type": "EQUALS",
          "matchStrings": [
            "<method name>"
          ]
        }
      }
    }
  }
}

Edit the JSON objects in the following way:

  • classMatch is optional. If you do not want to specify a class to match, delete the classMatch object from the phpDefinition object.
  • If you are using the class match, set the value for the classNameCondition match string to the class name.
    • The class must be defined as a separate file from the file in which it is instantiated and invoked.
    • If your class names are defined in a namespace, escape the backslashes in the namespace with an escape backslash.
  • methodMatch is required. Set the value for the methodNameCondition match string to the method name.

The following values are required for PHP information points:

  • classMatch type: MATCHES_CLASS
  • classNameCondition type: EQUALS
  • methodNameCondition type: EQUALS

For example, the following JSON creates an information point on a class for which the class name equals CheckoutManager and the method name processPayment:

{
  "probe": {
    "phpDefinition": {
      "classMatch": {
        "type": "MATCHES_CLASS",
        "classNameCondition": {
          "type": "EQUALS",
          "matchStrings": [
            "Bundy\\ShoesBundle\\Entity\\CheckoutManager"
          ]
        }
      },
      "methodMatch": {
        "methodNameCondition": {
          "type": "EQUALS",
          "matchStrings": [
            "processPayment"
          ]
        }
      }
    }
  }
}

If creating an information point primarily to capture KPI metrics for the method, it is likely you will define the class for the method. However, if you are creating an information point to implement a code metric, you may only need to specify method name matching.

This example shows a method match that tracks how many times a method is called:

{
  "probe": {
    "phpDefinition": {
      "methodMatch": {
        "methodNameCondition": {
          "type": "EQUALS",
          "matchStrings": [
            "deleteCartItems"
          ]
        }
      }
    }
  }
}

Match Conditions

A match condition (defined by a matchConditions object) lets you refine the method matching criteria by specifying a match condition based on a parameter or return value or the value returned by an invoked object. 

A match condition is optional, but there can be at most one for the information point. If you do not supply a match condition, the information point includes all invocations of the matched method. 

The condition consists of a match type and the comparison operator that defines the data to be compared. The match types are:

  • EQUALS
  • NOT_EQUALS
  • LT
  • GT
  • LE 
  • GE
  • NOT
  • AND
  • OR

The comparison operator is an expression node that defines a left side (lhs) and a right side (rhs) of the operation. It contains: 

  • a type: ENTITY, STRING, or INTEGER
  • a value, which is an entityValue, stringValue, or integerValue

If the type is ENTITY, the entityValue has one of the following types: INVOKED_OBJECT, RETURN_VALUE, or PARAMETER. If the type of the entityValue is PARAMETER, the parameterIndex indicates the 0-based numeric index of the parameter on which to match. So if the method takes two parameters, for example, the first being a string and second an integer, a parameterIndex of 0 matches against the string and a parameterIndex of 1 matches the integer value.

The information point in the following example only matches invocations of the processPayment method in which the second parameter (at parameter index 1) equals VISA.

{
  "probe": {
    "phpDefinition": {
      "methodMatch": {
        "methodNameCondition": {
          "type": "EQUALS",
          "matchStrings": [
            "processPayment"
          ]
        },
        "matchCondition": {
          "type": "EQUALS",
          "comparisonOp": {
            "lhs": {
              "type": "ENTITY",
              "entityValue": {
                "type": "PARAMETER",
                "parameterIndex": 1
              }
            },
            "rhs": {
              "type": "STRING",
              "stringValue": "VISA"
            }
          }
        }
      }
    }
  }
}

Metric Definitions

You can define custom metrics for data captured by an information point using the metricDefinitions object in your information point definition. Custom metrics appear in the Metric Browser and in the dashboard for the information point. You can create health rules based on a custom metric and retrieve custom metric values using the AppDynamics REST API.

There can be multiple custom metrics for a single information point. For example, one metric might be based on the average and one on the accumulated (sum) of the information point's values.

A metricDefinitions object consists of one or more definitions, each having the following structure:

  • a name
  • a rollup type (AVERAGE or SUM)
  • data, which consists of a type, (ENTITY, STRING, or INTEGER) and a value (entityValue, stringValue, or integerValue)

If the type is ENTITY, the entityValue has a type, which is INVOKED_OBJECT, RETURN_VALUE, or PARAMETER. If the type of the entityValue is PARAMETER, the zero-based parameterIndex indicates the parameter on which to base the match. A return value or parameter metric cannot be an array. 

For example, the following metricDefinitions object defines two custom metrics: VisaTotal, which reports the sum of the Visa payments processed and VisaAverage, which reports the average value of the Visa payments processed.

"metricDefinitions": [
    {
      "name": "VisaTotal",
      "rollup": "SUM",
      "data": {
        "type" : "ENTITY",
        "entityValue": {
          "type": "RETURN_VALUE"
        }
      }
    },
    {
      "name": "VisaAverage",
      "rollup": "AVERAGE",
      "data": {
        "type" : "ENTITY",
        "entityValue": {
          "type": "RETURN_VALUE"
        }
      }
    }
    
  ]

Sample JSON Information Point Configuration

This is an example that you can copy and paste into the JSON text field in the PHP information point window. It produces two metrics, named VisaTotal and VisaAverage.

{
  "probe": {
    "phpDefinition": {
      "classMatch": {
        "type": "MATCHES_CLASS",
        "classNameCondition": {
          "type": "EQUALS",
          "matchStrings": [
            "CheckOutManager"
          ]
        }
      },
      "methodMatch": {
        "methodNameCondition": {
          "type": "EQUALS",
          "matchStrings": [
            "processPayment"
          ]
        },
        "matchCondition": {
          "type": "EQUALS",
          "comparisonOp": {
            "lhs": {
              "type": "ENTITY",
              "entityValue": {
                "parameterIndex": 1,
                "type": "PARAMETER"
              },
              "rhs": {
                "type": "STRING",
                "stringValue": "VISA"
              }
            }
          }
        }
      }
    }
  },
  "metricDefinitions": [
    {
      "name": "VisaTotal",
      "rollup": "SUM",
      "data": {
        "entityValue": {
          "type": "RETURN_VALUE"
        },
        "type": "ENTITY"
      }
    },
    {
      "name": "VisaAverage",
      "rollup": "AVERAGE",
      "data": {
        "type": "ENTITY",
        "entityValue": {
          "type": "RETURN_VALUE"
        }
      }
    }
  ]
}