Skip to content

Latest commit

 

History

History
48 lines (41 loc) · 3.15 KB

README.md

File metadata and controls

48 lines (41 loc) · 3.15 KB
Raw

marklogic-telemetry

Telemetry is a MarkLogic Roxy Plugin that provides a simple means of capturing and displaying metrics about your application and how it's being used. Out of the box it provides:

  • Metrics on how many users are hitting the application over time, including which users are most active
  • Metrics on the number of documents in the system over time
  • Metrics about the activities happening in the app, including the activity duration (elapsed time), overall activity over time, and the number of times each activity is performed over a specific timeframe

Installation

  • Extract directly on top of your Roxy src directory.
    • Note: this project contains a version of ./roxy/router.xqy !
      • If you maintain your own ./roxy/router.xqy file, it is important that this file contain the changes that call this line:
tl:track(xdmp:get-current-user(), $controller-path || ":" || $func || "." || $format, $request-time, xdmp:elapsed-time())
  • Edit your roxy project's ./deploy/ml-config.xml file and add the indexes from the following sample file:
    • ./deploy/ml-config.telemetry
  • Edit src/app/config/telemetry-config.xqy with your application-specific settings.
  • Re-deploy your application code using Roxy's deploy tasks:
    • ./ml <env> bootstrap
    • ./ml <env> deploy modules
  • Create a scheduled task with the following settings:
    • task path: /scheduled-tasks/collect-telemetry-data.xqy
    • task root: /
    • task type: hourly
    • task period: 1
    • task database: <your app's db name>
    • task modules: <your app's modules>
    • task user: admin
    • task host:
    • task priority: normal

Scheduled Task

The scheduled task runs every hour and collects the user metrics and cleans up any metrics gathered older than age limit. See AGE-LIMIT

Telemetry Config File

The ./app/config/telemetry-config.xqy file contains options used to customize the application to work within your target environment. Below is a table containing some of the important/configurable settings:

Value Description
PORT The port your application server. Must have the telemetry code deployed to the target modules DB/filesystem.
AGE-LIMIT The xs:DayTimeDuration for how long metrics will be retained and searchable within the database. It is recommened not to exceed 365 days.
CLEANUP-LOCATION The filesystem location on all ML Cluster hosts where older metrics will be removed from the DB and written to disk (see AGE-LIMIT.) If left blank, older data is permanently deleted.
DOCUMENT-COLLECTION General document collection used to display ingest rate statistics in Telemetry UI. Should match a generic collection that is tagged on all documents within your database.
DOCUMENT-DATE-FIELD An element reference to a dateTime indexed value within the ingested documents which is used to show ingest metrics within the Telemetry UI.
HTTP-OPTIONS XML section used to pass credentials for invoking the external REST endpoints on all ML Cluster hosts.