From 93e9762112b262c5351dce5c875d767b883d7df0 Mon Sep 17 00:00:00 2001
From: Tomas Jacik <tomas@jacik.cz>
Date: Mon, 8 Mar 2021 04:17:44 +0100
Subject: [PATCH] Updated DOCS

---
 .docs/README.md | 157 ++++++++++++++++++++++++++++++++----------------
 1 file changed, 104 insertions(+), 53 deletions(-)

diff --git a/.docs/README.md b/.docs/README.md
index 1cf36bd..4e4f496 100644
--- a/.docs/README.md
+++ b/.docs/README.md
@@ -3,40 +3,50 @@
 ## Content
 
 - [Setup](#setup)
-- [Usage](#usage)
+- [Configuration](#configuration)
 - [Realtime User Monitoring](#realtime-user-monitoring)
-- [Tracy](#tracy)
+- [Console](#console)
+- [Agent](#agent)
 
 ## Setup
 
-**Install package with composer:**
+Install package
 
-```
+```bash
 composer require contributte/newrelic
 ```
 
-**Register as nette extension:**
+Register extension
 
 ```yaml
 extensions:
   newrelic: Contributte\NewRelic\DI\NewRelicExtension
 ```
 
-## Usage
+## Configuration
+
+Basic configuration
 
 ```yaml
 newrelic:
-  enabled: true #default
-  appName: YourApplicationName #optional
-  license: yourLicenseCode #optional
-  logLevel: #defaults
+  enabled: true # true is default
+  # use false on dev when newrelic extension is not present
+  appName: YourApplicationName # optional, defaults to "PHP Application"
+```
+
+Full configuration with default values
+
+```yaml
+newrelic:
+  enabled: true
+  appName: PHP Application
+  license: ''
+  logLevel:
     - critical
     - exception
     - error
-
-  # optional options with default values
   rum:
-    enabled: auto # other options are true/false
+    enabled: auto
   transactionTracer:
     enabled: true
     detail: 1
@@ -47,82 +57,123 @@ newrelic:
     explainThreshold: 500
   errorCollector:
     enabled: true
-    recordDatabaseErrors: Yes
+    recordDatabaseErrors: true
   parameters:
     capture: false
     ignored: []
   custom:
-    parameters:
-      paramName: paramValue
-    tracers:
+    parameters: []
+    tracers: []
 ```
 
 ## Realtime User Monitoring
 
-Add this component factory to your base presenter:
+If config option `rum/enabled` is set to `auto` (default), NewRelic extension is handling adding
+of monitoring JS on its own. You can disable that behavior setting this option to `true` or `false`.
+In both cases, auto instrumentation is set off. If set to `false`, `Agent` class is returning empty
+string when calling `getBrowserTimingHeader()` and `getBrowserTimingFooter()` functions.
+
+To specify where these JS should be added, you can either add `RUMControlTrait` to your
+`BasePresenter` or create components your own way if you want to avoid adding `<script>` tags.
+If `rum/enabled` is se to `false`, these controls returns empty string.
 
 ```php
-/**
- * @var \Contributte\NewRelic\RUM\HeaderControl
- * @inject
- */
-protected $headerControl;
-
-/**
- * @var \Contributte\NewRelic\RUM\FooterControl
- * @inject
- */
-protected $footerControl;
-
-protected function createComponentNewRelicHeader()
-{
-    $this->headerControl->disableScriptTag(); // optional
-    return $this->headerControl;
-}
+<?php
+
+declare(strict_types=1);
+
+use Contributte\NewRelic\RUM\HeaderControl;
+use Contributte\NewRelic\RUM\FooterControl;
+use Contributte\NewRelic\RUM\RUMControlFactory;
 
-protected function createComponentNewRelicFooter()
+abstract class BasePresenter extends \Nette\Application\UI\Presenter
 {
-    $this->footerControl->disableScriptTag(); // optional
-    return $this->footerControl;
+
+    /**
+     * @var RUMControlFactory
+     * @inject
+     */
+    protected $rumControlFactory;
+
+    protected function createComponentNewRelicHeader(): HeaderControl
+    {
+        // Adding true avoid adding <script> tags
+        return $this->rumControlFactory->createHeader(true);
+    }
+
+    protected function createComponentNewRelicFooter(): FooterControl
+    {
+        // Adding true avoid adding <script> tags
+        return $this->rumControlFactory->createFooter(true);
+    }
+
 }
 ```
 
-And add this to your `@layout` header (before `</head>`):
+To your `@layout` template add `newRelicHeader` component before `</head>` tag.
 
 ```smarty
 {control newRelicHeader}
 ```
 
-And add this to your `@layout` footer (before `</body>`):
+To your `@layout` template add `newRelicFooter` compenent before `</body>` tag.
 
 ```smarty
 {control newRelicFooter}
 ```
 
 ## Console
+
 This step is not necessary, but recommended as it will give you a nice formated data even for console commands.
-You will need to add two packages, [contributte/console](https://github.com/contributte/console) and [contributte/event-dispatcher](https://github.com/contributte/event-dispatcher).
-```bash
-composer require contributte/console
-```
 
-```yaml
-extensions:
-  console: Contributte\Console\DI\ConsoleExtension(%consoleMode%)
-```
+You will need to add [contributte/console](https://github.com/contributte/console) and [contributte/event-dispatcher](https://github.com/contributte/event-dispatcher) packages.
 
 ```bash
-composer require contributte/event-dispatcher
+composer require contributte/console contributte/event-dispatcher
 ```
 
+And register them.
+
 ```yaml
 extensions:
   events: Contributte\EventDispatcher\DI\EventDispatcherExtension
+  console: Contributte\Console\DI\ConsoleExtension(%consoleMode%)
+  newrelic.console: Contributte\NewRelic\DI\NewRelicConsoleExtension
 ```
 
-Last step is registration of `NewRelicConsoleExtension`.
+## Agent
 
-```yaml
-extensions:
-  newrelic.console: Contributte\NewRelic\DI\NewRelicConsoleExtension
+If you want to communicate with NewRelic extension, you can use autowired [Agent](../src/Agent/ProductionAgent.php)
+class, which wraps all NewRelic extension functions. If config options `enabled` is set to `false`,
+NewRelic native functions are not called, so it's great for development environments where NewRelic
+extension may not be installed.
+
+For example, if you want to add your logged-in user id as custom parameter:
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use Contributte\NewRelic\Agent\Agent;
+
+abstract class BasePresenter extends \Nette\Application\UI\Presenter
+{
+
+    /**
+     * @var Agent
+     * @inject
+     */
+    private $newRelicAgent;
+
+    protected function startup(): void
+    {
+        parent::startup();
+
+        if ($this->getUser()->isLoggedIn()) {
+            $this->newRelicAgent->addCustomParameter('userId', $this->getUser()->getId());
+        }
+    }
+
+}
 ```