Versions Compared

    Key

    • This line was added.
    • This line was removed.
    • Formatting was changed.
    Comment: Published by Scroll Versions from this space and version 20.7-next
    Sv translation
    languageen
    Appd tocbox
    Width340px
    Related pages:

    Information points reflect key performance metrics and custom metrics for methods and code data points that you configure. You can define information points for PHP applications as described in this topic.

    About PHP Information Points

    To create an information point for PHP, you first define the information point using JSON notation.

    In the definition, you specify the method for the information point and optionally a point in the code that you want to capture as a custom metric, such as a parameter value or return value. 

    After creating the definition, add an information point in the More > Information Points page in the Controller UI. When adding the information point, choose PHP as the agent type and then paste the definition into the information point text box, as shown in the following screenshot:

    Essentially, the elements of the definition correspond to configuration options available in the Add Information Point dialog box 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, for example, 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 Roles and Permissions for more information. 

    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 the following template to create a match definition:

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

    Edit the JSON objects as follows:

    • 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 is 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:

    No Format
    {
      "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.

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

    No Format
    {
      "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: ENTITYSTRING, or INTEGER
    • a value, which is an entityValuestringValue, or integerValue

    If the type is ENTITY, the entityValue has one of the following types: INVOKED_OBJECTRETURN_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.

    No Format
    {
      "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.

    No Format
    "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.

    No Format
    {
      "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"
            }
          }
        }
      ]
    }
    Sv translation
    languageja
    Appd tocbox
    Width340px
    On this page:

    Table of Contents
    maxLevel2
    minLevel2

    Related pages:

    インフォメーションポイントは、ユーザーが構成したメソッドとコードデータポイントのKPIメトリックとカスタムメトリックを反映します。PHPアプリケーションのインフォメーションポイントは、このトピックの説明に従って定義できます。

    PHPのインフォメーションポイントについて

    PHP のインフォメーションポイントを作成するには、最初に JSON 表記を使用してインフォメーションポイントを定義します。

    この定義では、インフォメーションポイント用のメソッドと、オプションでカスタムメトリックとしてキャプチャするコード内のポイント(パラメータ値や戻り値など)を指定します。 

    定義を作成したら、コントローラ UI の More > Information Points ページでインフォメーションポイントを追加します。インフォメーションポイントを追加するときに、エージェントタイプとして [PHP] を選択し、以下のスクリーンショットに示すように、インフォメーションポイントのテキストボックスに定義を貼り付けます。

    Java または .NET アプリケーションの場合、定義の要素は基本的に [Add Information Point] ダイアログボックスで利用可能な構成オプションに対応しています。

    しかし、PHP ではインフォメーションポイントが JSON 構文で定義されるため、構成オプションにいくつかの制限があります。1 つは、クラスの一致がクラス名ベースの一致のみに制限されることです(スーパークラスの一致や注釈の一致などは使用できません)。また、一致するメソッドに対して 1 つの一致条件しか定義できません(一致条件でパラメータ値または戻り値を検査することにより、メソッドの一致を絞り込みます)。

    カスタムメトリックを構成しない場合、インフォメーションポイントは、一致したメソッドの包括的な KPI(応答時間、コール数、1 分あたりのコール数、エラー数、1 分あたりのエラー数)をキャプチャします。カスタムメトリックは、メソッドの戻り値、メソッドのパラメータ値、または呼び出されたオブジェクトの値をキャプチャすることで、インフォメーションポイントを拡張します。   

    はじめに

    コントローラ UI でインフォメーションポイントを作成するには、Configure Information Points 権限を持つユーザとしてログインする必要があります。詳細については、「Roles and Permissions」を参照してください。 

    メソッドの一致条件

    一致の定義は、インフォメーションポイントとしてキャプチャする値に関連付けられたメソッドを指定します。一致の定義では、メソッドを必ず指定しますが、メソッドを含むクラスと絞り込み用の一致条件を指定することもできます。一致条件によって、メソッドパラメータの値、戻り値、または呼び出されたオブジェクトの戻り値を検査できます。

    以下のテンプレートを使って一致の定義を作成します。

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

    これらのJSONオブジェクトを次のように編集します。

    • classMatchはオプション。一致するクラスを指定しない場合は、phpDefinition オブジェクトから classMatch オブジェクトを削除。
    • クラスの一致を使用する場合、classNameCondition 一致文字列の値をクラス名に設定。
      • クラスは、インスタンス化され呼び出されたファイルとは別のファイルとして定義されていること。
      • クラス名がネームスペースに定義される場合、エスケープバックスラッシュでネームスペースのバックスラッシュをエスケープ。
    • methodMatchは必須。methodNameCondition 一致文字列の値をメソッド名に設定。

    PHPのインフォメーションポイントでは、以下の値が必要です。

    • classMatch タイプ: MATCHES_CLASS
    • classNameCondition タイプ: EQUALS
    • methodNameCondition タイプ: EQUALS

    たとえば、以下の JSON はクラス名が CheckoutManager、メソッド名が processPayment と等しいクラスにインフォメーションポイントを作成します。

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

    主にメソッドの KPI メトリックをキャプチャする目的でインフォメーションポイントを作成する場合は、メソッドのクラスを定義します。しかし、コードメトリックを実装するためにインフォメーションポイントを作成する場合は、一致するメソッド名を指定するだけで済みます。

    次の例は、メソッドの呼び出し回数を追跡するメソッド一致を示しています。

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

    一致条件

    matchConditions オブジェクトで定義される)一致条件を使用して、パラメータ値、戻り値、または呼び出されたオブジェクトから返された値に基づく一致条件を指定することで、メソッドの一致基準を絞り込むことができます。 

    一致条件はオプションですが、インフォメーションポイントに1つだけ設定できます。一致条件を設定しない場合、インフォメーションポイントには一致したメソッドのすべての呼び出しが含まれます。 

    条件は、一致タイプと、比較するデータを定義する比較演算子で構成されます。一致タイプは以下のとおりです。

    • EQUALS
    • NOT_EQUALS
    • LT
    • GT
    • LE 
    • GE
    • 以下ではありません。
    • および
    • または

    比較演算子は、演算の左辺(lhs)と右辺(rhs))を定義する式ノードです。これには次のものが含まれます。

    • タイプ:ENTITYSTRING、または INTEGER
    • 値:entityValuestringValue、または integerValue

    タイプが ENTITY の場合、entityValue には INVOKED_OBJECTRETURN_VALUE、または PARAMETER のいずれかのタイプが含まれています。entityValue のタイプが PARAMETER の場合、parameterIndex は照合するパラメータのゼロベースの数値インデックスを示します。たとえば、メソッドが 2 つのパラメータ(1 つ目が文字列、2 つ目が整数)を取る場合、parameterIndex を 0 にすると文字列と照合され、parameterIndex を 1 にすると整数値と照合されます。

    次の例のインフォメーションポイントは、(パラメータインデックス 1 の)2 つ目のパラメータが VISA と等しい processPayment メソッドの呼び出しとのみ一致します。

    No Format
    {
      "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"
                }
              }
            }
          }
        }
      }
    }

    メトリックの定義

    インフォメーションポイントによってキャプチャされるデータのカスタムメトリックを定義するには、インフォメーションポイント定義で metricDefinitions オブジェクトを使用します。カスタムメトリックは、メトリックブラウザと、インフォメーションポイントのダッシュボードに表示されます。AppDynamics REST APIを使用して、カスタムメトリックに基づいた正常性ルールを作成し、カスタムメトリック値を取得できます。

    1つのインフォメーションポイントに複数のカスタムメトリックがあることも可能です。例えば、平均に基づくメトリックと、インフォメーションポイントの集計値(合計)に基づくメトリックを使用できます。

    metricDefinitions オブジェクトは 1 つ以上の定義で構成され、各定義は以下のような構造になっています。

    • 名前
    • ロールアップタイプ(平均または合計)
    • タイプ(ENTITY、STRING、またはINTEGER)と値(entityValue、stringValue、またはintegerValue)からなるデータ

    タイプがENTITYの場合、entityValueにはINVOKED_OBJECT、RETURN_VALUE、またはPARAMETERのいずれかのタイプが含まれています。entityValueがPARAMETERの場合、ゼロベースのparameterIndexは一致の対象となるパラメータを示します。戻り値およびパラメータメトリックは配列にはできません。 

    たとえば以下の metricDefinitions オブジェクトは、2 つのカスタムメトリック(処理された Visa の支払い合計を報告する VisaTotal と、処理された Visa の支払いの平均値を報告する VisaAverage)を定義します。

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

    JSONインフォメーションポイントの構成サンプル

    以下の例は、PHPインフォメーションポイントウィンドウのJSONテキストフィールドにコピーして貼り付けられます。VisaTotalVisaAverage という名前の 2 つのメトリックが作成されます。

    No Format
    {
      "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"
            }
          }
        }
      ]
    }