Validate Realtime Services

How can I verify the Realtime API Service is up and available?

All Versions

Load the Realtime API URL into a web browser and validate that the Realtime API Splash page loads up. This is a good way to verify the version of RPI Realtime as well. The version of RPI Realtime should match exactly the version of the core RPI Server environment:

How can I verify the Realtime API Service has a successful connection to the memory cache? 

RPI Realtime Version 4.5 and newer:

Refer to the 'Validate the connection' section in the linked article. The section in the referenced article details how to leverage the /api/Status/Cache/{CacheName} endpoint to view information about the state of the Realtime API's connection to the memory cache. If the Realtime API is unable to connect to the memory cache, the response from this endpoint should provide an error message describing why the connection is failing.

RPI Realtime Version 4.4 and earlier:

Load the /RPIVisitors/CacheStatus.aspx endpoint into a browser. If the 'Web Cache Status' table is populated with values then it's a good indication the Realtime API service's connection to the memory cache is good:

How can I verify the Realtime API Service has a successful connection to the message queues? 

RPI Realtime Version 4.5 and newer:

Refer to the 'Advanced Validation' section in the linked article. The section in the referenced article gives details on how to leverage the status endpoint to get a true/false indicator as to whether or not the Realtime api is able to connect to the respective queues. If the Realtime API cannot successfully connect to either or both message queues, there should be an error message providing more detail around the failed connection.

RPI Realtime Version 4.4 and earlier:

Load the  /RPIVisitors/CacheStatus.aspx endpoint into a browser. If the Realtime API has a successful connection to the queue provider, you should see a table like the one below:

How can I verify the Realtime Agent is up and available?

Load the Realtime Agent API URL into a web browser and validate that the Realtime Agent API Splash page loads up. This is a good way to verify the version of RPI Realtime Agent as well. The version of RPI Realtime Agent should match exactly the version of the core RPI Server environment:

How can I verify the Realtime API  is able to successfully connect to the Realtime Agent?

Refer to the 'Advanced Validation' section in the linked article for instructions on using the Realtime status endpoint (/api/Status). The response to this endpoint will give you a true/false indicator of whether or not the Realtime API can connect to the Realtime agent.

How can I verify the Realtime agent is able to successfully connect to the RPI Warehouse or AuxDB?

The easiest way to do this is to...

1. configure a test Cached Attribute List (CAL) pointing to a key and at least one attribute from a table in the database you wish to test - Set the CAL to 'Always fetch from database'
2. set a parameter mapping under "ParameterToDataMappings" in the Realtime api appsettings.json.config that points to this CAL
3. Enable Realtime Agent logging (see section below)
4. Make a request to the /api/Cache/Visit endpoint, passing a Visitor attribute in the request payload with a name that matches the parameter setup in ParameterToDataMappings and a value for a record within the database that you're testing (ensuring the record has an column mapped by the test CAL created above)

Once the request has completed, you can validate by viewing both the Server Log and the SQL trace log for entries indicating a successful query:

Server & Client Log

You'll see a sequence of informational messages culminating with one that reads 'Data fetch complete'. Here is an example:

SQL Trace Log

The query issued to satisfy the CAL request should be logged, Here is an example:

How can I verify the Realtime agent is able to successfully connect to the operational databases?

The procedure from above for validating the database connection using a CAL effectively also serves to validate the connection to RPI operational database, as the agent needs to be able to establish connections to these databases in order to write the server and query log information.

Realtime Agent Logging

To enable Realtime Agent logging, modify the 'TraceLogEnabled' setting in the Realtime Agents web.config file by setting the value to 'True'

Realtime API Logging

Logging can be enabled by editing the "Logging" section of the Realtime API's appsettings.json.config file. By default, RPI ships with all logging turned off, and turning on logging comes with a performance penalty so use judicially:

• Set the File.LogLevel.Default property to "Trace" (full set of options can be found in the admin guide, in the section "appsettings.json Configuration File" → "Logging")
• Make sure the FileLogging.LogDirectory property is set to a path that exists on the server where the Realtime API is running

Here is an example of what a log file with full tracing looks like. One of the particularly useful pieces of information that is logged is the web visitor cache profile. Here is a sample visitor profile:

A few notes on the entry above:

• In the 'Values' array, the entries with the unique GUIDs are RPI Realtime managed parameters, and the ones with the placeholder GUIDs that looks like this '00000000-0000-0000-0000-000000000000' are realtime parameters that have been added from the web site tracking code (e.g., via URL parameters).
  ?

  "Values": [   {     "n": "Number of visits",     "i": "fe7e61b1-dfc8-492a-a452-ed727a3f0c22",     "u": "2019-12-11T13:25:12.3748768-05:00",     "iLE": "False",     "v": "1",     "vfmt": "int"   },   {     "n": "Language",     "i": "6930beb7-ce98-4b8a-a00b-2bfd8fe0757d",     "u": "2019-12-11T13:25:12.3788687-05:00",     "iLE": "False",     "v": "English (United States)",     "vfmt": "str"   },   {     "n": "Region",     "i": "1945768d-7970-4e6c-aa4c-91c336f784df",     "u": "2019-12-11T13:25:12.3788687-05:00",     "iLE": "False",     "v": "United States",     "vfmt": "str"   },   {     "n": "product_affinity",     "i": "00000000-0000-0000-0000-000000000000",     "u": "2020-01-07T08:32:42.7505231-05:00",     "iLE": "True",     "v": "SKI",     "vfmt": "str"   },   {     "n": "pid",     "i": "00000000-0000-0000-0000-000000000000",     "u": "2020-01-07T08:24:04.6594226-05:00",     "iLE": "True",     "v": "50002",     "vfmt": "str"   } ],

• the 'DBVals' property contains values that have been sourced from the RPI datawarehouse or auxiliary DB and the date they were last refreshed.
  
  ?

  "DBVals": [   {     "n": "PRODUCT_AFFINITY",     "d": "2020-01-07T08:32:42.8478139-05:00",     "v": [       "SKI"     ]   },   {     "n": "MARITAL_STATUS",     "d": "2020-01-07T08:32:42.8478139-05:00",     "v": [       "Married"     ]   },   {     "n": "LOYALTY_LEVEL",     "d": "2020-01-07T08:32:42.8478139-05:00",     "v": [       "VIP ELITE"     ]   },   {     "n": "INCOME",     "d": "2020-01-07T08:32:42.8478139-05:00",     "v": [       "$125,000-$149,999"     ]   },   {     "n": "GENDER",     "d": "2020-01-07T08:32:42.8478139-05:00",     "v": [       "M"     ]   },   {     "n": "EDUCATION",     "d": "2020-01-07T08:32:42.8478139-05:00",     "v": [       "Bachelor Degree likely"     ]   } ]

• The 'Pages' array contains the name of the page ("n"), the publishID if it's a landing page ("pubid"), the # of visits ("noV"), and the last visit timestamp ("lV") in the properties.
  The child "dyn" array contains objects providing the following information: (1) GUIDs identifying any realtime dynamic assets on the page ("id"), and the index of which dynamic asset slot was rendered in the decision ("ix").
  ?

  "Pages": [    {      "n": "/",      "h": "retaildemo-local.rphelios.net",      "lV": "2020-01-07T08:32:42.8478139-05:00",      "lDec": "2020-01-07T08:32:42.9006723-05:00",      "pubid": 0,      "noV": 10,      "dyn": [        {          "id": "0f9d7581-2c66-497c-86d7-7487163beada",          "ix": "7"        },        {          "id": "5e7ace86-0a76-4c61-9530-169f16435531",          "ix": "1"        },        {          "id": "fa2693b9-8fbf-4874-9b32-5e4611d331a1",          "ix": "2"        },        {          "id": "e452c1fe-1e87-4ad9-bb78-a33a4547fbd5",          "ix": "10"        },        {          "id": "b28c0aa4-092b-4447-af55-fa05514d86f0",          "ix": "4"        }      ]    }  ],

• There is a "Decs" array of objects containing the GUID ("id"), results "r", name "n", and timestamp "d" of decisions that the visitor has been served:
  ?

  "Decs": [   {     "id": "0f9d7581-2c66-497c-86d7-7487163beada",     "r": 7,     "n": "J&J-SiteProdAffinity",     "d": "2020-01-07T08:32:42.8657663-05:00"   },   {     "id": "5e7ace86-0a76-4c61-9530-169f16435531",     "r": 1,     "n": "Hompage Promo",     "d": "2020-01-07T08:32:42.9006723-05:00"   },   {     "id": "fa2693b9-8fbf-4874-9b32-5e4611d331a1",     "r": 2,     "n": "Homepage Merchandising",     "d": "2020-01-07T08:32:42.8667636-05:00"   },   {     "id": "e452c1fe-1e87-4ad9-bb78-a33a4547fbd5",     "r": 10,     "n": "Homepage Hero",     "d": "2020-01-07T08:32:42.8996744-05:00"   },   {     "id": "b28c0aa4-092b-4447-af55-fa05514d86f0",     "r": 4,     "n": "Homepage Carousel",     "d": "2020-01-07T08:24:08.3423481-05:00"   } ]

What do to do if...

...database cached attribute are not being populated to the cache?

• Validate that the Realtime Agent is up and available 
• Check that the connection strings in the web.config file for the Realtime Agent is pointing to the correct ops db (Pulse) for the environment. If the 'Integrated Security' flag of the connection string is set to 'true', ensure that the account associated to the application pool running the Web Processor Service has sufficient privileges to the Pulse DB. Also make sure the app pool's identity account also has privileges to the warehouse or auxDB where the cached attributes reside.

• Ensure that the 'ParameterToDataMappings' configuration in the RealTime API's appsettings.json file has correctly mapped the web realtime parameter to the cached attribute list name.

  ?

  "ParameterToDataMappings": [   {     "ParameterName": "PID",     "CALName": "Person"   } ]

...the incorrect decision is being served by the realtime engine?

• Check that the Visitor exists in the cache and that the parameters used in the realtime dynamic assets RTD rules are populated with the expected values. Use the information from the logging section above to gain insight into what the visitor's profile looks like. 
• Keep in mind that visitor profiles are expired based on the setting 'DaysToPersist" configured in the "DataMaps" array in the appsettings.json.config file. The data map associated to the visitor is labelled "Visitor Profile":
  
  By default, this is set to 365 days, but it may have been changed and a information in the profile or the profile itself may be gone from the cache. 
• Verify that the memory cache has not reached full capacity. Most memory cache services will start expiring keys once full capacity is reached. 
• If the realtime decisions are being served from RPI generated landing pages, make sure that the system configuration parameter "EnableRPIRealtimeServices" has been set to "true" prior to publishing the landing page.  (Note, in earlier versions of RPI, this parameter was named "EnableDynamicContentTracking")

...web tracking, web cache, web form, or decision result data is not making it back to the RPI warehouse? 

• Check that the following RPI System Tasks are enabled and running successfully:
  • Web cache data importer
  • Web events importer
  • Web form processor
• Verify the configuration of the queue provider and queue names in both the RPI application configuration and the RPI Realtime API appsettings.json.config configuration file match exactly with each other.
• Make sure the appsettings.json.config property named 'CacheOutputQueueEnabled' is set to true
• Make sure the 'WebCacheOutputToDatabase' parameter is set to true in RPI System Configuration screen. 

Architecture Diagram