Merge pull request #15903 from lavarou/feat/php/wordpress

feat(php): add `newrelic.framework.wordpress.hooks.options` description
newrelic · Jan 23, 2024 · 5867459 · 5867459
2 parents be60eef + 41b055c
commit 5867459
Show file tree

Hide file tree

Showing 2 changed files with 95 additions and 3 deletions.
diff --git a/src/content/docs/apm/agents/php-agent/configuration/php-agent-configuration.mdx b/src/content/docs/apm/agents/php-agent/configuration/php-agent-configuration.mdx
@@ -3216,6 +3216,92 @@ The values of these settings are used to control various tracer features.
     To enable WordPress hook tracking, set this to `true`. It will enable the recording of WordPress hooks, plugins, and themes, and they will display under the [**WordPress**](/docs/agents/php-agent/frameworks-libraries/wordpress-specific-functionality) tab in the New Relic UI.
   </Collapser>
 
+  <Collapser
+    id="inivar-framework-wordpress-hooks-options"
+    title="newrelic.framework.wordpress.hooks.options"
+  >
+    <table>
+      <tbody>
+        <tr>
+          <th>
+            Scope:
+          </th>
+
+          <td>
+            PERDIR
+          </td>
+        </tr>
+
+        <tr>
+          <th>
+            Type:
+          </th>
+
+          <td>
+            String
+          </td>
+        </tr>
+
+        <tr>
+          <th>
+            Default:
+          </th>
+
+          <td>
+            `"all_callbacks"`
+          </td>
+        </tr>
+      </tbody>
+    </table>
+    Sets the options how WordPress hooks are instrumented. 
+    New Relic agent can provide different levels of insights into WordPress hooks.
+    By default, all hook callbacks functions are instrumented ("all_callbacks").
+    To reduce agent's overhead it is possible to limit the instrumentation to only
+    plugin/theme callbacks ("plugin_callbacks"). Third option is to monitor hooks
+    without instrumenting callbacks ("threshold"). This option does not give insights
+    about plugins/themes. Read more about WordPress specific instrumentation [here](/docs/agents/php-agent/frameworks-libraries/wordpress-specific-functionality).
+  </Collapser>
+
+  <Collapser
+    id="inivar-framework-wordpress-hooks-threshold"
+    title="newrelic.framework.wordpress.hooks.threshold"
+  >
+    <table>
+      <tbody>
+        <tr>
+          <th>
+            Scope:
+          </th>
+
+          <td>
+            PERDIR
+          </td>
+        </tr>
+
+        <tr>
+          <th>
+            Type:
+          </th>
+
+          <td>
+            Duration
+          </td>
+        </tr>
+
+        <tr>
+          <th>
+            Default:
+          </th>
+
+          <td>
+            `1ms`
+          </td>
+        </tr>
+      </tbody>
+    </table>
+    Sets the threshold above which the New Relic agent will record WordPress hook execution. Used when newrelic.framework.wordpress.hooks.options is set to "threshold".
+  </Collapser>
+
   <Collapser
     id="inivar-wt-files"
     title="newrelic.webtransaction.name.files"

diff --git a/.../apm/agents/php-agent/frameworks-libraries/wordpress-specific-functionality.mdx b/.../apm/agents/php-agent/frameworks-libraries/wordpress-specific-functionality.mdx
@@ -20,14 +20,20 @@ You can control which WordPress-specific metrics your app sends to New Relic by
 newrelic.framework.wordpress.hooks = false
 ```
 
-Although this setting uses the word `.hooks`, it controls all WordPress metrics sent to New Relic, including hooks, plugins, and themes.
+Although this setting uses the word `.hooks`, it controls capturing all WordPress-specific metrics.
+
+New Relic PHP Agent version 10.16 adds `newrelic.framework.wordpress.hooks.options` `ini` setting that allows to fine tune which WordPress-specific metricsand what data is sent in those metrics.
+This setting accepts following values: `"all_callbacks"`, `"plugin_callbacks"`, and `"threshold"`. By default, all hook callback functions are instrumented (`newrelic.framework.wordpress.hooks.options="all_callbacks"`).
+`"plugin_callbacks"` and `"threshold"` settings allow to reduce agent's overhead by fine tuning data collected by the agent. Setting `newrelic.framework.wordpress.hooks.options` to `"plugin_callbacks"`
+limits the instrumentation to only plugin/theme callbacks. Setting `newrelic.framework.wordpress.hooks.options` to `"threshold"` disables plugins/themes monitoring and in this mode of operation
+New Relic PHP agent only records execution of hooks that exceed `newrelic.framework.wordpress.hooks.threshold` (1ms is the default threshold).
 
 ## Metrics
 
 The PHP agent receives metrics for the following:
 
-* **Hooks**: These metrics indicate time spent within each WordPress hook. Time is calculated from the hook dispatch functions `apply_filters`, `apply_filters_ref_array`, `do_action`, and `do_action_ref_array`.
-* **Plugins and themes**: These metrics indicate time spent within each WordPress plugin and theme. Time is calculated from the dispatch functions for hooks.
+* **Hooks**: These metrics indicate time spent within each WordPress hook. Time is calculated from the hook dispatch functions `apply_filters`, `apply_filters_ref_array`, `do_action`, and `do_action_ref_array`. When `newrelic.framework.wordpress.hooks.options="all_callbacks"` this includes WordPress core callbacks. When `newrelic.framework.wordpress.hooks.options="plugin_callbacks"` this includes only plugins/themes callbacks. In both cases the metric count indicates the number of callbacks called. However when `newrelic.framework.wordpress.hooks.options="threshold"`, the metric count indicates the number of times a hook was executed.
+* **Plugins and themes**: These metrics indicate time spent within each WordPress plugin and theme. Time is calculated from the dispatch functions for hooks. This metric is only generated when `newrelic.framework.wordpress.hooks.options` is either `"all_callbacks"` or `"plugins_only"`.
 
 ## Integration with New Relic partners [#integration]